CLI Reference
Every kumo command — sessions, tabs, panes, agents, and orchestration.
Commands
Sessions & tabs
| Command | Description |
|---|---|
kumo | Attach to the daemon (starts it if needed); restores the last session if present |
kumo attach | Force-attach to the running daemon |
kumo new [WORKSPACE] | Start a fresh session in the daemon (never attaches); uses the client's cwd when no workspace is given |
kumo [WORKSPACE] | Fresh-start alias for back-compat |
kumo session list | List sessions: tab names + ids, AI agent rows with their pane ids |
kumo session new [DIR] [--name NAME] | Create and focus a session in the daemon |
kumo session kill NAME | Close a session and its panes |
kumo session attach NAME | Focus the named session (a viewer attaches with kumo) |
kumo tab list [-s SESSION] | List the session's tabs with ids |
kumo tab new [WORKSPACE] [--name NAME] | Create a tab (window) in a session |
kumo tab focus TAB / kumo tab kill TAB / kumo tab rename TAB NAME | Manage tabs |
Worktrees
| Command | Description |
|---|---|
kumo worktree create BRANCH [-s SESSION] | Create a regular Git worktree from the session's repository and open it in a new session |
kumo worktree create --ai [NAME] [--branch BRANCH] [--from REF] [--jira ISSUE] [--note NOTE] [--agent KIND] [--model MODEL] [--effort LEVEL] [--prompt TEXT] [-s SESSION] | Create an isolated worktree for agent work; derive a branch from a name or Jira issue, start an agent with model preferences, and optionally submit its first task after readiness |
kumo worktree list [-s SESSION] | List the repository's main and linked worktrees |
kumo worktree current [PATH] [-s SESSION] | Show the checkpoint for the session's current worktree, or for PATH |
kumo worktree set [PATH] [--comment TEXT] [--status STATUS] [-s SESSION] | Set or update a checkpoint (todo, in-progress, in-review, or completed) |
kumo worktree open PATH [-s SESSION] | Open an existing worktree in a new session, or focus its existing session |
| `kumo worktree rm PATH [-f | --force] [-s SESSION]` |
The --ai form creates an ephemeral isolated checkout. --from accepts a
local branch, remote branch, commit, #1234, or a GitHub/GitLab pull or merge
request URL; Jira references are not supported yet. --agent KIND starts the
selected agent in the new pane, but does not submit a task automatically.
Wait for readiness and submit the task explicitly:
kumo worktree create --ai fix-login --agent claude --note "Investigate auth tests"
kumo agent status
kumo agent wait -p 42 --until idle --timeout 60s
kumo agent prompt -p 42 "Fix the failing auth tests" --wait idle --timeout 10m
kumo worktree set --status in-review --comment "Tests pass; ready for review"Automatic task submission after creation, including the fully chained create→start→ready→prompt flow, is planned for 0.7.1.
Panes
| Command | Description |
|---|---|
kumo pane split [-s SESSION] [--horizontal] [--ai] | Split the focused pane (AI split = agent pane) |
kumo pane close [-s SESSION] [-p PANE] / kumo pane focus -p PANE | Manage panes |
kumo pane send-keys [-s SESSION] [-p PANE] KEYS... | Type keys into a pane (tokens: Enter, Tab, Esc, Left, Up, PageDown, …) |
kumo pane list [-s SESSION] [-t TAB_ID] [S1:T2] | Every pane with its id + composite position (* = focused) |
kumo pane wait-output [PANE] PATTERN [--regex] [--timeout 30s] [-s SESSION] | Server-owned one-shot output waiter — returns when PATTERN appears in recent + visible buffer |
Agents
| Command | Description |
|---|---|
kumo agent spawn [-s SESSION] [PROGRAM] | Spawn an AI CLI in a new pane (default = configured ai-cmd) |
kumo agent status | One line per running AI CLI with its pane id + position (aliases: list, ls) |
kumo agent kill -p PANE [-s SESSION] | Kill the agent in a pane (closes it) |
kumo agent explain [PANE] [-s SESSION] | Why a pane reads the state it does: matched markers, evidence region, verdict-reason chain — evaluated live by the daemon |
kumo agent wait <PANE> --until blocked|done|idle|working [--timeout 30s] [-s SESSION] | Server-owned event-driven wait for an agent status (pinned to pane occupant) |
kumo agent prompt <PANE> <TEXT> [--wait [STATUS]] [--timeout 60s] [-s SESSION] | Bracketed-paste-aware submit; --wait atomically submits and waits in one RPC |
kumo agent read <PANE> [--source visible|recent|detection|traceback] [-s SESSION] | Read the pane's buffer directly from the daemon (including alt-screen) |
kumo agent start --kind <agent> --pane <PANE> [-- <args>] [-s SESSION] | Launch an agent in an existing shell pane; returns once detection shows ready |
kumo agent rename <PANE> <NAME> [-s SESSION] | Live alias for a pane so scripts can reference agents by name |
kumo agent broadcast "TEXT" [-s SESSION] [--filter STATUS] | Fan one prompt out to every AI pane (optionally filtered by status) |
kumo agent skill [--output PATH] | Print the bundled Kumo orchestration skill, or install it at PATH; does not require a daemon |
Add --json to any control command for machine-readable output. Successful
mutations use an { "ok": true } envelope; failures use
{ "ok": false, "error": { "code", "message" } }. Lists and reads retain
their typed fields (sessions, tabs, agents, worktrees, text, and so on).
PANE addressing — a stable numeric pane id, or a composite position
(1-based indexes, session may be a name):
s1:t2:p3 · kumo:t2:p1 · t2:p1 (session from -s). Composites are
resolved client-side against the live session list; the daemon always gets
the canonical id. Discover ids with kumo pane list and kumo agent status.
| kumo ls | Legacy alias of kumo session list |
| kumo kill | Stop the daemon (kills its panes) |
| kumo reload | Re-read the config and apply it live |
| kumo daemon [WORKSPACE] | Run the headless daemon in the foreground |
| kumo update | Update to the latest stable release |
| kumo update --nightly | Update to the latest nightly build |
| kumo update --check | Report availability (exit 0 = up to date, 1 = update available) |
| kumo --version | Print the version and channel (stable / nightly / dev) |
Orchestration quick refs
These are the ADE primitives — see Orchestration for the full guide.
# wait for an agent to become idle (server holds the socket, no polling)
kumo agent wait -p 42 --until idle --timeout 30s
# prompt and wait atomically (one RPC, no race)
kumo agent prompt -p 42 "fix the failing test" --wait idle --timeout 120s
# read what the agent actually sees (daemon owns the alt-screen buffer)
kumo agent read -p 42 --source visible
kumo agent read -p 42 --source recent # last ~16 KiB of output
kumo agent read -p 42 --source traceback # last prompt block (form / tail fallback)
# wait for any pane's output (dev server, test suite, build)
kumo pane wait-output -p 42 "Ready on" --timeout 30s
kumo pane wait-output -p 42 --regex "passed|failed" --timeout 60s
# fan a prompt to every idle agent in the session
kumo agent broadcast "rebase onto main" --filter idle -s myproj
# start an agent in an existing shell pane
kumo agent start --kind claude --pane 42 -- --model sonnet--timeout accepts ms / s / m suffixes (500ms, 30s, 2m) or bare milliseconds. Defaults: agent wait 30s, agent prompt --wait 120s, pane wait-output 30s.
Error codes are bad_regex, agent_blocked, agent_replaced (pane occupant changed, wait pinned to pane_os_pid), and timeout.
Examples
kumo new ~/proyecto # fresh session in ~/proyecto
kumo daemon ~/proyecto # headless daemon in the foreground
kumo agent status # which agents run, and in which pane
kumo agent explain 42 # why pane 42 reads the status it does
kumo agent explain s1:t2:p1 # same, by composite position
kumo pane list -s myproj # every pane id + s1:t2:p3 positionDuring development: cargo run -p kumo or make run.