SpyBara
Go Premium

headless.md 2026-10-06 23:59 UTC to 2026-10-07 20:57 UTC

This page contains 53 additions and 37 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sun 4 23:58 Wed 7 21:59

Eseguire Claude Code a livello programmatico

Utilizza l'Agent SDK per eseguire Claude Code a livello programmatico dalla CLI, Python o TypeScript.

L'Agent SDK ti fornisce gli stessi strumenti, il ciclo dell'agente e la gestione del contesto che alimentano Claude Code. È disponibile come CLI per script e CI/CD, oppure come pacchetti Python e TypeScript per il controllo programmatico completo.

Per eseguire Claude Code in modalità non interattiva, passa -p con il tuo prompt e le opzioni CLI di cui hai bisogno:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Questa pagina copre l'utilizzo dell'Agent SDK tramite la CLI (claude -p). Per i pacchetti SDK Python e TypeScript con output strutturati, callback di approvazione degli strumenti e oggetti messaggio nativi, consulta la documentazione completa dell'Agent SDK.

Utilizzo di base

Aggiungi il flag -p (o --print) a qualsiasi comando claude per eseguirlo in modo non interattivo. Non tutte le opzioni CLI si combinano con -p. Claude Code rifiuta --bg e rifiuta --cloud con una descrizione di attività, con un errore che nomina il conflitto; --cloud con un ID di sessione e -p invece accoda un messaggio in quella sessione cloud ed esce. Le opzioni che combinerai con -p spesso includono:

Questo esempio chiede a Claude una domanda sulla tua base di codice e stampa la risposta:

claude -p "What does the auth module do?"

Claude Code esce con codice 0 in caso di successo e con un codice diverso da zero quando l'esecuzione fallisce, quindi i tuoi script possono ramificarsi in base allo stato di uscita. Se passi un flag non valido, Claude Code segnala l'errore a stderr prima dell'inizio dell'esecuzione. Quando un errore si verifica durante l'esecuzione, come l'autenticazione mancante, Claude Code stampa l'errore come risultato su stdout.

Inizia più velocemente con la modalità bare

Aggiungi --bare per ridurre il tempo di avvio saltando l'auto-discovery di hooks, skills, comandi personalizzati, subagenti, plugin installati, server MCP, memoria automatica e CLAUDE.md. Senza di esso, claude -p carica lo stesso contesto che una sessione interattiva avrebbe, incluso tutto ciò che è configurato nella directory di lavoro o in ~/.claude.

La modalità bare è utile per CI e script dove hai bisogno dello stesso risultato su ogni macchina. Un hook nel ~/.claude di un collega o un server MCP nel .mcp.json del progetto non verranno eseguiti, perché la modalità bare non li legge mai. Una directory che nomini con --add-dir è un'eccezione parziale: la modalità bare carica skills dalla sua cartella .claude/skills/, ma salta comunque le sue cartelle .claude/commands/ e .claude/agents/. Skills da directory aggiuntive copre ciò che viene e non viene caricato.

Senza --bare, una sessione -p esegue gli hook nel .claude/settings.json di un progetto e connette i server nel suo .mcp.json, anche in una cartella che non hai mai considerato attendibile. Una sessione -p non mostra alcuna finestra di dialogo di fiducia dell'area di lavoro e nessun prompt di approvazione per server. Ciò che viene eseguito prima di considerare attendibile una cartella copre ogni tipo di contenuto del repository in -p e come mantenerlo fuori.

Questo esempio esegue un'attività di riepilogo una tantum in modalità bare e pre-approva lo strumento Read in modo che la chiamata si completi senza un prompt di autorizzazione. Imposta ANTHROPIC_API_KEY prima di eseguirlo, perché la modalità bare non utilizza il tuo accesso in abbonamento:

claude --bare -p "Summarize README.md" --allowedTools "Read"

In modalità bare, Claude Code non legge mai le credenziali OAuth o il keychain di sistema. Per l'API Anthropic, imposta ANTHROPIC_API_KEY nell'ambiente, con una chiave creata nella Claude Console, oppure fornisci un apiKeyHelper nel JSON --settings. Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry continuano a leggere le loro credenziali provider come al solito.

In modalità bare Claude ha accesso agli strumenti Bash, lettura file e modifica file. Passa qualsiasi contesto di cui hai bisogno con un flag:

Per caricare Utilizza
Aggiunte al prompt di sistema --append-system-prompt, --append-system-prompt-file
Impostazioni --settings <file-or-json>
Server MCP --mcp-config <file-or-json>
Agenti personalizzati --agents <file-or-json>
Un plugin --plugin-dir <path>, --plugin-url <url>

La modalità bare limita anche ciò che accade durante l'esecuzione della sessione:

  • Server MCP: si connettono solo i server forniti dalla riga di comando, ad esempio con --mcp-config. In una sessione interattiva, Claude Code salta anche la connessione automatica all'IDE a meno che tu non passi --ide.
  • Promemoria di sistema: Claude riceve i tuoi prompt e i risultati degli strumenti senza i promemoria di sistema che Claude Code aggiungerebbe insieme a essi. Ad esempio, Claude non viene informato quando un file che ha letto in precedenza cambia sul disco, e non riceve l'elenco delle skill disponibili, incluse le skill di una cartella --add-dir.
  • Attività in background: non ne viene eseguita nessuna. Un comando che raggiunge il suo timeout si interrompe invece di passare in background.

Prima della v2.1.286, questi limiti valevano solo in parte: una sessione --bare interattiva connetteva i server MCP che una sessione normale avrebbe connesso, ogni sessione --bare inviava promemoria di sistema e le attività in background restavano disponibili.

Attività in background all'uscita

Se Claude avvia un'attività Bash in background durante un'esecuzione di claude -p, ad esempio un server di sviluppo o una build di watch, tale shell viene terminata circa cinque secondi dopo che Claude ha restituito il suo risultato finale e stdin è stato chiuso. Il periodo di grazia consente a un'attività che termina subito dopo il risultato di consegnare comunque il suo output.

Se Claude avvia un subagente in background o un flusso di lavoro, claude -p rimane invece aperto fino al completamento di quel lavoro, perché il suo risultato fa parte dell'output finale.

Per impostazione predefinita l'attesa termina dopo 10 minuti di attesa continua inattiva, quindi un subagente o un flusso di lavoro bloccato non può mantenere il processo aperto indefinitamente. A quel punto Claude Code interrompe tutto ciò che è ancora in esecuzione e scarta il suo risultato parziale. Per modificare il limite, imposta CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, oppure impostalo su 0 per attendere senza uno.

Se Claude avvia un watch Monitor durante un'esecuzione di claude -p, Claude Code attende il watch fino a quando non scade o il limite di dieci minuti termina l'attesa, a seconda di quale arriva prima. Mentre attende, Claude continua a rispondere a ciò che il watch segnala. Per impostazione predefinita, un watch scade cinque minuti dopo che Claude lo avvia.

Interrompi un'esecuzione con SIGTERM

Se interrompi un'esecuzione di claude -p con SIGTERM, ad esempio con kill o da un supervisore di processo, Claude Code esce con codice 143. Claude Code lascia il turno che era in corso non completato e non registra alcun risultato per esso. Per terminare il turno invece, invia SIGINT, o chiama interrupt() dell'Agent SDK, prima di interrompere il processo.

Su SIGTERM, Claude Code termina l'albero dei processi di qualsiasi comando Bash ancora in esecuzione. Claude Code quindi esegue gli hook SessionEnd ed esce. Durante l'uscita, Claude Code non avvia alcuna nuova chiamata di strumento, non invia alcuna nuova richiesta di modello e non esegue alcun hook diverso da SessionEnd. Se l'esecuzione era nel mezzo di un comando o in attesa di una risposta a un prompt di autorizzazione quando il segnale è arrivato, Claude Code gestisce quel passaggio come segue:

  • Esecuzione di un comando: Claude Code registra il comando come terminato nella sessione.
  • In attesa di una risposta a un prompt di autorizzazione: se invii SIGTERM al processo, Claude Code lascia il prompt senza risposta. Se il tuo programma chiude la sessione tramite l'Agent SDK, l'SDK termina l'input di Claude Code prima di inviare qualsiasi segnale, e Claude Code annulla il prompt non appena l'input termina.

Quando riprendi la sessione, Claude Code lascia il turno interrotto così com'è, e il tuo prossimo prompt guida la conversazione. Per fare in modo che Claude Code continui il turno interrotto al ripristino, imposta CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Se la directory di lavoro viene eliminata

Se la directory di lavoro di una sessione claude -p o Agent SDK viene eliminata durante la sessione, la sessione continua a funzionare. Quando un turno inizia mentre la directory è mancante, Claude Code emette un messaggio di avviso nell'output stream-json, e i comandi shell falliscono fino a quando la directory non esiste di nuovo.

Esempi

Questi esempi evidenziano i modelli CLI comuni. Dove un comando nomina un file come auth.py o build-error.txt, sostituisci un file dal tuo progetto. In CI o altri ambienti con script, aggiungi --bare in modo che Claude Code si avvii senza caricare gli hook, i plugin, la memoria automatica o CLAUDE.md dell'host.

Inviare dati attraverso Claude

La modalità non interattiva legge stdin, quindi puoi inviare dati e reindirizzare la risposta come qualsiasi altro strumento da riga di comando.

Questo esempio invia un log di build a Claude e scrive la spiegazione in un file:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Con --output-format json, il payload della risposta include total_cost_usd e una suddivisione dei costi per modello, quindi i chiamanti con script possono tracciare la spesa senza consultare il dashboard di utilizzo. Quando continui una conversazione precedente con --continue o --resume, l'esecuzione segnala il totale complessivo della conversazione, la spesa delle esecuzioni precedenti inclusa. Entrambe le cifre sono stime lato client e possono differire dalla tua fattura effettiva.

Se Claude Code non riesce a leggere stdin, ad esempio perché il processo che lo ha avviato ha disconnesso la sua estremità, Claude Code stampa un avviso su stderr e continua con il prompt dalla riga di comando. Prima della v2.1.211, uno stdin illeggibile su Windows causava l'arresto della sessione o l'uscita silenziosa senza output.

Aggiungere Claude a uno script di build

Puoi avvolgere una chiamata non interattiva in uno script per utilizzare Claude come linter o revisore specifico del progetto.

Questo script package.json invia il diff rispetto a main a Claude e gli chiede di segnalare i refusi. Inviare il diff tramite pipe significa che Claude non ha bisogno del permesso Bash per leggerlo, e le virgolette doppie con escape mantengono lo script portabile su Windows:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Eseguilo con npm run lint:claude.

Ottenere output strutturato

Utilizza --output-format per controllare come vengono restituite le risposte:

  • text (predefinito): output di testo semplice
  • json: JSON strutturato con risultato, ID sessione e metadati
  • stream-json: JSON delimitato da newline per lo streaming in tempo reale

Questo esempio restituisce un riepilogo del progetto come JSON con metadati della sessione, con il risultato del testo nel campo result:

claude -p "Summarize this project" --output-format json

Per ottenere output conforme a uno schema specifico, utilizza --output-format json con --json-schema e una definizione JSON Schema. La risposta include metadati sulla richiesta (ID sessione, utilizzo, ecc.) con l'output strutturato nel campo structured_output.

Questo esempio estrae i nomi delle funzioni e li restituisce come array di stringhe:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Se il valore non è un JSON Schema valido, claude esce con Error: --json-schema is not a valid JSON Schema seguito dalla diagnostica del validatore. Claude Code accetta schemi che utilizzano la parola chiave format, come "format": "email", ma tratta format come un'annotazione e non la applica. Prima della v2.1.205, Claude Code ignorava silenziosamente uno schema non valido e restituiva testo non strutturato, e trattava qualsiasi schema contenente format come non valido.

Streaming delle risposte

Utilizza --output-format stream-json con --verbose e --include-partial-messages per ricevere i token mentre vengono generati. Ogni riga è un oggetto JSON che rappresenta un evento:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

L'ultima riga del flusso è un messaggio result con il testo della risposta finale, il costo e i metadati della sessione.

Se il tuo consumer legge il flusso lentamente, Claude Code attende che l'output in coda si svuoti prima di uscire, scalando l'attesa in base a quanto è ancora in coda, con un limite di 30 secondi. Prima della v2.1.214 l'attesa di uscita era limitata a circa due secondi, il che poteva troncare la fine di una risposta di grandi dimensioni.

L'esempio seguente utilizza jq per filtrare i delta di testo e visualizzare solo il testo in streaming. Il flag -r restituisce stringhe non elaborate (senza virgolette) e -j unisce senza newline in modo che i token fluiscano continuamente:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Per lo streaming programmatico con callback e oggetti messaggio, consulta Stream responses in real-time nella documentazione dell'Agent SDK.

Seguire i messaggi dei subagent

I messaggi dei subagent e delle skill che vengono eseguite in un subagent appaiono nel flusso come messaggi assistant e user. Il loro campo parent_tool_use_id indica a quale esecuzione appartiene ciascuno. I messaggi della conversazione principale portano null in quel campo.

Il primo messaggio di una skill biforcata, o di un subagent in esecuzione in primo piano, è un messaggio user che contiene il prompt o il contenuto della skill che lo guida. Dopo quel primo messaggio, Claude Code emette:

Quando abiliti una delle due opzioni, Claude Code inoltra i messaggi dei subagent a ogni profondità di annidamento, indipendentemente dal fatto che ciascuno sia stato generato con lo strumento Agent o avviato come skill biforcata. In parent_tool_use_id, i messaggi del subagent annidato portano l'ID della chiamata allo strumento Agent o Skill che lo ha avviato, in modo da poter ricostruire l'albero di annidamento completo seguendo quegli ID.

Un'esecuzione che Claude avvia con una chiamata a uno strumento porta l'ID di quella chiamata. Una skill biforcata che avvii passando /<skill-name> come prompt non ha alcuna chiamata a uno strumento, quindi i suoi messaggi portano invece un valore forked-command- e arrivano dopo che è terminata. Trova nella prima colonna come è stata avviata l'esecuzione:

Come si avvia l'esecuzione parent_tool_use_id Quando arrivano i suoi messaggi
Claude chiama lo strumento Agent dalla conversazione principale L'ID di quel blocco tool_use di Agent Mentre il subagent lavora
Claude chiama lo strumento Skill per una skill biforcata dalla conversazione principale L'ID di quel blocco tool_use di Skill Mentre la skill biforcata lavora
Passi /<skill-name> come prompt Un valore che inizia con forked-command- Tutti insieme e in ordine dopo che la skill biforcata è terminata

Per una skill biforcata avviata dal prompt, confronta parent_tool_use_id con il prefisso forked-command-, perché il nome che lo segue può differire da quello che hai digitato.

Se alcuni di questi messaggi mancano dal tuo flusso, verifica la tua versione di Claude Code rispetto a questi requisiti minimi:

  • --forward-subagent-text e CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: v2.1.211 o successivo
  • Inoltro a ogni profondità di annidamento: v2.1.219 o successivo
  • Una skill biforcata che Claude avvia con lo strumento Skill dalla conversazione principale: v2.1.86 o successivo per i suoi blocchi tool_use e tool_result, e v2.1.265 o successivo per il suo primo messaggio user e i suoi blocchi di testo e di ragionamento
  • Messaggi dei subagent generati da una skill biforcata, e delle skill biforcate avviate all'interno di un subagent o di un'altra skill biforcata: v2.1.275 o successivo
  • Messaggi di una skill biforcata che avvii passando /<skill-name> come prompt: v2.1.287 o successivo

Gestire i nuovi tentativi API

Quando una richiesta API non riesce con un errore per cui è possibile riprovare, Claude Code emette un evento system/api_retry prima di riprovare. Sulla v2.1.246 o successiva, quando un 401 o 403 rifiuta una credenziale apiKeyHelper, Claude Code effettua i primi due nuovi tentativi silenziosamente senza evento, quindi emette l'evento come al solito dal terzo nuovo tentativo consecutivo in poi. I nuovi tentativi silenziosi contano comunque per attempt. Puoi utilizzare l'evento per mostrare l'avanzamento dei nuovi tentativi nella tua interfaccia.

Campo Tipo Descrizione
type "system" tipo di messaggio
subtype "api_retry" identifica questo come un evento di nuovo tentativo
attempt integer numero del tentativo corrente, a partire da 1
max_retries integer nuovi tentativi totali consentiti per la causa di questo errore, che possono essere meno del budget a livello di sessione
retry_delay_ms integer millisecondi fino al prossimo tentativo
error_status integer o null codice di stato HTTP del tentativo non riuscito, o null quando il tentativo non ha ricevuto alcuna risposta HTTP dall'API
no_response object, opzionale presente solo quando il tentativo non riuscito non ha ricevuto alcuna intestazione di risposta in tempo. waited_ms è quanto tempo quel tentativo ha atteso e retry_wait_ms è quanto tempo attenderà il nuovo tentativo. In questi eventi, max_retries riflette l'unico nuovo tentativo che questa causa normalmente ottiene, non il budget a livello di sessione. Richiede Claude Code v2.1.261 o successivo
error string categoria di errore: authentication_failed, oauth_org_not_allowed, account_on_hold, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, max_output_tokens, cloud_credential_error, o unknown
uuid string identificatore evento univoco
session_id string sessione a cui appartiene l'evento

Leggere i metadati della sessione

L'evento system/init segnala i metadati della sessione inclusi il modello, gli strumenti, i server MCP e i plugin caricati. È il primo evento nel flusso a meno che non lo precedano eventi di avvio:

L'evento contiene anche un array capabilities opzionale di stringhe che denominano i comportamenti del protocollo che questa versione di Claude Code implementa, come interrupt_receipt_v1 o interrupt_cancel_queued_v1. Controllalo per rilevare le funzionalità invece di confrontare le stringhe di versione, e ignora i valori che non riconosci. Il campo richiede Claude Code v2.1.205 o successivo ed è assente dalle versioni precedenti. Consulta SDKSystemMessage per l'elenco delle capacità.

Far fallire CI quando un plugin o un server MCP non si carica

Utilizza i campi plugin nell'evento system/init per rilevare un plugin che non è stato caricato:

Campo Tipo Descrizione
plugins array plugin che sono stati caricati con successo, ognuno con name e path
plugin_errors array errori di caricamento del plugin, ognuno con plugin, type e message. Include versioni di dipendenza non soddisfatte e errori di caricamento di --plugin-dir come un percorso mancante o un archivio non valido. Un plugin che non è stato caricato è assente da plugins. La chiave viene omessa quando non ci sono errori

Quando una directory --plugin-dir o un archivio stesso non riesce a caricarsi, la sua voce plugin_errors include il percorso assoluto risolto come path. Usalo per capire quale dei vari valori --plugin-dir ha fallito. Il campo path richiede Claude Code v2.1.283 o successivo.

Utilizza i campi del server MCP allo stesso modo. Quando passi --mcp-config con -p, Claude Code attende i server ancora in sospeso prima di eseguire il primo turno, fino al timeout di avvio MCP_TIMEOUT, 30 secondi per impostazione predefinita. Un server remoto con un elenco di strumenti memorizzato nella cache salta l'attesa, mostra pending in system/init e si connette alla sua prima chiamata a uno strumento. L'attesa richiede Claude Code v2.1.221 o successivo.

Claude Code convalida ogni voce --mcp-config all'avvio e salta le voci che non superano la convalida, ad esempio una voce url senza type. L'esecuzione continua ed esce correttamente, quindi controlla questi campi per rilevare un server che non è mai stato caricato:

Campo Tipo Descrizione
mcp_servers array server MCP nella sessione, ognuno con name e status
mcp_server_errors array voci --mcp-config saltate dalla convalida della configurazione, ognuna con name, type e message. type è una categoria di salto come unknown_type, url_missing_type, invalid_config o reserved_name; tratta i valori che non riconosci come un salto generico. I server interessati sono assenti da mcp_servers. La chiave viene omessa quando non ci sono errori, quindi un gate CI può fallire su un array non vuoto. Richiede Claude Code v2.1.219 o successivo

Quando esegui il comando a mano in un terminale, Claude Code stampa anche un avviso di avvio su stderr, come Warning: 1 MCP server skipped due to invalid config:, seguito dal motivo di ogni voce saltata. Quando reindirizzi stderr, o quando un programma come un runner CI o un host SDK lo cattura, Claude Code non stampa alcun avviso e segnala le voci saltate solo nel campo mcp_server_errors. L'avviso richiede Claude Code v2.1.219 o successivo.

Tracciare le installazioni dei plugin

Quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL è impostato, Claude Code emette eventi system/plugin_install mentre i plugin del marketplace si installano prima del primo turno. Utilizza questi per visualizzare il progresso dell'installazione nella tua interfaccia utente.

Campo Tipo Descrizione
type "system" tipo di messaggio
subtype "plugin_install" identifica questo come un evento di installazione plugin
status "started", "installed", "failed", o "completed" started e completed racchiudono l'installazione complessiva; installed e failed segnalano i singoli marketplace
name string, opzionale nome del marketplace, presente su installed e failed
error string, opzionale messaggio di errore, presente su failed
uuid string identificatore evento univoco
session_id string sessione a cui appartiene l'evento

Approvare automaticamente gli strumenti

Utilizza --allowedTools per consentire a Claude di utilizzare determinati strumenti senza chiedere. Elencare Read e Edit consente a Claude di leggere e modificare file senza chiedere il permesso. Elencare Bash fa lo stesso per i comandi shell, tranne in un'esecuzione che inizia in modalità auto, dove Claude Code scarta una voce Bash semplice in quanto regola allow troppo ampia e la modalità auto valuta invece ogni comando. Questo esempio esegue una suite di test e corregge gli errori con questi tre strumenti elencati:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Per impostare una linea di base per l'intera sessione invece di elencare i singoli strumenti, passa una modalità di permesso. Un'esecuzione in cui nulla imposta una modalità di permesso adotta la modalità di permesso iniziale integrata, che può essere auto, quindi passa quella che desideri:

  • auto: passa --permission-mode auto per avere un classificatore che esamini la maggior parte delle azioni invece di te
  • dontAsk: Claude Code nega ogni chiamata che altrimenti richiederebbe conferma, il che è utile per esecuzioni CI bloccate. Le azioni che non necessitano di approvazione in modalità Manual vengono comunque eseguite, come le letture di file nelle tue directory di lavoro e il set di comandi di sola lettura, così come le azioni coperte dalle tue voci --allowedTools o dalle regole permissions.allow. AskUserQuestion, gli strumenti dei connettori che la tua organizzazione ha impostato su ask e gli strumenti MCP contrassegnati con requiresUserInteraction vengono negati anche quando una regola allow corrisponde
  • acceptEdits: Claude scrive file senza chiedere, e Claude Code approva automaticamente i comandi del filesystem comuni come mkdir, touch, mv e cp. Le azioni che nessuna modalità approva automaticamente si applicano comunque. A parte il set di comandi di sola lettura, altri comandi shell e richieste di rete hanno ancora bisogno di una voce --allowedTools o di una regola permissions.allow. Consulta cosa acceptEdits approva automaticamente per l'elenco completo

Questo esempio applica le correzioni di lint con acceptEdits come linea di base:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Disattivare le richieste di permesso nelle esecuzioni incustodite

Passa --permission-prompts none quando nessuno è disponibile per rispondere alle richieste di permesso, ad esempio in un lavoro programmato. Il flag è più importante quando la tua esecuzione ha un host dei permessi: un'app Agent SDK con un callback canUseTool, o uno strumento MCP che passi con --permission-prompt-tool. Senza il flag, la tua esecuzione attende che quell'host risponda a ogni richiesta di permesso.

Con il flag, la tua esecuzione non consulta l'host e non lo attende. Qualsiasi cosa che richiederebbe conferma viene negata a meno che un hook PermissionRequest non la consenta, a Claude viene detto che nessuno può approvare la richiesta e di non riprovarla, e l'esecuzione continua. In un'esecuzione -p senza host, queste richieste vengono negate comunque, e il flag dice anche a Claude di non riprovarle. Le regole di permesso, gli hook PermissionRequest e la modalità di permesso che imposti decidono comunque per primi ogni chiamata; Claude Code nega solo le richieste che nient'altro risolve.

Questo esempio esegue un'attività incustodita in modalità auto. Il classificatore esamina ogni azione come al solito, e Claude Code nega qualsiasi cosa che sarebbe altrimenti ricaduta su una richiesta di conferma:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Con --permission-prompts none, Claude Code rimuove gli strumenti che hanno bisogno di una risposta da una persona, come AskUserQuestion, in modo che Claude non possa chiamarli. Qualsiasi richiesta di elicitazione MCP a cui nessun hook Elicitation risponde viene annullata.

Con --output-format stream-json, i rifiuti appaiono come messaggi di sistema permission_denied, e il messaggio di risultato finale li elenca in permission_denials.

Creare un commit

Questo esempio esamina le modifiche in staging e crea un commit con un messaggio appropriato:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Il flag --allowedTools utilizza la sintassi delle regole di permesso. Il * finale abilita la corrispondenza dei prefissi, quindi Bash(git diff *) consente qualsiasi comando che inizia con git diff. Lo spazio prima di * è importante: senza di esso, Bash(git diff*) corrisponderebbe anche a git diff-index.

Personalizzare il prompt di sistema

Utilizza --append-system-prompt per aggiungere istruzioni mantenendo il comportamento predefinito di Claude Code. Questo esempio invia il diff di una PR a Claude e gli chiede di esaminarlo alla ricerca di vulnerabilità di sicurezza. Salvalo come script shell, ad esempio review.sh:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Nello script, "$1" rappresenta il primo argomento che passi sulla riga di comando. Esegui bash review.sh 123 e la shell sostituisce "$1" con 123, in modo che lo script recuperi il diff per la PR 123. Claude Code stampa la revisione come JSON, con il testo nel campo result.

Consulta i flag del prompt di sistema per ulteriori opzioni incluso --system-prompt per sostituire completamente il prompt predefinito.

Continuare le conversazioni

Utilizza --continue per continuare la conversazione più recente, oppure --resume con un ID sessione per continuare una conversazione specifica. Su Claude Code v2.1.257 o successivo, quando passi --continue, Claude Code apre una sessione in background che è terminata, ma non una che è ancora in esecuzione. Questo esempio esegue una revisione, quindi invia prompt di follow-up:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Se stai eseguendo più conversazioni, acquisisci l'ID sessione per riprendere una specifica:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Puoi eseguire i due comandi da directory diverse: Claude Code trova la sessione dal suo ID in qualsiasi progetto su questa macchina. Prima della v2.1.223, Claude Code cercava l'ID solo nella directory del progetto corrente e nei suoi worktree git, quindi dovevi eseguire entrambi i comandi dalla stessa directory.

Al posto dell'ID sessione, puoi passare a --resume il percorso assoluto al file di trascrizione .jsonl di una sessione, e Claude Code continua la conversazione memorizzata in quel file.

Passaggi successivi