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]

Option	Description
`--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-window`	Spawn 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-mode`	Start 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-resume`	Disable 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:

Option	Description
`--stream`	Stream SDK messages to stdout in real time (claude-sdk provider)
`--stream-format <format>`	Streaming output format: `text` (default), `json`, `ndjson`
`--sdk-stream`	SDK: 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]

Option	Description
`--all`	Resume 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)

State	Description
running	Agent is active in a tmux pane
suspended	Stopped gracefully, session preserved for resume
terminated	Force-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.

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.

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.

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.

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.

Tier	Source	Notes
1	`--team` flag	Explicit user intent — only tier that flips `teamWasExplicit`.
2	`agent_templates.team`	Template-pinned team in PG.
3	`$GENIE_TEAM`	Shell / automation context.
4	`discoverTeamName()`	JSONL `leadSessionId` match, then tmux session name.
5	`findTeamsContainingAgent()`	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.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Spawn & Lifecycle

Agent Lifecycle Commands

`genie spawn`

SDK streaming + resume flags

Examples

`genie stop`

`genie resume`

`genie kill`

Lifecycle Flow

Auto-resume

Team resolution

​Agent Lifecycle Commands

​genie spawn

​SDK streaming + resume flags

​Examples

​genie stop

​genie resume

​genie kill

​Lifecycle Flow

​Auto-resume

​Team resolution

Agent Lifecycle Commands

`genie spawn`

SDK streaming + resume flags

Examples

`genie stop`

`genie resume`

`genie kill`

Lifecycle Flow

Auto-resume

Team resolution