Local protocolProtocole local
The control socket (one JSON per line), the cluster-run wrapper messages, the web API endpoints and the MCP bridge.Le socket de contrôle (un JSON par ligne), les messages du wrapper cluster-run, les points d'accès de l'API web et le pont MCP.
1. Control socketSocket de contrôle
The core listens on a unix socket, $XDG_RUNTIME_DIR/claude-cluster/control.sock (CLAUDE_CLUSTER_SOCKET overrides it; the folder is 0700, the socket 0600: only your user reaches it). A connection carries any number of requests; each is one JSON object on one line and gets one JSON line back:
{"cmd": "list"}
{"ok": true, "data": [ ... ]}
{"ok": false, "error": "no such session: s9"}| Field | Meaning |
|---|---|
cmd | the command: list, status, send, spawn, allow, mode, model, task_add, schedule_add, web, usage, taxonomy, settings_get, settings_set, heavy_run, job_*... (the headless commands of the CLI, plus the ones of the interfaces and the MCP tools) |
session | id (s1, g), name or name prefix |
origin | set by the transport: mcp (the global session: its limits and its [mcp_tools] switches apply), sub (the small MCP of a sub-session, with owner: its own tasks and schedules only), web (a web device: read only for what the settings do not open) |
client, v, build | an interface of another process: its id, the version of the state it has, its build id |
Special commands: hello returns the version, build id, pid and binary of the core (an interface asks before attaching); sync is a long poll: it returns the whole state of the interface once its version v changes (up to 10 s), and is refused when the build id differs.
A request never stops the core: anything it throws is answered as {"ok": false, "error": "bad request: ..."}.
Le cœur écoute sur un socket unix, $XDG_RUNTIME_DIR/claude-cluster/control.sock (CLAUDE_CLUSTER_SOCKET le remplace ; le dossier est en 0700, le socket en 0600 : seul votre utilisateur l'atteint). Une connexion porte un nombre quelconque de requêtes ; chacune est un objet JSON sur une ligne et reçoit une ligne JSON en retour :
{"cmd": "list"}
{"ok": true, "data": [ ... ]}
{"ok": false, "error": "no such session: s9"}| Champ | Sens |
|---|---|
cmd | la commande : list, status, send, spawn, allow, mode, model, task_add, schedule_add, web, usage, taxonomy, settings_get, settings_set, heavy_run, job_*... (les commandes headless de la CLI, plus celles des interfaces et des outils MCP) |
session | identifiant (s1, g), nom ou préfixe de nom |
origin | posé par le transport : mcp (la session globale : ses limites et ses interrupteurs [mcp_tools] s'appliquent), sub (le petit MCP d'une sous-session, avec owner : ses propres tâches et planifications seulement), web (un appareil web : lecture seule pour ce que les réglages n'ouvrent pas) |
client, v, build | une interface d'un autre processus : son identifiant, la version de l'état qu'elle a, son identifiant de build |
Commandes spéciales : hello rend la version, l'identifiant de build, le pid et le binaire du cœur (une interface le demande avant de s'attacher) ; sync est une longue interrogation : elle rend tout l'état de l'interface dès que sa version v change (jusqu'à 10 s), et est refusée quand l'identifiant de build diffère.
Une requête n'arrête jamais le cœur : tout ce qu'elle lève est rendu en {"ok": false, "error": "bad request: ..."}.
2. cluster-runcluster-run
cluster-run [--class c] [--prio n] [--name x] [--cwd d] [--session id] -- cmd... talks to the same socket with a stream:
| Direction | Message |
|---|---|
| wrapper to core | {"cmd":"job_run","session","class","prio","name","cwd","argv","wrapper_pid"} |
| core to wrapper | {"ok":true,"event":"queued","id","position","total","waiting_for","eta_s"} (again when it changes) |
| core to wrapper | {"ok":true,"event":"go","id","threads","profile","nice","io_class","io_level"} |
| wrapper to core | {"event":"started","pid"}, later {"event":"exit","code","signal","tail"} |
| core to wrapper | {"event":"killed","by","reason"} |
The slot is released at exit or when the connection drops (the wrapper died: the command's process group is terminated). Without a core the wrapper runs the command directly; when the connection drops while queued it retries for 30 s, then runs directly.
cluster-run [--class c] [--prio n] [--name x] [--cwd d] [--session id] -- cmd... parle au même socket avec un flux :
| Sens | Message |
|---|---|
| wrapper vers cœur | {"cmd":"job_run","session","class","prio","name","cwd","argv","wrapper_pid"} |
| cœur vers wrapper | {"ok":true,"event":"queued","id","position","total","waiting_for","eta_s"} (de nouveau quand ça change) |
| cœur vers wrapper | {"ok":true,"event":"go","id","threads","profile","nice","io_class","io_level"} |
| wrapper vers cœur | {"event":"started","pid"}, puis {"event":"exit","code","signal","tail"} |
| cœur vers wrapper | {"event":"killed","by","reason"} |
Le créneau est libéré à exit ou quand la connexion tombe (le wrapper est mort : le groupe de processus de la commande est terminé). Sans cœur le wrapper lance la commande directement ; quand la connexion tombe pendant l'attente, il réessaie 30 s puis lance directement.
3. Web APIAPI web
The web access serves a single page and a small JSON API over https, only after login (the 6-digit code, then your approval); the session cookie is bound to the address of the device. The endpoints:
| Path | Use |
|---|---|
/, /index.html, /sw.js | the page and its service worker |
/api/login, /api/logout, /api/ping, /api/version | authentication, round trip, version (version is public) |
/api/state | the state of the cluster (long poll) |
/api/cmd | a control command (origin: "web") |
/api/complete | completions of the prompt |
/api/attach, /api/attach/file, /api/attach/link, /api/attach/list, /api/attach/remove | attachments |
/api/display, /api/file | a display picture; a file of a display |
/api/notify?since=N | the notification log (long poll, the Android app) |
/api/listen, /api/say | the voice of the page |
/api/tty/* (open, read, write, resize, close, ws) | the terminal mode, on its own port ([web] tty_port) |
/ca.crt, /app.apk | served to anyone: the authority certificate and the Android app |
/docs/* | this documentation, served without login |
L'accès web sert une page unique et une petite API JSON en https, seulement après connexion (le code à 6 chiffres, puis votre accord) ; le cookie de session est lié à l'adresse de l'appareil. Les points d'accès :
| Chemin | Usage |
|---|---|
/, /index.html, /sw.js | la page et son service worker |
/api/login, /api/logout, /api/ping, /api/version | authentification, aller-retour, version (la version est publique) |
/api/state | l'état du cluster (longue interrogation) |
/api/cmd | une commande de contrôle (origin: "web") |
/api/complete | complétions du prompt |
/api/attach, /api/attach/file, /api/attach/link, /api/attach/list, /api/attach/remove | pièces jointes |
/api/display, /api/file | l'image d'un affichage ; un fichier d'un affichage |
/api/notify?since=N | le journal des notifications (longue interrogation, l'application Android) |
/api/listen, /api/say | la voix de la page |
/api/tty/* (open, read, write, resize, close, ws) | le mode terminal, sur son propre port ([web] tty_port) |
/ca.crt, /app.apk | servis à tous : le certificat de l'autorité et l'application Android |
/docs/* | cette documentation, servie sans connexion |
4. The MCP bridgeLe pont MCP
claude-cluster mcp speaks the Model Context Protocol on stdio. tools/list returns the tools; tools/call maps the tool name to a control command (session_display to display, jobs_add to job_add, ...) and sets origin. The environment variable CLAUDE_CLUSTER_SESSION makes it the MCP of a sub-session. A tool turned off in [mcp_tools] is refused at once with a message for the user.
claude-cluster mcp parle le Model Context Protocol sur stdio. tools/list rend les outils ; tools/call associe le nom de l'outil à une commande de contrôle (session_display vers display, jobs_add vers job_add, ...) et pose origin. La variable d'environnement CLAUDE_CLUSTER_SESSION en fait le MCP d'une sous-session. Un outil désactivé dans [mcp_tools] est refusé aussitôt avec un message pour l'utilisateur.