claude-cluster docs1.10.1
ReferenceRéférence

ArchitectureArchitecture

One core, many interfaces: the processes, the sessions, the MCP server and how the parts talk.Un cœur, plusieurs interfaces : les processus, les sessions, le serveur MCP et comment les parties se parlent.

1. OverviewVue d'ensemble

claude-cluster is one C++20 program. A single core per user owns the sessions; every terminal, window, web page and phone is an interface of that core.

terminal (FTXUI) window (Qt6) web page, phone app CLI (headless) core (claude-cluster serve)Manager · Control socket · Web server · Orchestrator · Voice global session (claude) sub-sessions (agents) cluster-run MCP server
Figure 1: interfaces and agents around the core.

claude-cluster est un seul programme C++20. Un unique cœur par utilisateur possède les sessions ; chaque terminal, fenêtre, page web et téléphone est une interface de ce cœur.

terminal (FTXUI) fenêtre (Qt6) page web, appli téléphone CLI (sans interface) cœur (claude-cluster serve)Manager · socket Control · serveur Web · Orchestrator · Voice session globale (claude) sous-sessions (agents) cluster-run serveur MCP
Figure 1 : interfaces et agents autour du cœur.

2. The coreLe cœur

The core is started by the first terminal or window (claude-cluster serve --linger) or by the systemd service; it stops when the last interface is closed (unless a session is still working and you chose to keep it). It holds:

  • Manager: the sessions, the trash, tasks, schedules, groups, the taxonomy, usage, statistics.
  • Control: a unix socket served in a thread per connection; the CLI, the MCP server, the other interfaces and cluster-run talk to it (see the protocol).
  • Web: the https server of the web access, the terminal page and the docs.
  • Orchestrator: the queue of heavy jobs, with its scheduler thread (Orchestrator).
  • Voice: voice-listen and voice-say processes.

Interfaces of other processes sync their state from the core and their actions run there. A build id (its version and the date of its binary) is checked at attach: another build is refused until replaced.

Le cœur est lancé par le premier terminal ou la première fenêtre (claude-cluster serve --linger) ou par le service systemd ; il s'arrête quand la dernière interface est fermée (sauf si une session travaille encore et que vous avez choisi de la garder). Il contient :

  • Manager : les sessions, la corbeille, les tâches, planifications, groupes, la taxonomie, l'usage, les statistiques.
  • Control : un socket unix servi dans un thread par connexion ; la CLI, le serveur MCP, les autres interfaces et cluster-run lui parlent (voir le protocole).
  • Web : le serveur https de l'accès web, la page terminal et les docs.
  • Orchestrator : la file des travaux lourds, avec son thread d'ordonnancement (Orchestrateur).
  • Voice : les processus voice-listen et voice-say.

Les interfaces d'autres processus synchronisent leur état depuis le cœur et leurs actions s'y exécutent. Un identifiant de build (sa version et la date de son binaire) est vérifié à l'attachement : un autre build est refusé jusqu'au remplacement.

3. Sessions and agentsSessions et agents

Every session is a child process of the core, run through env -C <folder> VAR=... with the provider environment; every pipe end is close-on-exec so a session never keeps another one's pipes. The agents run in their own session (setsid): the signals of your terminal never reach them.

core
├── global session  claude -p --input-format stream-json ... --mcp-config mcp.json
├── session s1      claude -p stream-json  (permissions: --permission-prompt-tool stdio)
├── session s2      qwen -p ... -o stream-json -r <id>       (one process per turn)
└── session s3      opencode run --format json -s <id>        (one process per turn)

The claude driver keeps one process per session with live permissions and an MCP server; the others (Qwen Code, opencode, Codex) start one process per turn and resume the conversation by id.

Chaque session est un processus fils du cœur, lancé par env -C <dossier> VAR=... avec l'environnement du fournisseur ; chaque extrémité de tube est close-on-exec pour qu'une session ne garde jamais les tubes d'une autre. Les agents tournent dans leur propre session (setsid) : les signaux de votre terminal ne les atteignent jamais.

core
├── session globale  claude -p --input-format stream-json ... --mcp-config mcp.json
├── session s1       claude -p stream-json  (permissions : --permission-prompt-tool stdio)
├── session s2       qwen -p ... -o stream-json -r <id>       (un processus par tour)
└── session s3       opencode run --format json -s <id>        (un processus par tour)

Le pilote claude garde un processus par session avec permissions en direct et un serveur MCP ; les autres (Qwen Code, opencode, Codex) lancent un processus par tour et reprennent la conversation par son identifiant.

4. The MCP serverLe serveur MCP

claude-cluster mcp is a small stdio MCP server started by the global session. It turns each tool call into a request on the control socket, with origin: "mcp" (the limits you set for the global session), or origin: "sub" plus the session id for a sub-session's own small MCP. Results are compact JSON without empty fields.

claude-cluster mcp est un petit serveur MCP sur stdio lancé par la session globale. Il transforme chaque appel d'outil en requête sur le socket de contrôle, avec origin: "mcp" (les limites que vous avez fixées pour la session globale), ou origin: "sub" plus l'identifiant de session pour le petit MCP propre d'une sous-session. Les résultats sont du JSON compact sans champs vides.

5. Source layoutOrganisation des sources

PartFiles
coreCore.cpp, Manager*.cpp, Session.cpp, Store.cpp, Config.cpp, Auth.cpp
control and toolsControl.cpp, Mcp.cpp, Actions.cpp, Settings.cpp, Tools.cpp
webWeb.cpp, WebTty.cpp, WebVoice.cpp, templates/web.html, templates/tty.html
front-endsui/Tty.cpp, ui/TtyGraph.cpp, ui/Gui.cpp, ui/LineEditor.cpp, ui/Popup.cpp
orchestratorOrchestrator*.cpp, Hardware.cpp, RunProfile.cpp, run/cluster-run.cpp
voiceVoice.cpp, VoiceEngines.cpp, Vocabulary.cpp, templates/wake.py
tasksManager-Tasks.cpp, Manager-Schedules.cpp, Cron.cpp
taxonomy, usage, statsTaxonomy.cpp, Manager-Usage.cpp, Usage.cpp, Stats.cpp

Dependencies: libutils, nlohmann/json, toml++, FTXUI, Qt6 Widgets (optional) and OpenSSL (optional). The default prompts and the config template are embedded in the binary from templates/ at build time.

PartieFichiers
cœurCore.cpp, Manager*.cpp, Session.cpp, Store.cpp, Config.cpp, Auth.cpp
contrôle et outilsControl.cpp, Mcp.cpp, Actions.cpp, Settings.cpp, Tools.cpp
webWeb.cpp, WebTty.cpp, WebVoice.cpp, templates/web.html, templates/tty.html
interfacesui/Tty.cpp, ui/TtyGraph.cpp, ui/Gui.cpp, ui/LineEditor.cpp, ui/Popup.cpp
orchestrateurOrchestrator*.cpp, Hardware.cpp, RunProfile.cpp, run/cluster-run.cpp
voixVoice.cpp, VoiceEngines.cpp, Vocabulary.cpp, templates/wake.py
tâchesManager-Tasks.cpp, Manager-Schedules.cpp, Cron.cpp
taxonomie, usage, statsTaxonomy.cpp, Manager-Usage.cpp, Usage.cpp, Stats.cpp

Dépendances : libutils, nlohmann/json, toml++, FTXUI, Qt6 Widgets (optionnel) et OpenSSL (optionnel). Les prompts par défaut et le modèle de config sont embarqués dans le binaire depuis templates/ à la compilation.