Orchestrare team di sessioni Claude Code

Coordinare più istanze di Claude Code che lavorano insieme come un team, con attività condivise, messaggistica tra agenti e gestione centralizzata.

[!WARNING]

I team di agenti sono sperimentali e disabilitati per impostazione predefinita. Abilitateli impostando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 nel vostro settings.json o nell'ambiente. Senza quella variabile, nessun team viene configurato all'avvio della sessione, nessuna directory di team viene scritta, e Claude non genera o propone compagni di team. I team di agenti hanno limitazioni note relative alla ripresa della sessione, al coordinamento delle attività e al comportamento di arresto.

I team di agenti vi permettono di coordinare più istanze di Claude Code che lavorano insieme. Una sessione agisce come il team lead, coordinando il lavoro, assegnando attività e sintetizzando i risultati. I compagni di team lavorano indipendentemente, ognuno nel proprio context window, e comunicano direttamente tra loro. Potete anche parlare direttamente con qualsiasi compagno di team senza passare attraverso il lead.

Prima di configurare un team, verificate se un'opzione più leggera fa il lavoro. I Subagents lavorano all'interno di una singola sessione, e con la messaggistica tra sessioni Claude può passare i risultati tra le sessioni che eseguite voi stessi.

Quando utilizzare i team di agenti

I team di agenti sono più efficaci per attività in cui l'esplorazione parallela aggiunge valore reale. Consultate gli esempi di casi d'uso per scenari completi. I casi d'uso più forti sono:

• Ricerca e revisione: più compagni di team possono investigare diversi aspetti di un problema simultaneamente, quindi condividere e mettere in discussione i risultati reciproci
• Nuovi moduli o funzionalità: i compagni di team possono possedere ciascuno un pezzo separato senza interferire l'uno con l'altro
• Debug con ipotesi concorrenti: i compagni di team testano diverse teorie in parallelo e convergono sulla risposta più velocemente
• Coordinamento tra livelli: modifiche che si estendono su frontend, backend e test, ciascuno posseduto da un diverso compagno di team

I team di agenti aggiungono overhead di coordinamento e utilizzano significativamente più token di una singola sessione. Funzionano meglio quando i compagni di team possono operare indipendentemente. Per attività sequenziali, modifiche dello stesso file o lavoro con molte dipendenze, una singola sessione o i subagents sono più efficaci.

Confronto con i subagents

Sia i team di agenti che i subagents vi permettono di parallelizzare il lavoro, ma operano diversamente. Per sessioni separate che si passano messaggi l'una con l'altra senza un team, consultate la messaggistica tra sessioni.

I subagents riportano i risultati al main agent. Nei team di agenti, i compagni di team condividono un elenco di attività, rivendicano il lavoro e comunicano direttamente tra loro.

Utilizzate i subagents quando avete bisogno di worker veloci e focalizzati che riportino indietro. Utilizzate i team di agenti quando i compagni di team devono condividere i risultati, mettersi in discussione e coordinarsi autonomamente.

Abilitare i team di agenti

I team di agenti sono disabilitati per impostazione predefinita. Abilitateli impostando la variabile di ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1, sia nell'ambiente della shell che tramite settings.json:

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

L'abilitazione dei team di agenti modifica anche la delega ordinaria. Claude può denominare un subagente autonomamente, e mentre i team di agenti sono abilitati, un subagente che Claude denomina si avvia come un compagno di squadra, quindi i team possono formarsi anche quando non ne avete richiesto uno. Per ulteriori informazioni, consultate Come Claude avvia i team di agenti; per disattivare il comportamento, consultate Claude genera compagni di squadra invece di subagenti.

L'avvio di compagni di squadra richiede anche una sessione interattiva. In modalità non interattiva con il flag -p, incluse le sessioni di Agent SDK, Claude non genera compagni di squadra, e un subagente che Claude denomina viene eseguito come un ordinario subagente anche con i team di agenti abilitati.

Avvia il tuo primo team di agenti

Dopo aver abilitato i team di agenti, descrivi in linguaggio naturale l'attività e i compagni di team che desideri. Claude li genera e coordina il lavoro in base al tuo prompt.

Questo esempio funziona bene perché i tre ruoli sono indipendenti e possono esplorare il problema senza doversi aspettare a vicenda:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

A quel punto, Claude popola un elenco di attività condiviso in una sessione che dispone degli strumenti Task, genera compagni di team per ciascuna prospettiva, fa loro esplorare il problema e sintetizza i risultati al termine.

A volte Claude potrebbe usare dei subagent invece di creare un team. I subagent compaiono nello stesso pannello degli agenti dei compagni di team, quindi il pannello da solo non conferma che si sia formato un team. Se Claude ha generato dei subagent, chiedi di nuovo e richiedi esplicitamente un team di agenti.

Il terminale del lead elenca i compagni di team nel pannello degli agenti sotto l'input del prompt. Dal pannello:

• Frecce su e giù: seleziona un compagno di team
• Enter: apri la trascrizione del compagno di team selezionato e inviagli direttamente un messaggio
• Escape: annulla la selezione. Mentre visualizzi la trascrizione di un compagno di team, Escape interrompe il turno corrente di quel compagno di team

La riga di un compagno di team inattivo rimane nel pannello finché un qualsiasi compagno di team o subagent è ancora al lavoro, così puoi selezionarla per rivedere la sua trascrizione o assegnargli altro lavoro. Quando tutti gli agenti nel pannello sono inattivi, le righe inattive si nascondono dopo 30 secondi e ricompaiono al turno successivo del compagno di team; il compagno di team resta in esecuzione e raggiungibile anche mentre è nascosto.

Quando più di tre compagni di team sono inattivi contemporaneamente, le righe successive alle prime tre vengono compresse in un'unica riga che conta i compagni di team compressi, ad esempio 2 idle agents quando cinque sono inattivi. Selezionala e premi Enter per espandere le righe compresse, oppure premi Esc per comprimerle di nuovo. I compagni di team al lavoro, quelli con errori e il compagno di team che stai visualizzando mantengono sempre la propria riga.

Se vuoi ogni compagno di team in un proprio riquadro diviso, consulta Scegli una modalità di visualizzazione.

Controllare il tuo team di agenti

Comunica al lead ciò che desideri in linguaggio naturale. Si occupa del coordinamento del team, dell'assegnazione delle attività e della delega in base alle tue istruzioni.

Scegliere una modalità di visualizzazione

I team di agenti supportano due modalità di visualizzazione:

• In-process: tutti i compagni di squadra vengono eseguiti all'interno del tuo terminale principale. Usa i tasti freccia su e giù nel pannello degli agenti per selezionare un compagno di squadra, poi premi Enter per visualizzarlo e digita per inviargli messaggi direttamente. Funziona in qualsiasi terminale, senza alcuna configurazione aggiuntiva.
• Riquadri divisi: ogni compagno di squadra ha il proprio riquadro. Puoi vedere l'output di tutti contemporaneamente e fare clic su un riquadro per interagire direttamente. Richiede tmux o iTerm2.

[!NOTE]

tmux ha limitazioni note su alcuni sistemi operativi e tradizionalmente funziona meglio su macOS. L'uso di tmux -CC in iTerm2 è il punto di ingresso consigliato per tmux.

Il valore predefinito è "in-process". Imposta "auto" per abilitare i riquadri divisi quando stai già eseguendo all'interno di una sessione tmux, oppure quando il tuo terminale è iTerm2 con la CLI it2 installata, ripiegando su in-process negli altri casi. L'impostazione "tmux" abilita la modalità a riquadri divisi e rileva automaticamente se usare tmux o iTerm2 in base al tuo terminale.

Imposta "iterm2" per usare esplicitamente i riquadri divisi nativi di iTerm2. Questa modalità richiede la CLI it2 e mostra un errore con il comando di installazione se it2 manca. La richiesta di configurazione che propone di installare it2 o di passare a tmux compare con "auto" o "tmux" quando il tuo terminale è iTerm2 e tmux è disponibile come fallback.

Per sovrascrivere il valore predefinito, imposta teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Per impostare la modalità per una singola sessione, passala come flag:

claude --teammate-mode auto

Il flag --teammate-mode è sperimentale e non compare in claude --help.

La modalità a riquadri divisi richiede tmux oppure iTerm2 con la CLI it2. Per installarli manualmente:

• tmux: installalo tramite il gestore di pacchetti del tuo sistema. Consulta il wiki di tmux per le istruzioni specifiche per piattaforma.
• iTerm2: installa la CLI it2, poi abilita la Python API in iTerm2 → Settings → General → Magic → Enable Python API.

Specificare compagni di squadra e modelli

Claude decide il numero di compagni di squadra da generare in base alla tua attività, oppure puoi specificare esattamente ciò che desideri:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code sceglie il modello di ciascun compagno di squadra dalla prima delle seguenti fonti applicabile:

1. Il modello che il tuo prompt di generazione indica per quel compagno di squadra.
2. Per un compagno di squadra generato da una definizione di subagent, il model della definizione, dove inherit seleziona il modello del lead.
3. CLAUDE_CODE_SUBAGENT_MODEL, quando è impostata su un valore diverso da inherit.
4. Il modello corrente del lead.

Se un mod installato imposta un modello nel suo hook agent.spawn, Claude Code usa quel modello al posto della prima fonte.

Se imposti CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, le prime due fonti non si applicano. Claude Code sceglie il modello di ogni compagno di squadra da CLAUDE_CODE_SUBAGENT_MODEL quando è impostata su un valore diverso da inherit, e altrimenti dal modello corrente del lead. Richiede Claude Code v2.1.257 o successiva.

Prima della v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL veniva per prima in questo ordine.

[!NOTE]

teammateDefaultModel è stato rimosso nella v2.1.234; Claude Code ignora un eventuale valore residuo. Indica invece il modello nel tuo prompt.

Claude Code verifica il modello che seleziona per un compagno di squadra rispetto all'allowlist availableModels della tua organizzazione. Quando l'allowlist blocca un valore, Claude Code lo sostituisce con un altro modello:

• Alias di famiglia come opus: sull'API Anthropic e su Claude Platform on AWS, Claude Code esegue il compagno di squadra sulla versione più recente di quella famiglia consentita dall'allowlist. Sui provider con ID di modello specifici del provider, dove la sostituzione non opera, un alias bloccato usa il fallback come qualsiasi altro valore bloccato, secondo il punto successivo
• Qualsiasi altro valore bloccato, incluso un alias di famiglia sui provider dove la sostituzione non opera, o uno la cui famiglia non ha alcuna versione consentita: Claude Code esegue invece il compagno di squadra sul modello del lead. Se imposti CLAUDE_CODE_SUBAGENT_MODEL, Claude Code prova prima quel modello, secondo queste stesse regole

Per impostazione predefinita, un compagno di squadra sul modello del lead eredita il livello di sforzo del lead. Nella modalità a riquadri divisi questo si applica dalla v2.1.186; le versioni precedenti non passavano il livello di sforzo della sessione del lead ai compagni di squadra nei riquadri divisi. Per un compagno di squadra su un altro modello, consulta Livello di sforzo di subagent e compagni di squadra.

Far pianificare i compagni di squadra prima dell'implementazione

Per attività complesse o rischiose, puoi far pianificare i compagni di squadra prima dell'implementazione. Un compagno di squadra che Claude genera mentre il lead è in plan mode lavora anch'esso in plan mode finché il suo piano non è pronto. Porta prima il lead in plan mode, poi chiedi il compagno di squadra:

Spawn an architect teammate to refactor the authentication module.

Quando quel compagno di squadra termina la pianificazione, invia una richiesta di approvazione del piano al lead. Se non hai cambiato la modalità di permesso di quel compagno di squadra da quando è stato generato, Claude Code approva il piano non appena arriva la richiesta, senza che il lead lo esamini. Una volta approvato, il compagno di squadra esce dal plan mode e inizia l'implementazione. Claude Code gli passa la modalità di permesso corrente del lead, oppure Manual se questa è il plan mode.

Se metti in plan mode un compagno di squadra in-process in esecuzione premendo Shift+Tab mentre visualizzi la sua sessione, è il lead a esaminare il piano di quell'esecuzione invece che Claude Code ad approvarlo. Non ti viene chiesto di approvarlo; il lead lo approva o lo rimanda indietro per una revisione.

Parlare direttamente con i compagni di squadra

Ogni compagno di squadra è una sessione Claude Code completa e indipendente. Puoi inviare messaggi direttamente a qualsiasi compagno di squadra per dare istruzioni aggiuntive, porre domande di approfondimento o reindirizzare il suo approccio.

• Modalità in-process: usa i tasti freccia su e giù nel pannello degli agenti per selezionare un compagno di squadra, poi premi Enter per visualizzare la sua sessione e digita per inviargli un messaggio. Premi x su un compagno di squadra selezionato per fermarlo. Premi Ctrl+T per mostrare o nascondere l'elenco delle attività.
• Modalità a riquadri divisi: fai clic sul riquadro di un compagno di squadra per interagire direttamente con la sua sessione. Ogni compagno di squadra ha una visualizzazione completa del proprio terminale.

Mentre visualizzi un compagno di squadra in-process, il testo semplice e le skill vanno a quel compagno di squadra, mentre i comandi integrati vanno alla sessione del lead, con queste salvaguardie:

• /compact, /clear e /rewind agiscono sulla conversazione del lead, quindi Claude Code ti chiede di confermare prima di eseguirne uno da questa visualizzazione.
• /model e /fast impostano il modello e la modalità veloce del lead, non del compagno di squadra, quindi non vengono eseguiti da questa visualizzazione. Un avviso te ne spiega il motivo.

Il modello e la modalità veloce di un compagno di squadra sono fissati al momento della sua generazione.

Assegnare e rivendicare le attività

L'elenco condiviso delle attività coordina il lavoro all'interno del team. Il lead crea le attività e i compagni di squadra le portano a termine. Le attività hanno tre stati: in sospeso, in corso e completata. Un'attività può anche dipendere da altre attività e risulta bloccata nell'elenco delle attività finché queste non sono completate. I compagni di squadra non rivendicano autonomamente un'attività bloccata, ma tu o il lead potete comunque assegnarla.

Gli agenti senza gli strumenti Task si coordinano invece tramite messaggi anziché tramite l'elenco condiviso delle attività.

Il lead può assegnare le attività esplicitamente, oppure i compagni di squadra possono rivendicarle autonomamente:

• Assegnazione da parte del lead: indica al lead quale attività affidare a quale compagno di squadra
• Rivendicazione autonoma: dopo aver terminato un'attività, un compagno di squadra prende da solo la successiva attività non assegnata e non bloccata

La rivendicazione delle attività usa il blocco dei file per evitare race condition quando più compagni di squadra cercano di rivendicare la stessa attività contemporaneamente.

Arrestare i compagni di squadra

Per terminare in modo ordinato la sessione di un compagno di squadra, fai riferimento a lui per nome. Ad esempio, con un compagno di squadra chiamato researcher:

Ask the researcher teammate to shut down

Il lead invia una richiesta di arresto. Il compagno di squadra può approvarla, uscendo in modo ordinato, oppure rifiutarla con una spiegazione.

Le directory condivise del team vengono ripulite automaticamente al termine della sessione, quindi non c'è un passaggio di pulizia separato. Consulta Architettura per sapere quali directory vengono rimosse e quali restano sul disco.

Applicare controlli di qualità con gli hook

Usa gli hook per applicare regole quando i compagni di squadra terminano il lavoro o quando le attività vengono create o completate:

• TeammateIdle: viene eseguito quando un compagno di squadra sta per diventare inattivo. Esci con codice 2 per inviare un feedback e mantenere il compagno di squadra al lavoro.
• TaskCreated: viene eseguito quando un'attività viene creata. Esci con codice 2 per impedirne la creazione e inviare un feedback.
• TaskCompleted: viene eseguito quando un'attività viene contrassegnata come completata. Esci con codice 2 per impedirne il completamento e inviare un feedback.

Come funzionano i team di agenti

Questa sezione descrive l'architettura e i meccanismi alla base dei team di agenti. Se vuoi iniziare a usarli, consulta Controlla il tuo team di agenti più sopra.

Come Claude avvia i team di agenti

Per avviare un team, chiedi a Claude dei compagni di squadra. Claude avvia un compagno di squadra quando chiama lo strumento Agent con un name mentre i team di agenti sono abilitati, a meno che la chiamata non sia un fork o non passi isolation nella chiamata stessa. Claude Code non ti chiede di confermare l'avvio.

Claude assegna anche un nome ai subagent ordinari di propria iniziativa, in modo da poter inviare loro messaggi in seguito. Queste chiamate seguono la stessa regola, quindi i team possono formarsi anche quando non ne hai richiesto uno. Se invece vuoi dei subagent, disattiva i team di agenti.

Architettura

Un team di agenti è composto da:

La casella di posta di ciascun agente è un file JSON in ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code convalida ogni voce quando legge un file di casella di posta. Le voci che non corrispondono al formato dei messaggi vengono segnalate come errori e rimosse dal file; i messaggi validi vengono comunque recapitati.

Claude Code segnala un messaggio come inviato solo quando la scrittura nel file della casella di posta del destinatario va a buon fine, sia che il messaggio sia testo semplice sia che si tratti di un messaggio di protocollo strutturato come un'approvazione del piano o una richiesta di arresto. Quando la scrittura non riesce, ad esempio perché il disco è pieno o la directory della casella di posta non è scrivibile, l'agente mittente riceve un errore e non viene inviato nulla. Consulta Failed to write to a teammate's inbox per i messaggi di errore e i passaggi di ripristino.

Claude Code gestisce automaticamente le dipendenze tra le attività: quando un compagno di squadra completa un'attività da cui dipendono altre attività, sblocca le attività dipendenti senza alcun intervento da parte tua.

I team e le attività vengono archiviati localmente con un nome derivato dalla sessione. Il nome è session- seguito dai primi otto caratteri dell'ID della sessione:

• Configurazione del team: ~/.claude/teams/{team-name}/config.json. Claude Code rimuove la directory di configurazione del team al termine della sessione.
• Elenco delle attività: ~/.claude/tasks/{team-name}/. Questa directory rimane sul disco dopo la fine della sessione. Per modificare per quanto tempo Claude Code la conserva, imposta cleanupPeriodDays.

Claude Code genera entrambi automaticamente all'avvio della sessione e li aggiorna man mano che i compagni di squadra si uniscono, diventano inattivi o se ne vanno.

La configurazione del team contiene lo stato di runtime, come gli ID delle sessioni e gli ID dei pannelli tmux, quindi non modificarla a mano e non crearla in anticipo: le tue modifiche vengono sovrascritte al successivo aggiornamento dello stato.

Per definire ruoli riutilizzabili per i compagni di squadra, usa invece le definizioni dei subagent.

La configurazione del team contiene un array members con il nome e l'ID agente di ciascun membro. La voce del lead ha sempre il tipo di agente team-lead. La voce di un compagno di squadra riporta il tipo di agente indicato dal lead al momento della creazione, che si tratti di un tipo integrato o di una definizione di subagent, e omette il campo quando il lead non ne ha indicato nessuno. I compagni di squadra possono leggere questo file per scoprire gli altri membri del team.

Non esiste un equivalente a livello di progetto della configurazione del team. Un file come .claude/teams/teams.json nella directory del tuo progetto non viene riconosciuto come configurazione; Claude lo tratta come un file ordinario.

Usa le definizioni dei subagent per i compagni di squadra

Quando crei un compagno di squadra in una qualsiasi delle due modalità di visualizzazione, puoi fare riferimento a un tipo di subagent dall'ambito dei subagent di progetto, utente, gestito o di plugin. In questo modo puoi definire un ruolo una sola volta, ad esempio un security-reviewer o un test-runner, e riutilizzarlo sia come subagent delegato sia come compagno di squadra in un team di agenti.

Per usare una definizione di subagent, indicala per nome quando chiedi a Claude di creare il compagno di squadra:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Claude Code legge la definizione di subagent che hai indicato e ne applica al compagno di squadra le parti seguenti. Quando una parte dipende dalla modalità di visualizzazione del compagno di squadra, la voce lo specifica:

• tools: Claude Code limita il compagno di squadra agli strumenti presenti nell'elenco tools della definizione. Per un compagno di squadra in-process, Claude Code aggiunge SendMessage a tale elenco e, in una sessione che dispone degli strumenti Task, aggiunge anche TaskCreate, TaskGet, TaskList e TaskUpdate.
• model: Claude Code usa il model della definizione in entrambe le modalità di visualizzazione quando il tuo prompt di creazione non ne indica uno. Consulta come Claude Code sceglie il modello di un compagno di squadra.
• disallowedTools: per un compagno di squadra in-process, Claude Code rimuove dall'insieme del compagno di squadra gli strumenti indicati in disallowedTools della definizione. SendMessage e gli strumenti Task che aggiunge restano disponibili anche quando l'elenco li indica.
• effort: per un compagno di squadra in-process, Claude Code applica l'effort della definizione secondo le regole dell'effort nel frontmatter.
• autoCompactWindow: per un compagno di squadra in-process, Claude Code applica l'autoCompactWindow della definizione secondo le regole di quel campo. Un compagno di squadra a pannelli divisi ignora il campo. Richiede Claude Code v2.1.296 o versioni successive.
• Corpo: per un compagno di squadra in-process, Claude Code aggiunge il corpo della definizione al proprio prompt di sistema predefinito come istruzioni aggiuntive. Per un compagno di squadra a pannelli divisi, Claude Code usa il corpo al posto del proprio prompt di sistema predefinito.
• skills: Claude Code non applica le skills della definizione a un compagno di squadra in nessuna delle due modalità di visualizzazione. Il compagno di squadra carica le skill dalle impostazioni del tuo progetto e utente.
• mcpServers: per un compagno di squadra a pannelli divisi, Claude Code applica i mcpServers della definizione secondo le regole di quel campo, che riguardano anche una sessione avviata con --agent. Un compagno di squadra in-process ignora il campo e carica i server MCP dalle impostazioni del tuo progetto e utente.

Quando Claude invia un messaggio a un compagno di squadra in-process che non è più in esecuzione, Claude Code lo riattiva nella stessa sessione, ripristina l'eventuale conversazione salvata per esso e gli fornisce il messaggio come prompt successivo. Dopo aver ripreso una sessione, i compagni di squadra non vengono riattivati in questo modo, secondo la limitazione sulla ripresa.

Per un compagno di squadra che riattiva, Claude Code riapplica una definizione proveniente dalla directory .claude/agents/ di un progetto o da una directory --add-dir solo se hai considerato attendibile la cartella in cui si trova il file dell'agente. Considerare attendibile una cartella padre non conta. Fino ad allora, il compagno di squadra torna senza nessuno degli strumenti o delle istruzioni della definizione, mantenendo solo gli strumenti che Claude Code aggiunge a ogni compagno di squadra in-process. Consulta the teammate's agent definition was not restored per il testo dell'avviso.

Permessi

Per cambiare ciclicamente la modalità di permesso di un compagno di squadra in esecuzione, premi Shift+Tab, anche se un compagno di squadra in-process può invece essere eseguito nella modalità del lead. Per un compagno di squadra a pannelli divisi, premilo nel suo pannello. Per un compagno di squadra in-process, premilo mentre visualizzi la sua sessione: il compagno di squadra controlla la propria modalità quando inizia il turno successivo.

[!NOTE]

Un compagno di squadra in-process che non è in plan mode viene eseguito nella modalità del lead mentre il lead è in modalità acceptEdits, auto o bypassPermissions. Passare il compagno di squadra a Manual non cambia questo comportamento, anche se la sua barra di stato mostra Manual.

Per fare in modo che chieda conferma prima di modificare, premi Enter sulla riga main nel pannello degli agenti e passa anche il lead alla modalità Manual. A quel punto anche il lead chiede conferma, così come qualsiasi altro compagno di squadra in modalità Manual.

Non puoi impostare modalità di permesso specifiche per ciascun compagno di squadra al momento della creazione. Un nuovo compagno di squadra parte con la modalità del lead, inclusa la modalità bypassPermissions, che viene attivata da --dangerously-skip-permissions. Se il lead è in modalità dontAsk, il compagno di squadra parte invece in modalità Manual. Per un compagno di squadra a pannelli divisi di un lead in modalità Manual o dontAsk, questo richiede Claude Code v2.1.317 o versioni successive.

Un compagno di squadra in-process viene eseguito con le regole allow e deny attive del lead, quindi --disallowedTools, --tools e --allowedTools si applicano tutti a esso. Per un compagno di squadra a pannelli divisi, verifica ciascun flag:

• --disallowedTools e --tools: il compagno di squadra parte con le regole deny e l'elenco degli strumenti impostati dal lead nella riga di comando. Richiede Claude Code v2.1.309 o versioni successive.
• --allowedTools: Claude Code non passa questo flag a un compagno di squadra a pannelli divisi, quindi un'azione che hai consentito solo con esso non è preapprovata in quel compagno di squadra. Per approvare queste azioni in anticipo, inserisci le regole in permissions.allow in --settings quando avvii il lead. Ad esempio, esegui claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' nella tua shell. Le regole si applicano al lead e a ciascun compagno di squadra a pannelli divisi per quella sessione.

Le richieste di permesso dei compagni di squadra compaiono nella sessione del lead, quindi approvale lì personalmente. Non è necessario approvare il piano di un compagno di squadra.

Messaggi tra agenti

Quando un agente invia un messaggio a un altro tramite SendMessage, Claude Code comunica all'agente destinatario che il messaggio proviene da un'altra sessione di Claude, non da te. Un compagno di squadra non può approvare una richiesta di permesso né fornire il consenso per tuo conto, e un compagno di squadra a cui è stata negata un'azione non può inoltrarla a un altro compagno di squadra per aggirare il controllo. Le stesse regole si applicano a un messaggio che arriva da una delle tue altre sessioni di Claude Code, del tutto esterna al team.

In modalità auto, il classificatore applica due controlli ai messaggi tra agenti:

• Tratta un'affermazione di approvazione inoltrata da un altro agente come input non attendibile anziché come una tua conferma.
• Esamina ogni messaggio prima che Claude Code lo recapiti, che si tratti di un messaggio semplice o di un messaggio di protocollo strutturato come una richiesta di arresto o una risposta di approvazione del piano. Un messaggio che blocca non raggiunge mai il destinatario.

Contesto e comunicazione

Ogni compagno di squadra ha la propria finestra di contesto. Al momento della creazione, un compagno di squadra carica lo stesso contesto di progetto di una sessione normale: CLAUDE.md, server MCP e skill. Se avvii il lead con --setting-sources, i compagni di squadra caricano dallo stesso elenco ristretto di origini. Prima della v2.1.281, i compagni di squadra a pannelli divisi caricavano tutte le origini delle impostazioni.

Un compagno di squadra riceve anche il prompt di creazione dal lead. La cronologia della conversazione del lead non viene trasferita.

Come i compagni di squadra condividono le informazioni:

• Recapito automatico dei messaggi: quando i compagni di squadra inviano messaggi, questi vengono recapitati automaticamente ai destinatari. Il lead non deve controllare periodicamente la presenza di aggiornamenti.
• Notifiche di inattività: quando un compagno di squadra termina e si ferma, avvisa automaticamente il lead e include la propria risposta finale nella notifica. Un compagno di squadra il cui turno termina con un errore API avvisa il lead di non essere riuscito e include il testo dell'errore.
• Elenco delle attività condiviso: gli agenti che dispongono degli strumenti Task possono vedere lo stato delle attività e prendere in carico il lavoro disponibile.
• Messaggistica tra compagni di squadra: invia un messaggio a uno specifico compagno di squadra indicandone il nome. Per raggiungere tutti, invia un messaggio per ciascun destinatario.

Il lead assegna un nome a ogni compagno di squadra al momento della creazione, e qualsiasi compagno di squadra può inviare messaggi a qualsiasi altro usando quel nome. Per ottenere nomi prevedibili a cui fare riferimento nei prompt successivi, indica al lead come chiamare ciascun compagno di squadra nella tua istruzione di creazione.

Utilizzo dei token

I team di agenti usano molti più token di una singola sessione. Ogni compagno di squadra ha la propria finestra di contesto e l'utilizzo dei token cresce con il numero di compagni di squadra attivi. Per ricerca, revisione e sviluppo di nuove funzionalità, i token aggiuntivi di solito valgono la spesa. Per le attività abituali, una singola sessione è più conveniente. Consulta costi in token dei team di agenti per indicazioni sull'utilizzo.

Le richieste di un compagno di squadra in-process non rientrano nel bucket TTL della cache della conversazione principale, quindi la sua cache dura cinque minuti per impostazione predefinita, anche con un abbonamento Claude. Per mantenerla per un'ora, imposta subagentPromptCacheTtl su 1h. L'API addebita le scritture nella cache di 1 ora a una tariffa più elevata.

Esempi di casi d'uso

Questi esempi mostrano come i team di agenti gestiscono compiti in cui l'esplorazione parallela aggiunge valore.

Eseguire una revisione del codice parallela

Un singolo revisore tende a gravitare verso un tipo di problema alla volta. Dividere i criteri di revisione in domini indipendenti significa che la sicurezza, le prestazioni e la copertura dei test ricevono tutti un'attenzione approfondita simultaneamente. Il prompt assegna a ogni compagno di team una lente distinta in modo che non si sovrappongano:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Ogni revisore lavora dalla stessa PR ma applica un filtro diverso. Il lead sintetizza i risultati tra tutti e tre dopo che finiscono.

Investigare con ipotesi concorrenti

Quando la causa principale è poco chiara, un singolo agente tende a trovare una spiegazione plausibile e smettere di cercare. Il prompt combatte questo rendendo i compagni di team esplicitamente avversari: il lavoro di ognuno non è solo investigare la propria teoria ma sfidare le altre.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

La struttura del dibattito è il meccanismo chiave qui. L'investigazione sequenziale soffre di ancoraggio: una volta che una teoria è stata esplorata, l'investigazione successiva è distorta verso di essa.

Con più investigatori indipendenti che attivamente cercano di confutarsi a vicenda, la teoria che sopravvive è molto più probabile che sia la causa principale effettiva.

Best practices

Fornire ai compagni di team contesto sufficiente

I compagni di team caricano il contesto del progetto automaticamente, inclusi CLAUDE.md, MCP servers e skills, ma non ereditano la cronologia della conversazione del lead. Consultate Context e comunicazione per i dettagli. Includete i dettagli specifici dell'attività nel prompt di generazione:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Scegliere una dimensione del team appropriata

Non c'è un limite rigido al numero di compagni di team, ma si applicano vincoli pratici:

• I costi dei token si scalano linearmente: ogni compagno di team ha il proprio context window e consuma token indipendentemente. Consultate i costi dei token dei team di agenti per i dettagli.
• L'overhead di coordinamento aumenta: più compagni di team significa più comunicazione, coordinamento delle attività e potenziale per conflitti
• Rendimenti decrescenti: oltre un certo punto, i compagni di team aggiuntivi non accelerano il lavoro proporzionalmente

Iniziate con 3-5 compagni di team per la maggior parte dei flussi di lavoro. Questo bilancia il lavoro parallelo con il coordinamento gestibile. Se avete 15 attività indipendenti, 3 compagni di team è un buon punto di partenza.

Scalate solo quando il lavoro beneficia genuinamente dall'avere compagni di team che lavorano simultaneamente. Tre compagni di team focalizzati spesso superano cinque dispersi.

Dimensionare le attività appropriatamente

• Troppo piccole: l'overhead di coordinamento supera il beneficio
• Troppo grandi: i compagni di team lavorano troppo a lungo senza check-in, aumentando il rischio di sforzo sprecato
• Giuste: unità auto-contenute che producono un deliverable chiaro, come una funzione, un file di test o una revisione

[!TIP]

Il lead suddivide il lavoro in attività e le assegna ai compagni di team automaticamente. Se non sta creando abbastanza attività, chiedetegli di dividere il lavoro in pezzi più piccoli. Avere 5-6 attività per compagno di team mantiene tutti produttivi e permette al lead di riassegnare il lavoro se qualcuno rimane bloccato.

Aspettare che i compagni di team finiscano

A volte il lead inizia a implementare le attività stesso invece di aspettare i compagni di team. Se notate questo:

Wait for your teammates to complete their tasks before proceeding

Iniziare con ricerca e revisione

Se siete nuovi ai team di agenti, iniziate con compiti che hanno confini chiari e non richiedono di scrivere codice: revisionare una PR, ricercare una libreria o investigare un bug. Questi compiti mostrano il valore dell'esplorazione parallela senza le sfide di coordinamento che vengono con l'implementazione parallela.

Evitare conflitti di file

Due compagni di team che modificano lo stesso file porta a sovrascritture. Suddividete il lavoro in modo che ogni compagno di team possieda un set diverso di file.

Monitorare e sterzare

Controllate il progresso dei compagni di team, reindirizzate gli approcci che non funzionano e sintetizzate i risultati man mano che arrivano. Lasciare un team senza supervisione per troppo tempo aumenta il rischio di sforzo sprecato.

Risoluzione dei problemi

I teammate non compaiono

Se i teammate non compaiono dopo che hai chiesto a Claude di generarli:

• In modalità in-process, i teammate compaiono nel pannello degli agenti sotto l'input del prompt. Usa i tasti freccia su e giù per selezionarne uno, poi premi Enter per visualizzarlo.
• Una riga di un teammate scomparsa dopo essere rimasta inattiva è stata nascosta, non arrestata. Le righe inattive si nascondono 30 secondi dopo che l'intero pannello diventa inattivo e ricompaiono al turno successivo del teammate. Quando più di tre teammate sono inattivi, le righe in eccesso si comprimono in un'unica riga N idle agents che Enter espande. Invia un messaggio al teammate per nome per far ricomparire una riga nascosta.
• Verifica che l'attività che hai assegnato a Claude fosse abbastanza complessa da giustificare un team. Claude decide se generare teammate in base all'attività.
• Se hai richiesto esplicitamente i riquadri divisi, assicurati che tmux sia installato e disponibile nel tuo PATH:

  which tmux
  

• Per iTerm2, verifica che la CLI it2 sia installata e che la Python API sia abilitata nelle preferenze di iTerm2.

Claude genera teammate invece di subagent

Mentre i team di agenti sono abilitati, un subagent a cui Claude assegna un nome nella sessione del lead viene avviato come teammate. Claude può assegnare nomi ai subagent di propria iniziativa, quindi questo può accadere durante una delega che non hai mai impostato come lavoro di team.

Per fare in modo che i subagent con nome vengano di nuovo avviati come subagent, disattiva i team di agenti impostando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS su 0:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Non è necessario avviare una nuova sessione: Claude Code riapplica i valori env del file delle impostazioni alla sessione in esecuzione quando salvi, e rilegge la variabile ogni volta che Claude genera un subagent, quindi il prossimo subagent a cui Claude assegna un nome viene avviato come subagent.

Impostare la variabile su 0 nel tuo settings.json utente sovrascrive un export della shell. Altre fonti di impostazioni possono comunque abilitare i team di agenti:

• File di impostazioni con precedenza più alta: le impostazioni di progetto, le impostazioni locali e un payload --settings vengono applicati dopo le impostazioni utente, quindi una voce env che imposta la variabile su 1 in uno qualsiasi di essi ha la precedenza. Consulta Precedenza delle impostazioni.
• Impostazioni gestite: le impostazioni gestite vengono applicate dopo ogni altra fonte. Se la tua organizzazione abilita lì i team di agenti, chiedi al tuo amministratore di modificare il valore gestito.

Dopo la modifica, Claude potrebbe ancora assegnare nomi ai subagent, e il nome continua a funzionare come indirizzo SendMessage. Claude riceve il risultato di ogni subagent quando questo termina.

Troppe richieste di permesso

Le richieste di permesso dei teammate risalgono fino al lead, il che può creare attrito. Pre-approva le operazioni comuni nelle tue impostazioni dei permessi prima di generare i teammate per ridurre le interruzioni.

Gli agenti si fermano in anticipo

I teammate potrebbero fermarsi dopo aver riscontrato errori invece di riprendersi. Controlla il loro output selezionando il teammate nel pannello degli agenti e premendo Enter in modalità in-process, oppure facendo clic sul riquadro in modalità divisa, poi:

• Dai loro direttamente istruzioni aggiuntive
• Genera un teammate sostitutivo per continuare il lavoro

Un messaggio dal lead o da un altro teammate risveglia un teammate in-process che è in attesa di riprovare una richiesta API non riuscita, in modo che riprovi immediatamente invece di attendere l'intero intervallo prima del nuovo tentativo.

Anche il lead può fermarsi in anticipo, decidendo che il team ha finito prima che tutte le attività siano effettivamente completate. Se succede, digli di continuare.

Sessioni tmux orfane

Se una sessione tmux persiste dopo la fine della sessione di Claude Code, potrebbe non essere stata ripulita completamente. Elenca le sessioni e termina quella creata dal team:

tmux ls
tmux kill-session -t <session-name>

Limitazioni

I team di agenti sono sperimentali. Le limitazioni attuali di cui essere consapevoli:

• Nessuna ripresa della sessione con compagni di team in-process: /resume e /rewind non ripristinano i compagni di team in-process. Dopo aver ripreso una sessione, il lead potrebbe tentare di messaggiare compagni di team che non esistono più. Se questo accade, dite al lead di generare nuovi compagni di team.
• Lo stato dell'attività può ritardare: i compagni di team a volte non riescono a contrassegnare le attività come completate, il che blocca le attività dipendenti. Se un'attività sembra bloccata, controllate se il lavoro è effettivamente fatto e aggiornate lo stato dell'attività manualmente o dite al lead di spingere il compagno di team.
• L'arresto può essere lento: i compagni di team finiscono la loro richiesta attuale o la chiamata dello strumento prima di spegnersi, il che può richiedere tempo.
• Un team per sessione: una sessione ha esattamente un team, limitato a quella sessione. Non potete creare team denominati aggiuntivi o condividere un team tra sessioni.
• Nessun team annidato: i compagni di team non possono generare i loro propri compagni di team. Solo il lead può gestire il team.
• Nessun subagent in background da compagni di team in-process: i subagent di un compagno di team in-process vengono eseguiti in primo piano, perché il lavoro in background di un compagno di team non può sopravvivere al processo del lead. Claude Code restituisce un errore quando un compagno di team genera un subagent la cui definizione imposta background: true. Anche una richiesta run_in_background: true di un compagno di team fallisce, con un errore o eseguendosi silenziosamente in primo piano. I subagent lanciati dalla conversazione principale seguono il default in background.
• Il lead è fisso: la sessione principale è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.
• Nessuna modalità di permesso per singolo compagno di team al momento della generazione: i compagni di team iniziano con la modalità di permesso descritta in Permessi.
• Split panes richiedono tmux o iTerm2: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.

Prossimi passi

Esplorate approcci correlati per il lavoro parallelo e la delega:

• Delega leggera: i subagents generano agenti helper per ricerca o verifica all'interno della vostra sessione, migliore per compiti che non hanno bisogno di coordinamento tra agenti
• Messaggistica tra le vostre sessioni: la messaggistica tra sessioni consente a Claude di passare i risultati tra le sessioni che eseguite voi stessi
• Sessioni parallele manuali: i Git worktrees vi permettono di eseguire più sessioni Claude Code voi stessi senza coordinamento automatico del team