Sub-sessionsSous-sessions
What a sub-session is, and how it differs from a fork and from a Claude Code subagent.Ce qu'est une sous-session, et en quoi elle diffère d'un fork et d'un sous-agent de Claude Code.
Everything in claude-cluster is a session: one running agent (Claude Code by default) in one project folder, with its own conversation, mode, model and permissions. The session you talk to through the global session are its sub-sessions.
Tout, dans claude-cluster, est une session : un agent en cours (Claude Code par défaut) dans un dossier de projet, avec sa conversation, son mode, son modèle et ses permissions. Les sessions auxquelles vous parlez à travers la session globale sont ses sous-sessions.
1. What a sub-session isCe qu'est une sous-session
A sub-session is a full agent process of its own:
- one folder (a project of the map of your computer), one conversation that survives restarts (
--resume), one mode (auto,manual,acceptEdits,plan,dontAsk,bypassPermissions), one model and thinking effort; - it is shown in every interface (terminal, window, web page, phone) as a row with its state, its short description, its category and tags;
- it is created by you (
/new, Ctrl+T,claude-cluster spawn) or by the global session (session_spawn), and closed to the trash (restorable fortrash_days) or deleted for good; - the claude driver keeps one process per session with live permissions and its own small MCP server; the other drivers (Codex, opencode, Qwen Code) start one process per turn and resume the conversation by id.
The global session stays one level above: it dispatches your requests, reads the answers (they come back as [reply from <name> (<id>)], no polling) and merges them.
Une sous-session est un vrai processus d'agent à part :
- un dossier (un projet de la carte de votre ordinateur), une conversation qui survit aux redémarrages (
--resume), un mode (auto,manual,acceptEdits,plan,dontAsk,bypassPermissions), un modèle et un effort de réflexion ; - elle apparaît dans toutes les interfaces (terminal, fenêtre, page web, téléphone) comme une ligne avec son état, sa courte description, sa catégorie et ses tags ;
- elle est créée par vous (
/new, Ctrl+T,claude-cluster spawn) ou par la session globale (session_spawn), et fermée vers la corbeille (restaurable pendanttrash_days) ou supprimée pour de bon ; - le pilote claude garde un processus par session avec des permissions en direct et son propre petit serveur MCP ; les autres pilotes (Codex, opencode, Qwen Code) lancent un processus par tour et reprennent la conversation par son identifiant.
La session globale reste un niveau au-dessus : elle répartit vos demandes, lit les réponses (elles lui reviennent en [reply from <nom> (<id>)], sans interrogation) et les fusionne.
2. Compared with a forkComparée à un fork
A fork (claude-cluster fork <s>, palette Fork the session) is only a way to start a session: a copy of a Claude Code conversation so far, after which each copy goes its own way. The result is two ordinary sub-sessions. Use it to give a new session the context of another one. The global session may fork only when you allowed it (Global session can fork, off by default).
Un fork (claude-cluster fork <s>, palette Fork the session) n'est qu'une façon de démarrer une session : une copie d'une conversation Claude Code à ce jour, puis chaque copie suit son chemin. Le résultat, ce sont deux sous-sessions ordinaires. Utilisez-le pour donner à une nouvelle session le contexte d'une autre. La session globale ne peut forker que si vous l'avez autorisé (Global session can fork, désactivé par défaut).
3. Compared with a Claude Code subagentComparée à un sous-agent de Claude Code
A subagent is a feature inside one Claude Code session: the agent delegates a job to a helper with its own context window and gets a summary back. It is invisible to claude-cluster.
| Sub-session | Fork | Claude Code subagent | |
|---|---|---|---|
| Visible in the interfaces | yes, a row of its own | yes, once started | no, inside its parent |
| Own conversation kept | yes | yes (copied at start) | no, a summary returns |
| Own mode / model / permissions | yes | yes | those of its parent |
| You can talk to it | yes | yes | no |
| Started by | you or the global session | you | the agent itself |
| Costs | its own tokens | its own tokens | tokens of the parent session |
Un sous-agent est une fonction à l'intérieur d'une session Claude Code : l'agent confie un travail à un assistant avec sa propre fenêtre de contexte et reçoit un résumé. claude-cluster ne le voit pas.
| Sous-session | Fork | Sous-agent Claude Code | |
|---|---|---|---|
| Visible dans les interfaces | oui, une ligne à elle | oui, une fois démarré | non, dans son parent |
| Conversation propre conservée | oui | oui (copiée au départ) | non, un résumé revient |
| Mode / modèle / permissions propres | oui | oui | ceux de son parent |
| Vous pouvez lui parler | oui | oui | non |
| Démarrée par | vous ou la session globale | vous | l'agent lui-même |
| Coût | ses propres tokens | ses propres tokens | tokens de la session parente |
4. Limits and good practiceLimites et bonnes pratiques
[sessions] max_parallelcaps the sub-sessions working at once; more tasks wait in the queue (task_queuebounds it). See Tasks and schedules.- Heavy builds and tests go through the orchestrator, never several at once from several sessions.
- A session made for one precise job can be created
one_shot: it goes to the trash by itself once its answer was relayed. See One-shot sessions. - Moving a large session to a stronger model re-reads its whole context at the new price (asked first while it is loaded): prefer a new sub-session with a short brief (Permissions and models).
- The context of a sub-session is capped by
[sessions] context(auto, or 100k to 1M: compacted past it); the global session may give each one its own when it starts it (session_spawncontext:150kfor a small fix), so every turn and a wake-up after its cache expired cost what the task needs (Settings).
A sub-session of the claude driver gets a small scoped MCP (task_*, schedule_*): it sees and manages only the tasks and schedules it made.
[sessions] max_parallelplafonne les sous-sessions qui travaillent en même temps ; les autres tâches attendent dans la file (task_queuela borne). Voir Tâches et planifications.- Les compilations et tests lourds passent par l'orchestrateur, jamais plusieurs à la fois depuis plusieurs sessions.
- Une session faite pour un travail précis peut être créée
one_shot: elle part à la corbeille d'elle-même une fois sa réponse relayée. Voir Sessions à usage unique. - Passer une grande session sur un modèle plus fort relit tout son contexte au nouveau prix (demandé d'abord tant qu'il est chargé) : préférez une nouvelle sous-session avec un bref énoncé (Permissions et modèles).
- Le contexte d'une sous-session est plafonné par
[sessions] context(auto, ou 100k à 1M : compacté au-delà) ; la session globale peut donner le sien à chacune quand elle la démarre (session_spawncontext:150kpour un petit correctif), pour que chaque tour et un réveil après l'expiration de son cache coûtent ce dont la tâche a besoin (Réglages).
Une sous-session du pilote claude reçoit un petit MCP restreint (task_*, schedule_*) : elle ne voit et ne gère que les tâches et planifications qu'elle a créées.