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 Lifecycle Commands

The genie spawn, genie stop, genie resume, and genie kill commands manage agent processes. Agents run in tmux panes and can be stopped, resumed, and killed independently.

​
genie spawn

Spawn a new agent by name. Resolves the agent from the directory registry or built-in roles. 
genie spawn <name> [options]
OptionDescription
--provider <provider>Provider: claude or codex (default: claude)
--team <team>Team name (default: (genie))
--role <role>Role override (engineer, reviewer, qa, fix, etc.)
--model <model>Model override (e.g., sonnet, opus)
--skill <skill>Skill to load on start
--prompt <text>Initial prompt to send as the first user message
--new-windowSpawn in a new tmux window instead of a pane
--window <name>Target a specific tmux window by name
--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 provider
--cwd <path>Working directory (overrides directory entry)
--session <session>tmux session name to spawn into
--no-auto-resumeDisable auto-resume on pane death

​
SDK streaming + resume flags

When you spawn through the claude-sdk provider, these extra flags control turn budget, streaming, and session resumption:
OptionDescription
--streamStream SDK messages to stdout in real time (claude-sdk provider)
--stream-format <format>Streaming output format: text (default), json, ndjson
--sdk-streamSDK: enable streaming output (shortcut for --stream)
--sdk-max-turns <n>SDK: cap the number of conversation turns the agent may take
--sdk-max-budget <usd>SDK: cap the USD spend for this session
--sdk-effort <level>SDK: reasoning effort level — low, medium, high, max
--sdk-resume <session-id>SDK: resume a previous session by ID
SDK flags only apply when --provider resolves to a claude-sdk-backed executor. For non-SDK providers (e.g., classic claude or codex), they are silently ignored.

​
Examples

# Spawn a reviewer agent
genie spawn reviewer

# Spawn with model override
genie spawn engineer --model opus

# Spawn with a skill loaded
genie spawn engineer --skill work

# Spawn into a specific tmux session
genie spawn qa --session docs

# Spawn in plan mode for review before execution
genie spawn engineer --plan-mode

# Spawn with custom working directory
genie spawn engineer --cwd /home/user/my-project

# Spawn with accept-edits permission
genie spawn engineer --permission-mode acceptEdits

# Seed the agent with an initial prompt
genie spawn engineer --prompt "start the dispatch refactor, reference wish fix-dispatch-initial-prompt"

# SDK streaming with a turn cap and USD budget
genie spawn engineer --provider claude-sdk --stream --sdk-max-turns 20 --sdk-max-budget 5.00

# Resume a previous SDK session
genie spawn engineer --provider claude-sdk --sdk-resume conv-3d324b09

​
genie stop

Stop an agent gracefully. Preserves the session so the agent can be resumed later. 
genie stop <name>

genie stop reviewer
The agent’s Claude session is preserved — use genie resume to pick up where it left off.

​
genie resume

Resume a suspended or failed agent with its preserved Claude session. 
genie resume [name] [options]
OptionDescription
--allResume all eligible agents
# Resume a specific agent
genie resume reviewer

# Resume all stopped agents
genie resume --all

​
genie kill

Force-kill an agent by name. Unlike stop, this does not preserve the session. 
genie kill <name>

genie kill reviewer
kill terminates the agent immediately without preserving its session. Use stop if you want to resume later.

​
Lifecycle Flow

spawn → running → stop → suspended → resume → running
                    ↘ kill → terminated (no resume)
StateDescription
runningAgent is active in a tmux pane
suspendedStopped gracefully, session preserved for resume
terminatedForce-killed, session lost

​
Auto-resume

When an agent’s tmux pane dies unexpectedly (crash, OOM, terminal close), the scheduler daemon restores it by respawning against the saved Claude session ID. This keeps the “one name = one true Claude session UUID” invariant across crashes and is why --no-auto-resume (see the spawn flag table) exists as an escape hatch.
1

Detect dead pane

The daemon polls heartbeats. Two consecutive dead cycles mark the worker as resumable. On daemon startup, recoverOnStartup() sweeps any panes that died while the daemon was down.
2

Match session

An agent is eligible when it has a claudeSessionId (Claude provider only), its state is not done, and autoResume is not false. Spawn-time resume additionally requires a matching role and team.
3

Respawn with budget

Resumes are capped at maxResumeAttempts = 3 with a 60-second cooldown. Exceeding the budget marks the agent permanently failed; resumeAttempts is visible in genie ls.
4

Opt out

Pass --no-auto-resume at spawn time to set autoResume=false. The daemon then skips the agent in reconcileOrphans() — manual genie resume <name> still works and does not consume the budget.
Full behavior spec: automagik-dev/genie/docs/SPAWN-AUTO-RESUME.md.

​
Team resolution

genie spawn resolves the effective team via a five-tier precedence chain before it decides whether to create, resume, or fork a parallel. When --team (see the spawn flag table) is set, the team’s configured tmuxSessionName is used automatically — you rarely need --session.
TierSourceNotes
1--team flagExplicit user intent — only tier that flips teamWasExplicit.
2agent_templates.teamTemplate-pinned team in PG.
3$GENIE_TEAMShell / automation context.
4discoverTeamName()JSONL leadSessionId match, then tmux session name.
5findTeamsContainingAgent()On-disk scan of ~/.claude/teams/*/config.json — errors on ambiguity.
If every tier yields nothing and the agent is globally registered, an auto team-of-one is materialized downstream by ensureNativeTeam, named after the agent.
Passing --session <team-name> to genie spawn overrides the team’s configured tmuxSessionName and lands the worker in a separate tmux session, breaking the topology. When --team is set, let Genie resolve the session — only pass --session for rare manual overrides.
Full resolution spec: automagik-dev/genie/docs/SPAWN-TEAM-RESOLUTION.md.