Pods
A pod is a group of sessions that can message each other through Claude Code’s cross-session messaging. Sessions join a pod by name, from the same project or different ones.
odette --pod release --role supervisor # in one terminalodette --pod release -w # in othersThe launch prints pod <name> | session <id>. Inside the container, the pod
name and role are in ODETTE_POD and ODETTE_POD_ROLE, for your own hooks.
Example: a release with a supervisor and two workers
Section titled “Example: a release with a supervisor and two workers”Goal: one agent plans and reviews, two others each build a part, and you answer only what reaches you.
-
Start the supervisor in the project. odette asks you to confirm (
[y/N]), because a supervisor can direct work and approve merges:Terminal window odette --pod release --role supervisor --prompt "split the release checklist between two workers and review their branches" -
In two more terminals, start the workers. Each gets its own worktree, so they cannot overwrite each other:
Terminal window odette --pod release -wodette --pod release -w -
The supervisor messages the workers with their tasks and reads their status. A worker’s question for you goes to the supervisor first, which answers it or passes a reworded version on to you.
-
Open the dashboard. Overview shows the three sessions grouped under
release. Network and command approvals from any member come straight to you, never to the supervisor. -
When a worker’s context runs long, the supervisor clears it after a handoff, or you do from Sessions (below).
After a restart of the daemon
Section titled “After a restart of the daemon”A pod keeps working when the daemon restarts: the sessions reconnect on their own within a few seconds. A member can be missing from another member’s peer list until it takes its next turn, and a message to an address that is already known still goes through.
Pod volumes from older versions
Section titled “Pod volumes from older versions”Earlier versions mounted a shared volume named odette-pod-<name> into every
pod session. Nothing uses it now and odette clean no longer removes it. List
it with docker volume ls --filter label=odette.pod (or the same listing with
your runtime’s command) and remove it with docker volume rm.
--role is a free-form label and needs --pod. Two values change what odette
tells the session:
| Role | The session is told to |
|---|---|
supervisor |
Direct and review the other members’ work rather than do it alone; read their status instead of asking; clear a member when its context runs long. |
conductor |
Do the work through its own sub-agents, and report progress to the supervisor if there is one. |
| anything else, or none | Report progress to the supervisor, if there is one. |
Members are told to act on messages from a verified supervisor without
asking you first. A supervisor can direct work, answer members’ questions and
approve merges on your behalf, so launching one asks you to confirm ([y/N],
30 seconds, default no).
Questions in a pod
Section titled “Questions in a pod”When a pod member files a decision or action (Approvals), it goes to the supervisor first. The supervisor can answer it, or pass a reworded version on to you. Approvals for the gates always come to you.
Seeing what members do
Section titled “Seeing what members do”Each session reports what it is for and what it is doing now. You see this in the dashboard’s Sessions zone; a supervisor reads its members’ status, including their context use, directly.
Clearing a session’s context
Section titled “Clearing a session’s context”A long-running session eventually fills its context. A pod session can be cleared after it writes a handoff, then told to pick up from it, without you typing into its terminal.
| Who clears | How | Approval |
|---|---|---|
| You | Dashboard Sessions → select the session → Clear context with handoff | Your click is the approval. |
| The supervisor | Clears a member when it judges the member’s context too full | Goes through the member’s command gate: in manual mode you get an approval card. |
| The session itself | A supervisor or conductor clears itself after writing its handoff | Goes through its own command gate. |
The dashboard button appears only once the session has finished at least one turn, so odette knows when it is idle.
Feature flags control this (Configuration):
| Flag | Default | Turns on |
|---|---|---|
pod_clear |
on | Clearing pod sessions at all (dashboard and supervisor). |
self_clear |
off | A supervisor or conductor clearing itself. Needs pod_clear. |
odette config set feature.self_clear onodette config set feature.pod_clear offThings to know:
- odette clears a session by typing into its terminal. Text you have half-typed at that prompt gets the typed text appended. Leave a pod session’s prompt empty.
- A member cleared by its supervisor messages the supervisor once it has cleared. A message sent to it before then lands in the old context.
- A session started by an older odette may clear but never check in. Relaunch it with the current odette.