settings.json di Claude Code: agent teams, hook e marketplace di plugin

🎯 Dove vive settings.json e perché conta

Claude Code legge la configurazione da tre livelli, dal più generale al più specifico: ~/.claude/settings.json vale per tutto ciò che faccio sulla macchina; .claude/settings.json dentro un progetto è condiviso nel repository con il team; .claude/settings.local.json resta sulla mia macchina e non finisce sotto version control. Quando la stessa chiave compare in più file, vince il livello più specifico.

La regola pratica che seguo: impostazioni personali e segreti stanno nel file utente o in quello .local, mentre nel repo committo solo ciò che ha senso condividere — hook di progetto, plugin attivi, permessi. Qui sotto c'è il mio file utente, con il token GitHub e i percorsi oscurati: le quattro sezioni evidenziate sono quelle che spiego nei prossimi paragrafi.

👥 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: la modalità squadra

È una feature sperimentale: la attivo mettendo la variabile a "1" dentro env. Sblocca gli agent teams, cioè più sessioni di Claude Code che lavorano insieme come una squadra invece di un singolo agente. Una sessione fa da team lead, coordina e distribuisce il lavoro; le altre — i teammate — lavorano in parallelo, ciascuna con la propria finestra di contesto.

La differenza con i subagent è sostanziale: i subagent riportano solo al capo e non si parlano tra loro, mentre in un agent team i membri condividono una task list, si assegnano il lavoro e comunicano direttamente. È potente quando spacchetto un task grande in parti indipendenti, ma richiede l'accesso a Opus e un minimo di disciplina. Essendo sperimentale, la attivo quando serve e la spengo quando lavoro da solo.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

🛠️ toolSearch: quando spegnerlo

Con tanti server MCP collegati, gli strumenti disponibili diventano centinaia e ognuno occupa contesto. Il Tool Search è l'ottimizzazione che carica gli strumenti on demand quando superano una certa soglia della finestra, invece di tenerli tutti caricati. Di default è attivo e fa risparmiare token.

Metto toolSearch: false quando voglio il comportamento opposto: tutti gli strumenti MCP precaricati all'avvio, senza il passaggio di ricerca. Ha senso se uso sempre gli stessi pochi server e preferisco latenza zero alla partenza, a costo di un po' più di contesto consumato. È un compromesso, non una regola: di solito lo lascio attivo, lo spengo solo su setup leggeri.

{
  // false = precarica tutti gli strumenti MCP all'avvio
  "toolSearch": false
}

🚀 hooks.Stop: uno script alla fine di ogni turno

Gli hook eseguono comandi in punti precisi del ciclo di vita dell'agente. Quello che uso di più è Stop: scatta ogni volta che Claude Code finisce di rispondere. Il matcher a "" dice «vale per ogni stop», e dentro ho un solo handler di tipo *command che lancia uno script di shell con un timeout di 300 secondi.

Nel mio caso lo script è auto-end-of-session.sh: a fine sessione riassume e salva la conversazione in Obsidian. Qui mi fermo alla configurazione — cosa fa davvero lo script, e come costruirlo come plugin con i comandi /salva-session, lo spiego nell'articolo collegato. Il punto è solo questo: un hook Stop ti dà un gancio affidabile per automatizzare ciò che deve succedere alla fine.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/auto-end-of-session.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

🐙 extraKnownMarketplaces: i tuoi cataloghi di plugin

Un marketplace è un catalogo di plugin: un repo con un file JSON che elenca cosa è installabile. Con extraKnownMarketplaces registro cataloghi non ufficiali direttamente in settings.json — qui, ad esempio, il superpowers-marketplace preso da GitHub indicando solo source e repo.

Il bello è che il marketplace può essere il mio: un repo GitHub, anche privato, dove pubblico i miei comandi come plugin installabile su qualsiasi macchina. Registrarlo qui (o con un comando) significa che Claude Code lo conosce e può installarne i plugin. Come si crea da zero un marketplace personale e ci si mette dentro un plugin — da remoto, non da locale — è il tema dell'articolo collegato qui sotto.

{
  "extraKnownMarketplaces": {
    "superpowers-marketplace": {
      "source": {
        "source": "github",
        "repo": "obra/superpowers-marketplace"
      }
    }
  }
}

✅ Applicare e verificare le modifiche

Dopo aver toccato settings.json, le modifiche si leggono all'avvio della sessione: riavvio Claude Code o ne apro una nuova. Per controllare che tutto sia attivo uso i comandi giusti: /hooks mostra gli hook caricati, /plugin gestisce marketplace e plugin, /config apre le impostazioni.

Un errore comune è mettere un segreto nel file di progetto versionato: i token vanno nel file utente o in .local. E se un hook non scatta, quasi sempre è un path sbagliato o un permesso mancante sullo script — non un problema di Claude.

Altri articoli del blog