Cette page est la référence compacte de Conductor. Elle nomme la surface publique et les champs qu'un script ou un LLM peut utiliser de façon fiable.
Verbes CLI
| Verbe | Méthode principale | Usage |
|---|---|---|
ps [--json] | fleet.list | Liste les agents détectés dans les workspaces |
status <target> [--json] | surface.status | Lit l'état agent d'une pane |
watch [--surface <sel>] [--type <event>] | events.subscribe | Stream les événements de cycle de vie et les changements de surface |
read <target> | surface.read | Lit le scrollback d'une pane |
send <target> <text> | surface.send_text | Prépare ou soumet du texte dans une pane |
wait --match <sel> | surface.read, flux d'événements en mode idle | Bloque jusqu'à l'état idle, une regex ou les deux |
up <file> | orchestration workspace | Crée un workspace d'agents déclaratif |
flow run <file> | orchestration flow | Lance un pipeline multi-agent |
ls, search, focus, key | méthodes scripting | Utiles quand l'état conductor ne suffit pas |
Les lectures sont autorisées par défaut. Les écritures comme send --submit, key et les étapes de flow qui soumettent du texte exigent le scripting gate ou le mode AI free access.
Sélecteurs
| Sélecteur | Exemple | Notes |
|---|---|---|
| Id numérique | paneflow status 42 | Id exact de pane |
| Nom | paneflow status backend | Meilleur sélecteur pour les workflows conductor |
cmdline:<substr> | paneflow read cmdline:claude | Utile mais moins portable qu'un nom de pane |
cwd:<path> | paneflow read cwd:/home/me/app | Bon choix pour les scripts liés à un repo |
Un sélecteur qui ne matche rien ou plusieurs panes sort avec le code 3, sauf pour les commandes qui acceptent explicitement plusieurs matches comme les sends broadcast ou wait --any et wait --all.
fleet.list
paneflow ps --json retourne un tableau agents.
| Champ | Sens |
|---|---|
pid | Id de processus agent, ou null pour une détection scan-only |
tool | Famille d'agent comme claude, codex, opencode ou gemini |
state | thinking, waiting_for_input, finished, errored, stalled, idle ou unknown_running |
hooked | true quand Paneflow reçoit les événements de hook |
reason | Raison de détection, dont no_hook pour les processus non hookés |
surface_id | Id de pane quand résolu |
surface_name | Nom de pane quand présent |
workspace | Index du workspace |
active_tool_name | Outil actuellement exécuté par l'agent, si reporté |
message | Question ou permission en attente, si reportée |
last_result | Résumé du dernier tour, quand le hook le fournit |
waiting_ms | Millisecondes passées en attente d'entrée |
idle_ms | Millisecondes depuis la dernière activité observée |
Une flotte vide retourne {"agents":[]} avec le code de sortie 0.
surface.status
paneflow status <target> --json retourne le statut d'une pane.
| Champ | Sens |
|---|---|
surface_id | Id de pane |
state | Même vocabulaire que fleet.list |
hooked | Indique si le suivi de cycle de vie est actif |
tool | Famille d'agent, si détectée |
active_tool_name | Outil actuellement exécuté, si reporté |
message | Question ou permission en attente, si reportée |
last_result | Résumé du dernier tour, quand disponible |
waiting_ms | Millisecondes passées en attente d'entrée |
idle_ms | Millisecondes depuis la dernière activité observée |
output_generation | Compteur monotone qui avance quand la sortie de pane change |
Une pane sans agent actif retourne un état idle au lieu d'une erreur.
surface.read
paneflow read <target> retourne du texte de terminal. Par défaut, la sortie est enveloppée dans <untrusted_terminal_output> pour qu'un LLM puisse l'inspecter sans la traiter comme des instructions. Utilisez --raw seulement pour des scripts humains de confiance.
Les champs utiles en mode JSON incluent text, lines, total_lines, eof et output_generation.
events.subscribe et watch
paneflow watch est du JSON délimité par lignes. Il peut émettre :
| Type d'événement | Sens |
|---|---|
ai.session_start | Une session agent démarre |
ai.prompt_submit | Un prompt est soumis |
ai.tool_use | L'agent invoque un outil |
ai.notification | L'agent pose une question ou demande une permission |
ai.stop | Un tour se termine |
ai.exit | Le processus agent sort |
ai.session_end | La session se ferme |
surface_changed | Le output_generation de la pane a avancé |
Les frames de contrôle sont aussi valides :
| Frame | Sens |
|---|---|
subscribed | Subscription acceptée |
heartbeat | Frame keepalive |
dropped | Le subscriber a pris du retard et des événements ont été supprimés |
Quand un client reçoit dropped, il doit se resynchroniser avec paneflow ps --json ou paneflow status <target> --json.
wait
wait --idle utilise le flux d'événements quand il est disponible et bascule proprement en fallback si nécessaire. wait --pattern poll le scrollback récent toutes les 500 ms et scanne les 500 dernières lignes.
| Mode | Exemple | Usage |
|---|---|---|
| Idle | paneflow wait --match reviewer --idle --timeout 600 | Continuer après l'arrêt du travail agent |
| Pattern | paneflow wait --match backend --pattern '^DONE:' --timeout 300 | Continuer après une ligne sentinelle |
| Idle plus pattern | paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600 | Exiger une pane stable et un marqueur |
| Any ou all | paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all | Coordonner plusieurs panes en mode pattern |
Les timeouts sortent avec le code 4.
Clés de configuration
| Clé | Défaut | Sens |
|---|---|---|
ai_unrestricted | false | Autorise l'automation IA de confiance à soumettre quand activé |
ai_injection_fence | true | Enveloppe la sortie terminal pair comme texte non fiable |
agent_stall_threshold_secs | défaut app | Marque comme stalled les tours silencieux encore en cours |
Codes de sortie
| Code | Sens |
|---|---|
0 | Succès |
1 | Échec runtime |
2 | Erreur d'usage CLI |
3 | Cible introuvable ou ambiguë |
4 | Timeout de wait |