takode-orchestration

name	takode-orchestration
description	Cross-session orchestration for Takode. Use when you need to interact with other sessions: listing active sessions, peeking at session activity, reading messages, sending instructions to workers, or spawning new sessions. Triggers: 'check on workers', 'send to session', 'orchestrate', 'coordinate agents', 'list sessions', 'peek at session', 'what are my sessions doing', 'check session status'.

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 phase-based lifecycle, including Journey revision and purpose-specific review phases	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.
• Leaders do not become the quest owner for implementation work. The worker doing the job claims and completes the quest; the leader only dispatches, reviews, and coordinates later phase boundaries.
• Use /quest-design before quest creation/refinement. Before creating a quest or refining an idea quest into worker-ready scope, invoke /quest-design and wait for user confirmation or correction. When the user clearly wants a quest created and dispatched, combine quest-design with /leader-dispatch: write a concise approval packet with Proposed Quest, Goal / Acceptance, Journey, Scheduling, and only optional sections that the user needs to approve, correct, or choose. The visible chat proposal should read like a TLDR for approval, not a pasted worker-facing quest body or form; keep detailed scope, evidence, acceptance criteria, non-goals, fallback mechanics, constraints, and related context in the quest record for workers. Quest-design-only variants should omit dispatch sections; dispatch-only variants should reference the existing quest instead of duplicating its accepted scope. Routine feedback, claims, completion, verification checks, board updates, and already-approved lifecycle transitions do not need another round.
• Before dispatching any quest, ALWAYS invoke /leader-dispatch. It owns worker selection, the initial Journey proposal, durable board recording, and the alignment-only dispatch template. The user-facing pre-dispatch approval there must cover both the initial Journey phases and the scheduling/orchestration plan, including the simple immediate-dispatch case such as "spawn fresh and dispatch immediately if approved." If clarification was needed first, the next response after the user clarifies should normally include both the drafted quest and drafted Journey/scheduling plan instead of another restated-understanding-only round. Get approval for that combined proposal before spawning a worker, then write the approved Journey to the board before or with dispatch. Use clean bullets where they improve scanning, keep Goal / Acceptance as the source of truth for scope and acceptance, and omit optional sections when they add no new decision value. Preserve judgment, but expand only for ambiguity, user-visible tradeoffs, unusual phase reasons, or choices the user must confirm. Do not mirror the full quest body, extra context, file paths, or investigation instructions into chat or the dispatch message -- add worker-facing information into the quest itself before dispatching.
• Persist true follow-up relationships. When creating or refining a quest that is a true follow-up, bug fix, successor, redesign, or user-approved next quest from prior findings, include Relationship: follow-up of [q-N](quest:q-N) in the approval surface and persist it with quest create ... --follow-up-of q-N or quest edit q-M --follow-up-of q-N. Leave incidental mentions to auto-detected backlinks.
• 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. New human feedback becomes the source of truth for that quest: reset the board to the earliest valid phase for the fresh cycle and do not let stale in-flight review/port completions from the older scope keep advancing it. See quest-journey.md.
• Same-thread feedback usually belongs, but verify exceptions. Treat the current quest thread as strong context, not absolute proof of scope. If a user message in a quest thread appears to describe a separate feature, cross-cutting redesign, or unrelated issue, propose a new quest/Journey and attach the relevant discussion there instead of mutating the current quest until the user confirms. If that separate quest is a true successor to the current quest, propose it as an explicit follow-up and persist the relationship after approval.
• Don't echo board state as prose. takode board commands display the board in the terminal with a special UI, and the user already sees the live board state in the Takode Chat UI. Never repeat current board rows as markdown tables or summaries -- just run the command and move on unless the user explicitly asks for a text summary.
• Use quest threads as shared state. Main is the staging area for unthreaded/global work. Quest-backed threads carry quest-specific activity, and All Threads/global inspection preserves the append-only audit stream.
• Remind at quest setup points. After successful quest creation, refinement, or dispatch, include a non-blocking reminder to attach clearly quest-specific prior Main discussion to [q-N](quest:q-N) with takode thread attach.
• Use explicit phase plans for every quest. The recommended tracked-change Quest Journey is alignment -> implement -> code-review -> port -> memory, represented on the board as PLANNING -> IMPLEMENTING -> CODE_REVIEWING -> PORTING -> MEMORY, but user overrides win and standard phases are not mandatory. Omit notes for standard phases unless the user or quest adds unusual phase-specific work. Make every extra phase earn its keep: ask what it contributes over merging the work into a later phase. implement includes the normal investigation, root-cause analysis, code/design reading, and test planning needed to complete approved fixes, docs changes, config changes, prompt changes, and artifact changes. Do not insert routine explore -> implement just so a worker can look around, and never plan adjacent explore -> implement. Choose richer built-in phases such as explore, user-checkpoint, mental-simulation, execute, outcome-review, or compatibility bookkeeping when the quest needs them, and explain each non-standard phase concisely: why it is needed and what evidence, user decision, scenario, outcome, or durable state it covers. Use explore -> user-checkpoint -> implement when Explore findings may need user steering before implementation. User Checkpoints are mandatory by default; mark one optional only with an approved phase note that says it may be skipped and gives the concrete skip condition; after Explore, skip it only when that condition has been evaluated as satisfied and the skip reason is recorded. Repeated phases are allowed, and progress is tracked by phase occurrence. Zero-tracked-change work is not a separate board workflow: assemble a Journey that omits port when nothing will be synced, but still ends in memory. Legacy no-code board flags and shortcut commands are removed, and the older phase ID planning remains only as a compatibility alias for alignment. While a quest is on the board, its current planned Journey is board-owned draft-or-active state rather than quest-creation metadata. After approval, use takode board set --worker ... --phases ... or takode board promote to make the approved Journey durable before or with dispatch.
• Final Memory is mandatory. Every completed non-cancelled quest must have final Memory closure, final User review check settlement, a final debrief, a debrief TLDR, and quest metadata reconciliation so the title, TLDR, and description still match the accepted delivered scope. A quest in MEMORY is downstream-unblocking because substantive work is accepted and synced when applicable, but completion is incomplete until Memory settles durable state, User review checks, metadata reconciliation, and the memory statement.
• Quest completion summaries are outcome notes. When telling the user a quest is complete, lead with what changed or was decided, why it matters, and any real next action or residual risk. Do not lead with Journey bookkeeping. Routine internals such as raw commit hashes, empty User review checks, final debrief metadata status, no-op memory statements, command lists, or routine verification belong in structured metadata, phase notes, or debrief bodies unless directly useful to the user. If quiz metadata exists or was updated, write a complementary useful outcome summary first, then render {[(Quest Quiz: q-N)]} on its own physical line where the quiz should appear.
• Route leader messages explicitly. Every leader text response starts with a first-line thread marker: [thread:main] for general conversation or [thread:q-N] for a quest thread. The marker is stripped from rendering and used as thread metadata. Shell/terminal commands that belong to a thread should start with # thread:main or # thread:q-N as their first non-empty line.
• Do not use takode user-message as the new publishing path. It remains deprecated compatibility only. Use ordinary leader responses with mandatory thread markers, plus takode notify when notification state or suggested answers are needed.
• Never use AskUserQuestion or EnterPlanMode. These block your turn and prevent herd event processing. Ask clarifying questions in a normal leader response with the right [thread:...] marker, then call takode notify needs-input so the user never misses it. For obvious short choices, add one to three --suggest <answer> flags; for multiple independent questions, use --question <prompt> with each question's --suggest <answer> flags immediately after it.
• Use takode notify at these moments: needs-input every time you ask the user a question or need a decision before work can continue; first send the detailed question text as a marked leader response, then call takode notify needs-input with a short summary. The visible thread text is the decision surface and must contain the complete decision context needed to answer; notification summaries, notification UI options, and --suggest choices are only attention/reply affordances. Any user wait must use takode notify needs-input; never represent it only with Thread Waiting or takode notify waiting. New blocking prompt -> new notification: existing unresolved prompts do not cover a separate approval or decision. Link the affected active board row with --wait-for-input when applicable. Scoped-wait rule: a pending needs-input blocks only its owning thread, quest, or board row; keep that affected scope paused, continue unrelated quests and herd events, and make it broader only when the visible prompt explicitly concerns global orchestration, worker-slot scheduling, shared resource safety, or another cross-quest dependency. If the user chooses to park one prompt and work elsewhere, comply unless that other work depends on the unresolved decision or the broader-blocker exception applies. Use --suggest only for concise obvious options, typically binary choices like yes/no; use --question <prompt> when one notification needs multiple independent answers. Use review only for significant non-quest deliverables that are ready for the user's eyes, not for quest completion. Use waiting only when a marked leader thread, quest, or board row is intentionally parked on non-user work such as a herd event, timer, resource lease, worker, reviewer, or queued dependency; it is transient status, not user attention, so it does not create notification IDs, chip counts, or resolver work.
• Prefer plain-text inspection by default. When using takode info, takode peek, takode scan, or quest show to read for judgment, scanability, or general situational awareness, use the normal plain-text output first. It is usually more token-efficient and easier to reason about than --json.
• Use --json only when exact machine fields matter. Reach for JSON when you need precise structured data such as feedback addressed flags, commitShas, version-local quest metadata from quest history, exact IDs, or machine-oriented filtering/branching. Compact JSON omits bulky fields by default; use --details, --include <field>, or a dedicated detail command only when those fields are truly needed.

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 alignment read-in 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 (⊘)	Worker was interrupted by a user, leader, or system	Check whether it is terminal; system or recovery pending cases may still recover
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

• Respect scoped waits during herd events. Keep the affected thread, quest, or board row waiting even if herd events arrive, but continue unrelated orchestration. Only safety/global/worker-slot/shared-resource/cross-quest prompts broaden the wait; a user-parked prompt should not block unrelated work.
• System-interrupted worker events can be provisional. If a turn_end (⊘) event says recovery pending, or the worker still appears connected/generating after a stuck-watchdog interruption, inspect takode info/takode peek/takode scan and consider a simple continuation or short timer/recheck before writing fallback documentation yourself. Do not ignore real interruptions; take over when recovery failed, the worker is idle with no progress, or the user needs an immediate fallback.
• 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 phase events:

• takode notify needs-input "need decision on auth approach for q-42" --suggest yes --suggest no: every time you ask the user a question or need a decision before work can continue. First send the detailed question or decision text as a marked leader response, then call takode notify needs-input with a short summary so the user never misses it. The marked response must be self-contained enough to answer; suggested answers are optional shortcuts for short, obvious choices and never replace the in-thread decision context. Scope the wait to the affected thread, quest, or board row unless the question says it is global/safety/resource/cross-quest. For multiple independent questions, use takode notify needs-input "need decisions" --question "Which worker?" --suggest reuse --suggest spawn --question "Run browser validation?" --suggest yes --suggest no.
• {[(Thread Waiting: q-42 | waiting on reviewer pass)]}: put this strict standalone marker line in a leader assistant response when a marked leader thread is parked on a herd event, timer, lease, worker, reviewer, or queued dependency. Use it only for non-user waits; user waits require takode notify needs-input. Use {[(Thread Ready: q-42 | ready for review)]} when the thread is complete or ready. Put the marker on its own physical line as plain text, not in a code block, quote, bullet, or surrounding prose. This marker only updates thread status; it never routes the enclosing message or attached UI. Use [thread:main] / [thread:q-N] for message routing. Do not use inline markers for user questions.
• Do not call takode notify review for quest completion: when a work board item is completed, Takode already fires the review notification automatically. Sending another one creates duplicate quest-completion notifications.

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] [--details | --include <fields>]

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

takode info 1
takode info 1 --json
takode info 1 --json --include injectedSystemPrompt

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.

Prefer plain-text for normal inspection. Use compact --json only when you need exact structured fields for a programmatic decision. Use --details or --include <field> for opt-in bulky fields such as injectedSystemPrompt, task history, tools, MCP servers, or keywords.

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>. Prefer the plain-text scan output for this triage workflow; it is optimized for human reading. Use --json only if you truly need to branch on structured turn fields.

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

Default to the plain-text forms above when you are reading for judgment. Switch to --json only when you need exact machine fields.

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 thread attach <quest-id> --message <index> | --range <start-end>

Associate existing Main-thread history with a quest thread without moving or duplicating persisted messages. Use this when a quest thread is created after useful context already appeared in Main.

takode thread attach q-941 --range 120-135
takode thread attach q-941 --message 140

takode user-message --text-file <path|-> [--json] (deprecated)

Deprecated compatibility publisher for older leader sessions. New leader workflow uses ordinary marked responses with [thread:main] or [thread:q-N]; do not use takode user-message as the core thread publishing path.

takode notify <category> <summary> [--suggest <answer>]...

takode notify needs-input <summary> --question <prompt> [--suggest <answer>]... [--question <prompt> ...]

Alert the user when they need to take action or record a visible non-attention waiting status. Available to all sessions (not orchestrator-only). For leader sessions, send the detailed question or decision text as a normal marked leader response first, then use takode notify needs-input for attention state and optional suggested answers. User waits must use needs-input; waiting and Thread Waiting are only for non-user waits such as workers, reviewers, timers, leases, queued dependencies, or herd events. Pending leader decisions are owner-scoped by default; continue unrelated orchestration unless the prompt explicitly creates a global or cross-quest blocker. The summary is required and should describe the action or status.

Categories: needs-input, waiting, review

Suggested answers are supported only for needs-input. Use one to three short choices when the answer set is obvious; do not use them as a substitute for detailed question text in chat. For multi-question prompts, each --suggest applies to the most recent --question; do not mix top-level --suggest with --question. For leader thread waiting/ready status, prefer strict standalone inline markers such as {[(Thread Waiting: q-42 | waiting on reviewer pass)]} and {[(Thread Ready: main | answered the user)]}; these are stripped from displayed prose and rendered as status chips. These status markers never route the enclosing message or attached UI; only [thread:main] / [thread:q-N] message prefixes and # thread:... shell comments control routing. Never use these status markers as the only representation of a user wait.

takode notify needs-input "need decision on auth approach for q-42" --suggest yes --suggest no
takode notify needs-input "need dispatch decisions" --question "Reuse #12?" --suggest yes --suggest no --question "Run browser validation?" --suggest yes --suggest no
{[(Thread Waiting: q-42 | waiting on reviewer pass)]}
{[(Thread Ready: main | answered the user's question)]}
takode notify review "landing page copy draft is ready for review"

takode phases [--json]

List the read-only Quest Journey phase catalog. Available to all sessions. Use this when you need phase descriptions, source metadata, aliases, board states, assignee roles, or the exact ~/.companion/quest-journey-phases/<phase-id>/assignee.md path to include in a phase dispatch.

takode phases
takode phases --json

takode pending <session>

Show leader-answerable prompts for a session: AskUserQuestion, ExitPlanMode, and active takode notify needs-input questions.

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 text payloads directly inside double quotes if they may contain backticks, $(...), quotes, braces, copied CLI output, or other shell-sensitive content. Your shell can execute or corrupt that text locally before the target command receives it. Use Takode's non-inline input paths instead: takode send --stdin for sent messages, and takode spawn --message-file <path> or --message-file - for spawn dispatches.

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

For quest comments or summaries, prefer the quest CLI's safer rich-text path instead of inline shell quoting:

cat >/tmp/quest-feedback.txt <<'EOF'
Port summary: commit abc123 ...
Treat `foo $(bar)` as literal text, not shell.
EOF
quest feedback q-123 --text-file /tmp/quest-feedback.txt

printf '%s\n' 'Port summary: commit abc123 ...' 'Treat `foo $(bar)` as literal text, not shell.' | \
  quest feedback q-123 --text-file -

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 "..."] [--message-file <path>|-] [--cwd DIR] [--no-worktree] [--fixed-name "..."] [--reviewer <session>] [--replace-worktree-worker <session>] [--json] [--details | --include <fields>]

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 --message-file /tmp/dispatch.txt
takode spawn --replace-worktree-worker 5 --message-file /tmp/dispatch.txt
takode spawn --reviewer 5 --no-worktree --fixed-name "Skeptic review of #5" --message-file /tmp/reviewer-dispatch.txt

Use --message only for short inline text. For multiline or shell-like dispatch bodies, prefer --message-file <path> or --message-file -.

Use --replace-worktree-worker <session> when reclaiming an owned completed worktree worker for a new worker in the same repo/base branch. Replacement mode archives the old worker, refuses dirty or committed-ahead worktrees, resets the recycled worktree to the base branch, and spawns the replacement in that path. It is not compatible with --count > 1, --reviewer, or --no-worktree.

Routine dispatch should use compact plain-text output, not spawn --json. If structured spawn output is needed for a script, compact JSON is the default and bulky session fields require --details or --include <field>.

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> [--message <msg-id> | --target <id>] <response>

Answer a worker's pending question, needs-input clarification prompt, or plan approval request.

takode answer 2 --message 41 1                          # pick option 1 for msg [41]
takode answer 2 --message 41 "custom answer"           # free text reply to msg [41]
takode answer 2 --message 52 approve                   # approve the plan shown in msg [52]
takode answer 2 --target req_abc reject "add error handling" # target an exact pending id

Use this when a worker or reviewer asked a clarification question through takode notify needs-input and is waiting on you. If you can resolve the question from existing context, answer it directly. If the question reveals genuine ambiguity you cannot resolve, ask the user in a marked leader response, then call takode notify needs-input with a short summary, optionally using one to three short --suggest <answer> choices for obvious answers, and do not advance that quest until the ambiguity is resolved.

takode board [show|detail|set|advance|rm]

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

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

For queued rows, --wait-for accepts one comma-separated value containing multiple blockers, such as --wait-for q-1143,q-1139 or --wait-for q-1143,#12,free-worker. Use that directly when multiple quest, session, or capacity blockers apply.

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.

If a quest is still active on the board and its worker or reviewer is idle or disconnected, treat that as a potential stall signal rather than an automatic wait state. Check the quest phase and send the next legal instruction if progress has stalled; takode send will auto-relaunch disconnected sessions. Idle or disconnected sessions with active timers may still be healthy, so use timer visibility in takode outputs as part of that judgment rather than assuming every idle/disconnected row is stalled.

Archiving Sessions

Maintain at most 5 worker slots in your herd. Reviewers can be herded for routing, but they do not use worker slots. Never archive proactively. Only reclaim capacity when you are at the 5-worker-slot limit AND need to spawn a new worker. Use the worker-slot summary from takode list / takode spawn directly -- do not infer slot usage from the raw total. Archiving reviewers does not free worker-slot capacity. Idle and disconnected worker sessions retain valuable context -- keep them until you actually need the slot. Prefer takode spawn --replace-worktree-worker <session> ... over archive-then-spawn when replacing an owned completed worktree worker for the same repo/base branch. Otherwise choose the worker least likely to be reused -- typically the one whose work is most complete, least related to upcoming tasks, or oldest. Archived sessions' conversation history remains readable via takode peek, takode read, and the Takode UI, but that history does not preserve uncommitted work from a deleted worktree.

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 only for programmatic decisions. Parse JSON output when you need to branch on exact event data, IDs, or other structured fields. Do not use spawn/replacement --json for routine dispatch; use the compact text result first and request details explicitly only when needed.
• 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.
• Human-input pauses are quest-scoped board decisions. If one quest is waiting on user clarification or confirmation, keep that pause explicit in the board handling for that quest and continue unrelated board work. Do not treat /confirm or another confirmation round as an implicit herd-wide pause; if the user parks that prompt, work elsewhere when there is no safety/global/cross-quest dependency.
• Reconcile active rows after restarts/context reloads. After a server restart, context compaction, or any manual state refresh, immediately compare takode board show and takode list. If an active board row has an idle or disconnected worker/reviewer, decide whether the quest is genuinely waiting or whether you need to send the next-phase instruction now.
• 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.