Sessions and handoff

claudio talks and your sessions work. Use this page to send a task to a session, open new sessions, check what one is doing, and choose which of their reports you hear.

A session is a coding agent working on a task, such as a Claude Code session. Where your sessions live is the backend setting: cmux (each session is a cmux pane) or bb (each session is a bb thread). The rules on this page are the same on both; on each platform says where they differ.

Choose the orchestratorCopy Anchor Link

The orchestrator is the session that gets your tasks unless you name another. You pick it during setup, by its title. To change it, say "the orchestrator is Core now", or run:

claudio set orchestrator Core

To use a different orchestrator in one project, put a .claudio.json in that project:

{ "orchestrator": "Core" }

Hand work to a sessionCopy Anchor Link

When you ask for work, the brain sends it to the orchestrator. With permission checks on, claudio itself asks first, every time, and only your yes sends it; there's no “always” for sends:

A message of more than 25 words is read by its start: its first 12 words, then how many more there are. Say “read it all” and the brain reads you the whole message; a yes in the next two minutes sends it.

A question is never an order: “should I merge?” gets the brain's view, not a send. With permission checks off, it sends without that question.

The message starts with a marker, so the session knows the words are yours and not the brain's:

[spoken by the user, transcribed by claudio] rebase 44 on main and run the tests

The brain passes on your words and any detail you gave. It never puts the marker on something you didn't say.

To send work elsewhere, name the session: "ask Core to update the changelog". Sessions come and go, so whenever you name or ask about one, the brain lists them again rather than trust the list it started with.

Open a new sessionCopy Anchor Link

Ask for one ("open a session called Core") and the brain opens it, in the project you name or the one claudio runs in. claudio asks first, as for a send, when the new session starts with your task. A new session takes a few seconds to start, so the brain waits before handing it work.

Check on a sessionCopy Anchor Link

Ask "what's Sequencer doing?" and the brain reads what that session has been doing and sums it up in a sentence or two. It doesn't ask you first.

The state line also shows the orchestrator's state, checked every 5 seconds:

If the orchestrator stays waiting on you for 2 minutes, claudio tells you once, unless you're muted or it's already speaking.

To stop a running session, stop it where it runs. claudio can't stop it for you.

Hear what sessions report backCopy Anchor Link

Three Claude Code hooks, which setup installs, report from every Claude Code session:

• Stop
• Notification
• PreToolUse with matcher AskUserQuestion

When claudio isn't running, each hook exits at once, so they cost nothing the rest of the time.

A session finished your taskCopy Anchor Link

When a session finishes a turn on work you handed it in the last 30 minutes, claudio narrates the result under a header naming the request:

Finished turns come from the hooks, so only Claude Code sessions report them.

A session needs permissionCopy Anchor Link

When a session stops at a permission prompt, claudio shows the prompt, tells you which session wants what, and asks you:

Say yes, always or no, or press 1, 2 or 3. “Always” is offered only when the prompt has such an option. claudio itself, not the brain, takes your answer and gives it to the session, so nothing a session prints can answer it. Ask a question back ("what does that do?") and the brain answers; a yes in the next two minutes still counts. Say anything else and the prompt waits for you in the session.

Each prompt is read out once. When claudio is already asking you something, it reads the new one out and leaves you to answer it in the session.

A session asks you to chooseCopy Anchor Link

When a session asks a multiple-choice question, claudio reads the question and its options aloud, numbered, and waits. Tell it your choice and it confirms what it understood, then answers the session with the option you picked. For a question that takes several, name them all. For an answer in your own words, say them. You can always answer in the session yourself instead.

Choose which reports you hearCopy Anchor Link

The narrate setting decides what you hear from sessions:

Change it with claudio set narrate all. claudio also ignores:

• Its own brain's session
• Sessions outside the platform backend names, since it can't tell which session they are
• Everything, while you're muted

On each platformCopy Anchor Link

The rules above hold everywhere. What changes is how claudio reaches a session:

The platform pages have the detail: cmux and bb.