Skip to content

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.

Terminal window
odette --pod release --role supervisor # in one terminal
odette --pod release -w # in others

The 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.

  1. 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"
  2. In two more terminals, start the workers. Each gets its own worktree, so they cannot overwrite each other:

    Terminal window
    odette --pod release -w
    odette --pod release -w
  3. 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.

  4. 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.

  5. When a worker’s context runs long, the supervisor clears it after a handoff, or you do from Sessions (below).

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.

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).

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.

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.

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.
Terminal window
odette config set feature.self_clear on
odette config set feature.pod_clear off

Things 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.
Theme