Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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 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 (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-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
--role <role>Role override (engineer, reviewer, qa, fix, etc.)
--new-windowSpawn 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-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 registered agents with runtime status. 
genie ls [options]
OptionDescription
--jsonOutput 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

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

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>
​
name
string
required
Agent name (or any target the resolver accepts — pane id, session label, etc.).
​
choice
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 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>]
FlagDescription
--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).
--waitBlock 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>]
FlagDescription
--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]
FlagDescription
--agent <name>Only show approvals requested by this agent.
--jsonEmit 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.