claude-cluster docs1.10.1
Advanced conceptsConcepts avancés

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 for trash_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 pendant trash_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-sessionForkClaude Code subagent
Visible in the interfacesyes, a row of its ownyes, once startedno, inside its parent
Own conversation keptyesyes (copied at start)no, a summary returns
Own mode / model / permissionsyesyesthose of its parent
You can talk to ityesyesno
Started byyou or the global sessionyouthe agent itself
Costsits own tokensits own tokenstokens 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-sessionForkSous-agent Claude Code
Visible dans les interfacesoui, une ligne à elleoui, une fois démarrénon, dans son parent
Conversation propre conservéeouioui (copiée au départ)non, un résumé revient
Mode / modèle / permissions propresouiouiceux de son parent
Vous pouvez lui parlerouiouinon
Démarrée parvous ou la session globalevousl'agent lui-même
Coûtses propres tokensses propres tokenstokens de la session parente

4. Limits and good practiceLimites et bonnes pratiques

  • [sessions] max_parallel caps the sub-sessions working at once; more tasks wait in the queue (task_queue bounds 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_spawn context: 150k for 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_parallel plafonne les sous-sessions qui travaillent en même temps ; les autres tâches attendent dans la file (task_queue la 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_spawn context : 150k pour 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.