Come organizzare una dozzina di sessioni Claude Code in esecuzione in tmux

Quando lanci Claude Code nel terminale per qualche rapida modifica, tutto sembra ordinato. Esegui il comando, assegna un task, attendi la risposta, chiudi. I problemi iniziano quando mantieni quattro o cinque progetti aperti contemporaneamente. In un repository, l'agente sta facendo il refactoring dei test, in un altro sta scrivendo una migrazione del database, e in un terzo sta eseguendo una build.

In mezz'ora il terminale diventa un labirinto. Non è chiaro dove l'agente sta aspettando conferma del comando, dove sta ancora eseguendo script, e dove ha terminato da tempo ed è semplicemente inattivo. Devi scorrere manualmente le finestre tmux, sprecando tempo a controllare gli stati.

Tak Matsuyama, autore del blog devas.life e di diverse utility popolari per Neovim e tmux, ha lanciato una soluzione a questo problema. Il suo plugin tmux-claude-session-manager trasforma le finestre del terminale sparse con agenti in un elenco ordinato con cambio rapido.

Cosa fa il plugin

Fondamentalmente, è un task manager per Claude Code dentro tmux. Lo strumento combina l'interfaccia fzf, il meccanismo popup integrato di tmux, e l'API interna di Claude Code stesso.

Premi una combinazione di tasti e appare una finestra mobile con l'elenco di tutte le sessioni attive. Ogni processo mostra immediatamente il suo stato:

• working (l'agente è occupato a generare o eseguire comandi);
• waiting (richiesto input o conferma dell'utente);
• idle (la sessione è inattiva);
• tempo dall'ultima attività dell'agente.

Gli agenti che necessitano di attenzione vengono automaticamente spostati in cima all'elenco. Una preview live dello schermo tramite capture-pane viene mostrata accanto. Puoi vedere immediatamente quale domanda ha messo in difficoltà l'assistente, senza nemmeno passare alla sessione stessa.

Premendo Invio entri direttamente nel contesto della finestra desiderata e apri la sessione in un frame popup. Hai finito il dialogo o l'agente ha completato il suo lavoro — premi la combinazione di tasti per rimuovere il processo, e la sessione si chiude correttamente.

Dettagli interessanti sotto il cofano

Non ci sono demoni personalizzati o hook bash pesanti che parsano l'output di ps qui. L'autore ha scelto un approccio più elegante.

Le versioni di Claude Code dalla 2.1.139 in poi possono esporre informazioni sui loro agenti tramite il comando integrato claude agents --json. Ogni copia in esecuzione riporta il suo stato attuale a un supervisore locale. Il plugin legge semplicemente questo JSON tramite jq.

La sfida tecnica principale era abbinare i processi ai pannelli tmux. Su macOS, ad esempio, un pannello spesso riporta il PID della shell padre invece del programma figlio. Dentro il plugin, lo script agents.sh collega gli identificatori lungo una catena: pid -> tty -> pannello tmux.

Grazie a questo collegamento, il plugin traccia i processi piuttosto che le sessioni. Se hai lanciato tre agenti diversi in un progetto o hai avviato Claude in un normale pannello adiacente senza il plugin, lo strumento troverà comunque ogni processo e lo mostrerà come riga separata. L'intero polling richiede solo tre chiamate di sistema, quindi l'interfaccia funziona senza ritardi.

Un altro dettaglio interessante: se apri il menu di selezione (prefix + u) mentre sei già dentro un popup Claude, il plugin prima stacca il popup corrente, poi espande la finestra di selezione alla dimensione piena del terminale esterno. Niente bambole matrioska nidificate di frame che si restringono.

Installazione e configurazione base

Avrai bisogno di tmux versione 3.2 o superiore con supporto popup, fzf installato, l'utility jq, e una versione recente di Claude Code.

Se usi il gestore di plugin TPM, aggiungi questa riga al tuo file di configurazione ~/.tmux.conf:

Dopo di che, premi prefix + I per caricarlo.

Di default, il plugin usa due combinazioni di tasti:

• prefix + y lancia una nuova sessione Claude nella directory corrente dentro una finestra popup (o si connette a una esistente);
• prefix + u apre il selettore fzf con tutti gli agenti attivi.

Dentro la finestra lista, funzionano le frecce standard e il filtraggio del testo. Invio passa alla sessione selezionata, e Ctrl-x forza la terminazione del processo.

I parametri sono facili da sovrascrivere. Ad esempio, puoi impostare flag di lancio per Claude stesso o cambiare le dimensioni della finestra:

Per gli amanti del controllo modale, il README ha un ottimo esempio di integrazione con layout in stile vim. Puoi configurare fzf così che la lista si apra in modalità navigazione via j/k, e il passaggio alla modalità ricerca avviene con i tasti i o a:

Vale la pena installarlo

Se esegui Claude Code una volta a settimana per un paio di righe di codice, puoi cavartela facilmente senza il plugin. Un normale tab del terminale è perfettamente sufficiente.

Lo strumento è utile per chi usa attivamente l'approccio basato su agenti nel terminale e parallelizza i task tra rami o sottoprogetti diversi. Il plugin elimina la noia di trovare il tab giusto e consolida il monitoraggio dei task in background in una schermata chiara. La configurazione richiede un paio di minuti, e il codice sorgente dello script è compatto e trasparente, senza magia non necessaria.