Agent Commands

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

To register an agent in the directory before spawning, see genie agent register.

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 ls
AGENT       STATUS    PANE   PROVIDER   MODEL
engineer    running   %42    claude     sonnet
reviewer    running   %43    claude     opus
fixer       stopped   %44    claude     sonnet

$ 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

$ genie read engineer
[engineer %42] Last 5 messages:

  assistant: Reading WISH.md for Group 1 deliverables...
  tool:      Read(.genie/wishes/add-oauth/WISH.md)
  assistant: Implementing OAuth middleware in src/auth/
  tool:      Write(src/auth/middleware.ts)
  assistant: All tests passing. Group 1 complete.

$ genie answer engineer 'focus on edge cases in token refresh'
Message sent to engineer (pane %42).

$ genie stop engineer
Stopped agent "engineer". Use 'genie resume engineer' to continue.

$ genie resume engineer
Resumed engineer in pane %42.

$ genie kill reviewer
Killed agent "reviewer" (pane %43).

`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

Flag	Description
`--model <model>`	Model override (e.g., `sonnet`, `opus`)
`--provider <provider>`	Provider: `claude` or `codex` (default: `claude`)
`--layout <layout>`	Layout mode: `mosaic` (default) or `vertical`
`--color <color>`	Teammate pane border color
`--plan-mode`	Start 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
`--role <role>`	Role override (engineer, reviewer, qa, fix, etc.)
`--new-window`	Spawn in a new tmux window instead of a pane
`--window <name>`	Target a specific tmux window by name
`--team <team>`	Team name (default: `(genie)`)
`--skill <skill>`	Skill to load on start
`--session <session>`	tmux session name to spawn into
`--no-auto-resume`	Disable 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 registered agents with runtime status.

genie ls [options]

Option	Description
`--json`	Output the agent list as JSON (suitable for piping to `jq`)
`--source <name>`	Filter by executor metadata source (e.g., `omni`) — useful when your workspace has agents registered from multiple origins

Terminal

$ genie ls
AGENT       STATUS    PANE   PROVIDER   MODEL
engineer    running   %42    claude     sonnet
reviewer    running   %43    claude     sonnet
fixer       stopped   %44    claude     sonnet

$ genie ls --source omni
# only agents registered through Omni's executor metadata

`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

Flag	Description
`--full`	Full 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
`--raw`	Output raw JSONL entries (no formatting)
`--log-file <path>`	Direct path to log file
`--json`	JSON output
`--ndjson`	Newline-delimited JSON (pipeable to jq)

`genie read`

Read an agent’s current transcript or output.

genie read <agent> [options]

Options

Flag	Description
`-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, --follow`	Follow mode — stream new output
`--all`	Show full transcript (not truncated)
`-r, --reverse`	Show newest entries first
`--json`	Output as JSON

`genie answer`

Answer a question for an agent that is currently blocked at a prompt — picks the menu option, types text into a free-form input, or sends raw keystrokes. Genie inspects the agent’s pane state first; if no question is pending it logs No question pending and exits without acting.

genie answer <name> <choice>

string

required

Agent name (or any target the resolver accepts — pane id, session label, etc.).

string

required

How to answer. One of:

Numeric (1–9) — navigates to that menu option and presses Enter.
text:<message> — selects the free-form text option, types <message>, and presses Enter.
Anything else — sent verbatim as keystrokes to the pane.

$ genie answer engineer 2
Selected option 2 for engineer (pane %42)

$ genie answer engineer 'text:focus on edge cases in token refresh'
Sent feedback: "focus on edge cases in token refresh"

$ genie answer engineer 1
No question pending (state: working)

genie answer only acts when the pane is in a question state. To send a regular instruction to a working agent, use genie send.

`genie approval`

Remote approval queue used by tmux-path agents that need a human (or another agent) to allow or deny a tool call before the provider proceeds. Approvals live in Postgres so any teammate with CLI access can resolve them.

genie approval <subcommand> [options]

Subcommands: request, resolve, list.

`genie approval request`

Create an approval request and (optionally) block until it is resolved. Used by agent runtimes when a tool needs out-of-band sign-off.

genie approval request --tool <name> --input <preview> --agent <name> [--wait] [--timeout <seconds>]

Flag	Description
`--tool <name>`	Tool name requiring approval (required).
`--input <preview>`	Preview text of the tool input shown to the approver (required).
`--agent <name>`	Agent requesting the approval (required).
`--wait`	Block until the approval is resolved; exits non-zero on `deny`.
`--timeout <seconds>`	Override the workspace `permissions.timeout` (default `300`). On timeout, the workspace `permissions.defaultAction` decides (default `deny`).

Terminal

$ genie approval request --tool Bash --input 'rm -rf node_modules' --agent engineer --wait
Approval created: 7b1f3c20-8d4e-4c8a-9bf1-2a18c4ad7e9e
Waiting for resolution (timeout: 300s, default: deny)...
Decision: allow

`genie approval resolve`

Allow or deny a pending approval by id. The actor label is the value of GENIE_AGENT_NAME if set, otherwise the --by value.

genie approval resolve <id> --decision allow|deny [--by <actor>]

Flag	Description
`--decision <decision>`	`allow` or `deny` (required).
`--by <actor>`	Display label for the decision maker. Defaults to `GENIE_AGENT_NAME` or `cli`.

Terminal

$ genie approval resolve 7b1f3c20-8d4e-4c8a-9bf1-2a18c4ad7e9e --decision allow --by felipe
Approval 7b1f3c20-8d4e-4c8a-9bf1-2a18c4ad7e9e resolved: allow by felipe

`genie approval list`

List pending approvals across the workspace, optionally filtered by agent.

genie approval list [--agent <name>] [--json]

Flag	Description
`--agent <name>`	Only show approvals requested by this agent.
`--json`	Emit the raw rows as JSON (suitable for piping to `jq`).

Terminal

$ genie approval list
  ID                                     AGENT                TOOL            TIMEOUT
  ─────────────────────────────────────────────────────────────────────────────────────
  7b1f3c20-8d4e-4c8a-9bf1-2a18c4ad7e9e   engineer             Bash            14:32:08

  1 pending approval

Workspace defaults for approvals (permissions.timeout, permissions.defaultAction) are configured in the workspace config — see Configuration.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Agents

Agent Commands

Agent Lifecycle at a Glance

`genie spawn`

Options

`genie resume`

`genie kill`

`genie stop`

`genie ls`

`genie history`

Options

`genie read`

Options

`genie answer`

`genie approval`

`genie approval request`

`genie approval resolve`

`genie approval list`

​Agent Commands

​Agent Lifecycle at a Glance

​genie spawn

​Options

​genie resume

​genie kill

​genie stop

​genie ls

​genie history

​Options

​genie read

​Options

​genie answer

​genie approval

​genie approval request

​genie approval resolve

​genie approval list

Agent Commands

Agent Lifecycle at a Glance

`genie spawn`

Options

`genie resume`

`genie kill`

`genie stop`

`genie ls`

`genie history`

Options

`genie read`

Options

`genie answer`

`genie approval`

`genie approval request`

`genie approval resolve`

`genie approval list`