Lavorare con agenti AI

L'automazione di Zshell è pensata principalmente per gli agenti di programmazione AI. Offre loro un modo sicuro di lavorare con i pannelli e coordinare altri agenti; non è un altro linguaggio di comandi da imparare.

L'integrazione AI è attiva per impostazione predefinita. Parla normalmente con il tuo agente: può creare un pannello in background, avviare un esecutore delegato, eseguire un comando, attendere il risultato e riportarti la risposta senza togliere il focus al pannello che usi.

Attendere i risultati dei comandiCopia link

Per comandi che terminano, come test o compilazioni, il tuo agente può attendere il codice di uscita e la durata del comando e leggere l’output recente salvato del terminale. Se l’attesa scade, il comando continua e puoi attendere nuovamente la stessa attività, senza spostare il focus. Serve un prompt vuoto nella zsh locale originale avviata da Zshell; shell annidate, SSH e programmi di avvio personalizzati non sono supportati. L’output recente è limitato e può contenere comandi o prompt precedenti. Chiedi all’agente di salvare l’output completo in un file quando necessario.

I comandi diretti exit, logout ed exec vengono rifiutati perché terminano o sostituiscono la shell originale; usa /bin/sh -c per eseguirli in un sottoprocesso.

ConfigurazioneCopia link

Controlla Impostazioni → Automazione → AI. È già attiva; se l'avevi disattivata, riattivala e apri un nuovo terminale o riavvia l'agente già in esecuzione.

Zshell supporta Codex, Claude Code, Gemini CLI, Grok Build, OpenCode, Cursor Agent, Aider, Amp e Pi. Se trova una configurazione esistente dell'agente incompatibile con la funzione, la lascia intatta, riporta l'interruttore allo stato precedente e mostra l'errore nelle Impostazioni.

Chiedere in linguaggio naturaleCopia link

Descrivi all'agente il risultato desiderato. Per esempio:

Esegui i test pertinenti in un pannello in background e dimmi quali falliscono.

Delega questo bug a un altro agente Codex, poi rivedi il risultato.

Chiedi all'agente che lavora sull'API se lo schema è pronto e passa la risposta all'agente dei test.

Avvia il server di sviluppo accanto a noi, aspetta che sia pronto e dammi l'URL.

Controlla se l'agente in background ha finito. Se è bloccato, dimmi di cosa ha bisogno.

L'agente gestisce l'interfaccia di automazione per te. Non devi digitare o memorizzare comandi Zshell.

Coordinare gli agenti tra pannelliCopia link

Puoi suddividere attività correlate tra diversi pannelli e chiedere all'agente principale di coordinarle. Un agente può lavorare sull'API mentre un altro aggiorna i test. Il coordinatore può chiedere i risultati a un esecutore specifico, inviare una richiesta successiva, passare informazioni utili a un altro e riportarti la risposta complessiva. Gli esecutori possono usare diversi strumenti supportati.

Questo elimina il copia e incolla dal lavoro parallelo. Ogni agente conserva la propria conversazione nel proprio pannello; il coordinatore trasmette soltanto domande, aggiornamenti o risultati necessari all'altro.

Inviare una richiesta successiva non significa che il lavoro sia finito. Il coordinatore deve ancora attendere l'esecutore, leggere il risultato e verificarlo. Un messaggio di un altro agente non equivale mai alla tua approvazione. Permessi, credenziali, decisioni di fiducia e azioni distruttive continuano a tornare a te.

Continuare a lavorare durante l'esecuzioneCopia link

I pannelli delegati restano in background finché non chiedi di vederli. Quando l'integrazione nativa del ciclo di vita del provider comunica lo stato, Zshell lo mostra nel pannello e nella scheda dell'agente:

Zshell dà priorità agli eventi nativi di Codex, Claude Code, Pi, OpenCode e Grok, poi alle segnalazioni esplicite dei programmi. Passa il puntatore sul badge o apri Agents per vedere origine, motivo dell’attesa, percentuale e attività secondarie. Gli hook Codex vanno prima esaminati e autorizzati in /hooks; Zshell non aggira questa verifica.

Senza segnalazioni native viene esaminata solo una porzione limitata del fondo della schermata attiva di un agente riconosciuto. La deduzione dallo schermo è indicata, non segnala il completamento, non invia notifiche e non soddisfa zshell +agent wait. Non concede approvazioni. Controlla il pannello e il risultato effettivo.

I programmi usano zshell +agent report per segnalare l’avanzamento e zshell +agent clear per cancellare la propria segnalazione. Questa scade dopo 120 secondi senza aggiornamenti o alla chiusura del processo proprietario.

Quando l'integrazione segnala la conclusione o la necessità di input, Zshell può anche inviare una notifica. Premi Cmd+Shift+A per raggiungere il prossimo agente che ha segnalato di richiedere attenzione.

Utilizzo e limiti dell'accountCopia link

Impostazioni → Automazione → Utilizzo dell'account mostra i limiti disponibili di Claude Code e Codex: percentuale usata, orario di ripristino se comunicato e momento dell'ultimo aggiornamento. Aggiorna utilizzo ricarica i dati più recenti disponibili.

Codex richiede una CLI installata, con accesso effettuato e capace di comunicare i limiti. L'utilizzo di Claude Code compare quando Zshell riceve dal provider un rapporto tramite la riga di stato. La sezione appare solo quando sono disponibili dati; i periodi supportati dipendono da provider e account. Sono limiti dell'account, non il totale dei token della sessione attiva.

Un flusso tipicoCopia link

1. Avvia l'agente abituale in un terminale Zshell.
2. Chiedigli di delegare un'attività circoscritta, eseguire qualcosa in background o coordinare un altro agente.
3. Continua nel pannello corrente mentre il lavoro delegato resta visibile nella disposizione del progetto.
4. Segui gli indicatori Al lavoro, Bloccato o Completato quando il provider li fornisce. Se lo strumento non comunica il ciclo di vita, apri il pannello per leggere conversazione o output.
5. Rivedi i file nel pannello Git, esamina il diff e decidi cosa tenere.

Il controllo resta a teCopia link

• L'automazione resta nel progetto Zshell corrente e non può raggiungere pannelli di altri progetti o finestre.
• Il lavoro in background non prende il focus senza una tua richiesta esplicita.
• Zshell non risponde al posto tuo a richieste di permessi, credenziali, fiducia o azioni distruttive. Un agente bloccato secondo il provider ti restituisce la decisione.
• Il completamento segnalato invita a rivedere il risultato, non approva automaticamente le modifiche.

Se un agente non usa ZshellCopia link

• Verifica che Impostazioni → Automazione → AI sia attivo.
• Apri un nuovo terminale se quello corrente esisteva già prima dell'attivazione.
• Riavvia l'agente che era già in esecuzione quando l'hai attivata.
• Controlla le Impostazioni per un errore di configurazione mostrato accanto al controllo.
• Chiedi esplicitamente un “pannello Zshell in background” o un “agente Zshell delegato” quando vuoi usare questo flusso.

Riprendere la conversazione originaleCopia link

Con Riprendi le conversazioni degli agenti, un pannello senza il PTY originale disponibile riprende la propria conversazione registrata di Claude Code, Codex, Pi o OpenCode. Pannelli nella stessa cartella mantengono conversazioni distinte.

Zshell installa hook SessionStart per Claude Code e Codex, un’estensione Pi e un plugin TUI OpenCode nella configurazione esistente. Conserva altri hook, plugin, impostazioni e commenti JSONC. Quando richiesto, attiva gli hook nella conferma di fiducia di Claude Code e approva quelli nuovi di Codex in /hooks. Riavvia gli agenti già in esecuzione prima dell’installazione.

Si riprendono solo conversazioni radice verificate segnalate da queste integrazioni. Le sessioni condivise dell’app-server Codex sono supportate quando un ID di conversazione verificato corrisponde al pannello; le corrispondenze ambigue restano scollegate. Per le conversazioni su host remoti, consulta le sessioni remote condivise. OpenCode richiede l’API dei plugin TUI; versioni precedenti, sessioni server senza interfaccia e opencode attach non sono supportati. Un agente figlio non sostituisce la conversazione del pannello padre. Pi richiede il file della sessione salvato.

Senza identità verificata, cartella originale o file Pi si apre una nuova shell. Anche una CLI non disponibile riporta alla shell. Zshell non riesegue comandi di avvio arbitrari e non sceglie una conversazione recente. La CLI mostra gli errori del provider, per esempio una conversazione eliminata.

Trovare e riprendere conversazioni salvateCopia link

Apri Agenti → Cronologia delle conversazioni degli agenti, fai clic sull’orologio in cima alla barra laterale dei progetti. Cerca tra i progetti per titolo, provider, progetto, ID della conversazione o cartelle di lavoro e configurazione. Zshell conserva le ultime 200 conversazioni locali verificate dopo la chiusura di agenti e pannelli e il riavvio dell’app. Recenti mostra 20 risultati non archiviati; Tutte include quelli archiviati; Archiviate mostra solo questi ultimi.

Scegli Mostra conversazione se è aperta o Riprendi conversazione se è salvata. Zshell riutilizza un pannello aperto, riconnette un PTY ancora attivo o riprende l’esatta conversazione del provider con la cartella e la configurazione originali. La ripresa manuale richiede l’integrazione AI anche se il ripristino automatico è disattivato. Cartelle mancanti e file Pi assenti o non corrispondenti producono un errore prima di creare un pannello.

Archivia nasconde la voce da Recenti; Ripristina la riporta. Elimina… rimuove solo la voce di Zshell e conserva i file del provider.

In un pannello Zshell, zshell +agent history --all e zshell +agent resume --id HISTORY_UUID riguardano il suo progetto. Da un normale terminale esterno, lascia Zshell aperto, trova l’UUID del progetto e selezionalo esplicitamente:

zshell +agent history projects
zshell +agent history --project PROJECT_UUID --all
zshell +agent resume --project PROJECT_UUID --id HISTORY_UUID --focus

La CLI riprende in background senza --focus. Per un progetto aperto in più finestre scegli --window WINDOW_UUID da history projects. Con più istanze dell’app usa --connection PATH con il percorso assoluto del file di connessione privato indicato dalla CLI. Queste opzioni sono per terminali esterni; i processi dei pannelli mantengono il progetto originale.

Seguire gli eventi del progettoCopia link

Esegui zshell +events in un terminale Zshell per ricevere in NDJSON le modifiche future del suo progetto e della sua finestra, senza polling. Opzioni: --pane UUID, --event NAME ripetibile, --once e --timeout MS (0 attende senza limiti).

Include creazione e chiusura di sessioni e riquadri, focus, avanzamento, attenzione e completamento degli agenti, e comandi terminati. stream.ready inizia da sequence 0; ogni evento corrispondente incrementa la sequenza. Ogni riga contiene version, event, stream_id, sequence, time in millisecondi Unix, project_id e data. Nessuna riproduzione dello storico. Leggi i risultati con +pane wait --task UUID.

Limiti: 32 iscrizioni, 256 frame e 1 MiB per coda, 64 KiB per frame. Un lettore lento riceve stream.lagged se possibile, poi viene disconnesso; anche 2 secondi senza scrittura chiudono la connessione. Ritardo, disconnessione inattesa o errore di sequenza terminano con codice diverso da zero. Iscriviti di nuovo e leggi lo stato attuale. Chiusura del terminale, rotazione del token o trasferimento ad altro progetto o finestra terminano l’iscrizione. Nessun controllo esterno né --project; eliminare variabili non amplia i permessi. --once senza corrispondenze restituisce 124 alla scadenza, altrimenti 0.

zshell +events --event command.task.finished --once --timeout 30000

pane.updated: data.from → data (tab_id, pane_id, terminal_id, content).