Skip to main content

​
Agent Commands

Top-level commands for managing agent lifecycle — spawning, stopping, listing, and inspecting agents.

​
Agent Lifecycle at a Glance

$ genie spawn engineer
Spawning engineer...
  Provider: claude
  Model: sonnet
  Pane: %42
  Session: myapp

$ genie spawn reviewer --model opus
Spawning reviewer...
  Provider: claude
  Model: opus
  Pane: %43
  Session: myapp

​
genie spawn

Spawn a new agent in a tmux pane. 
genie spawn <name> [options]
Terminal
$ genie spawn engineer
Spawning engineer...
  Provider: claude
  Model: sonnet
  Pane: %42
  Session: myapp
Built-in agent roles: engineer, reviewer, fixer, tracer, qa, docs.

​
Options

FlagDescription
--model <model>Model override (sonnet, opus, codex)
--provider <provider>Provider (claude, codex)
--layout <layout>Layout mode: mosaic (default) or vertical
--color <color>Teammate pane border color
--plan-modeStart teammate in plan mode
--permission-mode <mode>Permission mode (e.g., acceptEdits)
--extra-args <args...>Extra CLI args forwarded to the provider
--cwd <path>Working directory for the agent
--session <session>Tmux session name to spawn into
--no-auto-resumeDisable auto-resume on pane death

​
genie resume

Resume a stopped agent or all stopped agents. 
genie resume <name>
genie resume --all
Terminal
$ genie resume engineer
Resumed engineer in pane %42.

$ genie resume --all
Resumed 3 agents: engineer, reviewer, fixer

​
genie kill

Terminate an agent and its tmux pane. 
genie kill <name>
Terminal
$ genie kill engineer
Killed agent "engineer" (pane %42).

​
genie stop

Gracefully stop an agent (preserves state for resume). 
genie stop <name>
Terminal
$ genie stop engineer
Stopped agent "engineer". Use 'genie resume engineer' to continue.

​
genie ls

List all active agents. 
genie ls [--json]
Terminal
$ genie ls
AGENT       STATUS    PANE   PROVIDER   MODEL
engineer    running   %42    claude     sonnet
reviewer    running   %43    claude     sonnet
fixer       stopped   %44    claude     sonnet

​
genie history

View a compressed summary of an agent’s session by parsing provider logs. 
genie history <agent> [options]
Terminal
$ genie history engineer
Session Summary for engineer (compressed):
  Duration: 12m
  Files modified: src/auth/middleware.ts, src/auth/config.ts
  Key actions:
    1. Read WISH.md for Group 1 context
    2. Implemented OAuth middleware
    3. Added token validation
    4. Ran tests — all passing
  Status: Complete

​
Options

FlagDescription
--fullFull conversation (not compressed)
--since <n>Last N user/assistant exchanges
--last <n>Last N transcript entries
--type <role>Filter by role (user, assistant, tool_call)
--after <timestamp>Only entries after ISO timestamp
--rawOutput raw JSONL entries (no formatting)
--log-file <path>Direct path to log file
--jsonJSON output
--ndjsonNewline-delimited JSON (pipeable to jq)

​
genie read

Read an agent’s current transcript or output. 
genie read <agent> [options]

​
Options

FlagDescription
-n, --lines <number>Number of lines to read
--from <line>Start from line number
--to <line>End at line number
--range <range>Line range (e.g., 10-50)
--search <text>Search for text in transcript
--grep <pattern>Grep with regex pattern
-f, --followFollow mode — stream new output
--allShow full transcript (not truncated)
-r, --reverseShow newest entries first
--jsonOutput as JSON

​
genie answer

Send a response to an agent that is waiting for input. 
genie answer <agent> '<response>'