MrVPlusOne/takode-orchestration

Takode -- Cross-Session CLI Reference

The takode CLI lets you interact with other sessions managed by the Companion server. Read-only commands work for all sessions. Mutation commands (send, rename, herd, spawn, interrupt) require the orchestrator role (TAKODE_ROLE=orchestrator env var).

Environment

• TAKODE_API_PORT -- the Companion server port (used automatically by the CLI)
• COMPANION_SESSION_ID -- your own session ID
• The takode command is available at ~/.companion/bin/takode (or on PATH)
• Works with both Claude Code and Codex sessions

Sub-Skill Workflows

Read these files or invoke these skills when performing the corresponding operation:

| Workflow | When to use | Source | |----------|------------|--------| | Dispatching work | Before choosing a worker and sending a quest | Invoke /leader-dispatch | | Quest Journey | Advancing a quest through its lifecycle | quest-journey.md | | Work board | Managing the quest board | board-usage.md |

Key Principles

• Quests are the unit of work. Create a quest for any non-trivial task before dispatching.
• Never implement non-trivial changes yourself. Leaders brainstorm, create quests, dispatch, steer, and review -- they do not write code. Investigation and research are also work to delegate.
• Never run quest claim yourself. Workers claim quests when dispatched. Leaders coordinate, workers claim.
• Before dispatching any quest, ALWAYS invoke /leader-dispatch. The dispatch message to the worker must use the standardized template. Do not add extra context, file paths, or investigation instructions -- add any extra information into the quest itself before dispatching.
• Events are push-based. Herd events arrive as [Herd] user messages when idle. No polling.
• Reference, don't relay. Point to source messages instead of paraphrasing.
• Workers have the same tools you do. Give them the quest ID; they run quest show themselves.
• One task at a time per worker. Mid-task steering is fine; unrelated new tasks queue.
• User feedback triggers full rework. When a user reports issues with a completed quest, record feedback, set the quest back to refined, and dispatch for a full quest journey. Never skip review steps for "small" fixes. See quest-journey.md.
• Don't echo board state as prose. takode board commands display the board in the terminal with a special UI. Never repeat that information as markdown tables or summaries -- just run the command and move on.
• Never skip quest journey stages. Every quest gets the full lifecycle: PLANNING → IMPLEMENTING → SKEPTIC_REVIEWING → GROOM_REVIEWING → PORTING. No exceptions for "small" changes.
• Never use AskUserQuestion or EnterPlanMode. These block your turn and prevent herd event processing. Ask clarifying questions in plain text output, or use takode notify needs-input for non-blocking user notifications.
• Use takode notify at these moments: needs-input when a quest/worker is blocked and genuinely needs the user's decision before proceeding (e.g., scope unclear, design choice needed); review when a quest completes the full journey and is ported.

Herd Events

Events from herded sessions are delivered automatically as [Herd] user messages when you go idle. No polling needed.

Message Source Tags

• [User HH:MM] -- human operator
• [Herd HH:MM] -- automatic event summary from herded sessions
• [Agent #N name HH:MM] -- forwarded from another agent/session

Event Types and Reactions

| Event | Meaning | Action | |-------|---------|--------| | turn_end (✓) | Worker completed successfully | Peek at output, send follow-up or mark done. In PLANNING, this may contain a plain-text plan that should be reviewed and answered with normal takode send rather than takode answer | | turn_end (✗) | Worker hit an error | Diagnose the issue, send recovery instructions | | turn_end (⊘) | User interrupted the worker | Check if it needs redirection | | permission_request | Worker needs approval | For AskUserQuestion/ExitPlanMode, answer with takode answer. Tool permissions are human-only. If (user-initiated), don't answer -- the user is handling it | | permission_resolved | Worker was unblocked | No action needed | | session_error | Session-level error | Investigate, decide whether to retry | | user_message [User] | Human sent directly to worker | May indicate new instructions -- stay aware but don't interfere |

Session Lifecycle

Three distinct operations -- never confuse them:

| Command | What it does | Session after | |---------|-------------|---------------| | takode interrupt <N> | Halts the worker's current turn (SIGTERM) | Active, idle, ready for new work | | takode archive <N> | Removes session from active herd | Archived, history still readable | | Disconnect (idle manager) | CLI process killed automatically | Disconnected (✗), auto-relaunches on takode send |

Key rule: When you interrupt a worker, say "interrupted" -- never "archived" or "stopped".

Maintaining Focus

• Don't let herd events override your decision to wait for the user. If you asked the user a question, keep waiting even if herd events arrive. Acknowledge events briefly, but don't proceed until the user responds.
• When the user is directly steering a herded worker: stay out of it. Resume normal coordination once the user stops interacting.
• After context compaction, refresh state. Run takode list to see your herd with each worker's recent task history before making dispatch decisions.

User Notifications

Tie takode notify calls to Quest Journey events:

• takode notify review "q-42 ready for verification": when a quest completes the full Journey (removed from board and transitioned to needs_verification)
• takode notify needs-input "need decision on auth approach for q-42": when the user needs to make a decision or provide information and no built-in tool covers it

Do not notify for routine progress or intermediate steps.

Read-Only Commands

These commands work for any session.

takode list [--herd] [--active] [--all] [--json]

List sessions. Default shows all unarchived sessions. Use --herd (or just takode list as leader) to see only your herded sessions. Use --all to include archived.

takode list          # leader default: herded sessions only
takode list --herd   # explicit: herded sessions only
takode list --active # all unarchived sessions
takode list --all    # include archived

Output shows: #N session number, status icon, name, role labels, quest status, branch info, last activity.

When referencing a session in chat, use [#N](session:N) (example: [#5](session:5)).

takode search <query> [--all] [--json]

Search sessions by name, keyword, task title, branch, message, or path.

takode search auth
takode search jwt --all

takode info <session> [--json]

Show detailed session metadata: identity, backend, working directory, git state, worktree info, quest claim, metrics, and timestamps.

takode info 1
takode info 1 --json

Human-readable output shows a structured overview with sections for identity (UUID, CLI session ID, PID), backend (type, model, version, permissions), working directory, git state (branch, ahead/behind, diff stats), roles, quest claim, metrics (turns, cost, context usage), MCP servers, and timestamps.

Use --json for programmatic access to all fields.

takode tasks <session> [--json]

Show the task outline (table of contents) for a session's conversation history.

takode tasks 1

Tip: Run takode tasks first when investigating an unfamiliar session -- it gives you a high-level map of what the agent has been working on.

takode scan <session> [--from N] [--until N] [--count N] [--json]

Scan session turns as collapsed summaries. Like a table of contents for the conversation -- shows each turn's trigger (user/herd message), assistant response, message range, duration, and tool count. Scans backward from the end by default (most recent turns first). Paginated by turn number (default: 50 turns per page).

takode scan 1                       # last 50 turns (most recent)
takode scan 1 --from 0              # turns 0-49 (from the beginning)
takode scan 1 --until 100           # 50 turns ending before turn 100 (turns 50-99)
takode scan 1 --from 50 --count 20  # turns 50-69

Each turn shows the trigger message and the assistant's response. Compaction events appear as markers between turns:

Turn 42 · [821]-[827] · 18:17-18:17 (15s) · 2 tools · ✓
  user: "check how #89 is doing"
  ...
  asst: "#89 has been idle since 2:02 PM..."
── Context compacted [828] (auto) ──
Turn 43 · [829]-[835] · 18:18-18:19 (45s) · 3 tools · ✓
  user: "run the tests"
  ...
  asst: "All 142 tests passed."

Use this to quickly understand what a session worked on across its entire history without reading every message. Drill into interesting turns with takode peek <session> --turn <N>.

takode peek <session> [--from N] [--until N] [--count N] [--turn N] [--task N] [--detail --turns N] [--json]

View session activity with progressive detail.

Default mode (smart overview) -- shows collapsed recent turns + expanded last turn:

takode peek 1

Collapsed turns include message ranges like Turn 5 · [42]-[58] · 14:22-14:25 (3s) · ✓ "Done", so you can quickly identify which messages belong to which turn.

Expand a specific turn -- shows all messages in turn N (0-indexed):

takode peek 1 --turn 5

Use this when you see an interesting collapsed turn and want its full messages without guessing message IDs.

Range browsing (paged history by message index):

takode peek 1 --from 500
takode peek 1 --from 500 --count 50
takode peek 1 --until 500

Task browsing -- expand messages for a specific task number:

takode peek 1 --task 3

Detail mode -- legacy full-detail view of the last N turns:

takode peek 1 --detail --turns 3

Navigation Workflow

1. takode info 1                          → Session metadata: backend, git, quest, metrics
2. takode tasks 1                         → Table of contents: tasks with msg ranges
3. takode scan 1                          → Turn-level scan (most recent first)
4. takode scan 1 --from 0                 → Scan from the beginning
5. takode peek 1                          → Overview: collapsed turns + expanded last turn
6. takode peek 1 --turn 5                 → Expand turn 5 (use turn number from scan)
7. takode peek 1 --task 3                 → Browse task 3's messages
8. takode peek 1 --from 800              → Browse messages [800]-[860] in detail
9. takode read 1 815                      → Full content of message 815
10. takode grep 1 "query"                 → Search within session messages (regex)
11. takode grep 1 "error" --type user     → Search only user messages
12. takode export 1 /tmp/s1.txt           → Dump full session for offline analysis

takode read <session> <msg-id> [--offset N] [--limit N] [--json]

Read full content of a specific message, with line numbers and pagination.

takode read 1 42
takode read 1 42 --offset 0 --limit 50

takode grep <session> <pattern> [--type user|assistant|result] [--count N] [--json]

Search within a session's message history. Uses JS/ERE regex (case-insensitive). Falls back to literal substring if the pattern is invalid regex. Use | for alternation, not \| (that's BRE syntax from grep/sed -- in JS regex it matches a literal pipe). Optional --type filter restricts matches to a specific message type.

takode grep 1 "authentication"
takode grep 1 "q-5[0-9]"                    # regex pattern
takode grep 1 "image|quality"               # alternation (matches either word)
takode grep 1 "error" --type user            # only user messages
takode grep 1 "commit.*synced" --type result  # only result messages
takode grep 1 "reward hacking" --count 20

Each match shows [msg-id] time type turn snippet. Use takode read <session> <msg-id> to see the full message, or takode peek <session> --turn <N> for the turn's context.

takode export <session> <path>

Export a session's full conversation history to a text file. The exported file includes turn headers and all message content, suitable for searching with standard tools (grep, etc).

takode export 1 /tmp/session-1.txt

takode notify <category> <summary>

Alert the user when they need to take action. Available to all sessions (not orchestrator-only). The notification anchors to your most recent assistant message. The summary is required -- always describe what specifically needs attention.

Categories: needs-input, review

takode notify review "q-42 ready for verification"
takode notify needs-input "need decision on auth approach for q-42"

takode pending <session>

Show pending permission requests for a session (questions, plans awaiting approval).

Orchestrator Commands

These commands require TAKODE_ROLE=orchestrator. Non-orchestrator sessions will get a permission error.

takode send <session> <message> [--correction]

Send a message to a herded worker session (injected as a user message). Requires herding first.

Syntax: The session ID must always be the first argument after send. Flags (--correction, --json) go after the message or at the end. Putting flags before the session ID will cause parse errors.

Use --correction to send a steering message to a session that is currently running (without it, sends to running sessions are blocked).

takode herd 2
takode send 2 "Please also add tests for the edge cases"
takode send 2 "Actually, skip the auth tests" --correction

Shell quoting safety. Do not put complex message text directly inside double quotes if it contains backticks, $(...), or other shell syntax. Your shell can execute that content locally before takode receives it. For multi-line or shell-like text, build the message with a single-quoted heredoc and pass the variable to takode:

msg=$(cat <<'EOF'
Investigate the failing path.
Treat `foo $(bar)` as literal text, not shell.
EOF
)
takode send 2 "$msg"
takode spawn --message "$msg"

takode herd <session> [<session> ...]

Claim worker sessions under your orchestrator. Each session can only have one leader.

takode herd 2 3 5

takode spawn [--backend claude|codex] [--count N] [--message "..."] [--cwd DIR] [--no-worktree] [--fixed-name "..."] [--reviewer <session>] [--json]

Create worker sessions and auto-herd them to yourself. Sessions always use worktrees by default. Never pass --no-worktree unless the user explicitly asks for it or the project's repo instructions require it -- even investigation and debugging tasks should get worktrees since they almost always lead to code changes. Use --fixed-name only for reviewer sessions (regular workers get auto-named from their quest). Use --reviewer <session> to create a reviewer session linked to a parent worker.

takode spawn                                                    # worktree session (default)
takode spawn --backend claude --count 3 --cwd ~/repos/app --message "Run tests"
takode spawn --reviewer 5 --no-worktree --fixed-name "Skeptic review of #5" --message "Review session #5 / quest q-42."

The same shell quoting rule applies to --message: avoid inline double-quoted dispatch bodies when the text may contain shell-like content. Use the heredoc pattern above instead.

takode rename <session> <name>

Rename a session.

takode rename 5 "Auth refactor worker"

takode interrupt <session>

Interrupt a worker's current turn (sends SIGTERM).

Interrupt ≠ archive. Interrupting only halts the worker's current turn -- the session stays active, its history and worktree are intact, and you can send it new work immediately. takode archive is a completely separate operation that removes the session from your active herd. Never tell the user you "archived" a session when you only interrupted it.

takode interrupt 2

takode answer <session> <response>

Answer a worker's pending question or plan approval request.

takode answer 2 1                          # pick option 1
takode answer 2 "custom answer"            # free text
takode answer 2 approve                    # approve a plan
takode answer 2 reject "add error handling" # reject with feedback

takode board [show|set|advance|rm]

Quest Journey work board. See board-usage.md for full usage and coordination patterns.

takode board show
takode board set <quest-id> [--worker N] [--status STATE] [--wait-for q-X,#Y]
takode board advance <quest-id>
takode board rm <quest-id> [<quest-id> ...]

Session Identification

Commands accept multiple formats:

• Integer number: 1, 3, 5 -- the short form from takode list
• UUID prefix: abc123 -- first chars of the full UUID
• Full UUID: 550e8400-e29b-41d4-a716-446655440000

Prefer integer numbers -- they're stable within a server session and easy to type.

Session Naming

Sessions start with random names and auto-rename on first message and turn completion. Quest claiming changes the session name to the quest title and pauses auto-naming while the quest is active. Only use --fixed-name for reviewer sessions -- regular workers should rely on auto-naming from their quest.

When referencing sessions, use session numbers (#107) which are stable -- names can change.

Disconnected Sessions

A ✗ disconnected session just means its CLI process was killed (usually by the idle manager). The session history, worktree, and quest claim are fully intact. Do not avoid disconnected sessions -- if one is the right fit for a task, use it. takode send auto-relaunches the CLI before delivering the message, so no extra reconnect step is needed.

Archiving Sessions

Maintain at most 5 sessions in your herd. Never archive proactively. Only archive when you are at the 5-session limit AND need to spawn a new worker. Idle and disconnected sessions retain valuable context -- keep them until you actually need the slot. When you must archive, choose the one least likely to be reused -- typically the one whose work is most complete, least related to upcoming tasks, or oldest. Archiving doesn't lose anything -- archived sessions' full conversation history remains readable via takode peek and takode read, and the Takode UI.

Tips

• Use peek over read to protect your context window -- peek gives truncated summaries. Drill into specific messages with read only when the summary isn't enough. Paginate long messages with --offset/--limit.
• Use --json for programmatic decisions. Parse JSON output when you need to branch on event data.
• Verify spawn settings. After takode spawn, check the output to confirm worktree and other settings match your intent. Never use --no-worktree unless the user explicitly requests it or the project instructions require it.
• Mixed backends work seamlessly. The takode CLI talks to the Companion server, not to any backend directly. You can orchestrate both Claude Code and Codex sessions from either backend.
• Coordinate with quests. Use the quest CLI alongside takode for task tracking. Always create a quest for non-trivial work before dispatching.
• Board immediately. When you intend to manage a quest (dispatch, review, port), put it on the work board right away (takode board set), even if it's QUEUED with --wait-for. The board is the tracking mechanism -- never rely on memory for follow-up dispatch. Exception: if the user only asked you to create/file the quest without dispatching, just create it and wait for their go-ahead.
• Batch related messages. If you need to send context + instructions to a worker, send it as one message rather than multiple.
• Don't interrupt idle workers. takode interrupt halts the worker's current turn. Only use it to redirect active work. Workers that finished a quest are already idle -- don't interrupt them unnecessarily.
• Say "interrupt", not "stop". When communicating with the user, prefer "interrupt" over "stop" to avoid confusion with archiving. "Interrupted #5" is unambiguous; "stopped #5" could imply the session was shut down.
• Events are push-based. Herd events arrive automatically as user messages when you go idle. No polling needed.
• One task at a time per worker. Don't send an unrelated new task to a busy worker. Mid-task steering (scope refinement, corrections, urgent interventions) is fine.
• Don't repeat corrections. Before sending a correction to a busy worker, check if you already sent one in the current turn. If yes, wait for the turn to end and evaluate whether the worker incorporated it.
• For urgent mid-turn redirections: interrupt the worker first (takode interrupt), wait for the interruption herd event, check its conversation to understand where it stopped, then send the corrected instructions as a fresh message.