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.
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.
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-runtalk 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-listenandvoice-sayprocesses.
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-runlui 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-listenetvoice-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
| Part | Files |
|---|---|
| core | Core.cpp, Manager*.cpp, Session.cpp, Store.cpp, Config.cpp, Auth.cpp |
| control and tools | Control.cpp, Mcp.cpp, Actions.cpp, Settings.cpp, Tools.cpp |
| web | Web.cpp, WebTty.cpp, WebVoice.cpp, templates/web.html, templates/tty.html |
| front-ends | ui/Tty.cpp, ui/TtyGraph.cpp, ui/Gui.cpp, ui/LineEditor.cpp, ui/Popup.cpp |
| orchestrator | Orchestrator*.cpp, Hardware.cpp, RunProfile.cpp, run/cluster-run.cpp |
| voice | Voice.cpp, VoiceEngines.cpp, Vocabulary.cpp, templates/wake.py |
| tasks | Manager-Tasks.cpp, Manager-Schedules.cpp, Cron.cpp |
| taxonomy, usage, stats | Taxonomy.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.
| Partie | Fichiers |
|---|---|
| cœur | Core.cpp, Manager*.cpp, Session.cpp, Store.cpp, Config.cpp, Auth.cpp |
| contrôle et outils | Control.cpp, Mcp.cpp, Actions.cpp, Settings.cpp, Tools.cpp |
| web | Web.cpp, WebTty.cpp, WebVoice.cpp, templates/web.html, templates/tty.html |
| interfaces | ui/Tty.cpp, ui/TtyGraph.cpp, ui/Gui.cpp, ui/LineEditor.cpp, ui/Popup.cpp |
| orchestrateur | Orchestrator*.cpp, Hardware.cpp, RunProfile.cpp, run/cluster-run.cpp |
| voix | Voice.cpp, VoiceEngines.cpp, Vocabulary.cpp, templates/wake.py |
| tâches | Manager-Tasks.cpp, Manager-Schedules.cpp, Cron.cpp |
| taxonomie, usage, stats | Taxonomy.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.