> ## 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.

# Spawn & Lifecycle

> Spawn agents, stop, resume, and force-kill — the full agent process lifecycle

# Agent Lifecycle Commands

The `genie spawn`, `genie stop`, `genie resume`, and `genie kill` commands manage [agent](/genie/concepts/agents) 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.

```bash theme={"dark"}
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                             |

<Note>
  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.
</Note>

### Examples

```bash theme={"dark"}
# 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.

```bash theme={"dark"}
genie stop <name>
```

```bash theme={"dark"}
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.

```bash theme={"dark"}
genie resume [name] [options]
```

| Option  | Description                |
| ------- | -------------------------- |
| `--all` | Resume all eligible agents |

```bash theme={"dark"}
# 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.

```bash theme={"dark"}
genie kill <name>
```

```bash theme={"dark"}
genie kill reviewer
```

<Warning>
  `kill` terminates the agent immediately without preserving its session. Use `stop` if you want to resume later.
</Warning>

## Lifecycle Flow

```text theme={"dark"}
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](#genie-spawn)) exists as an escape hatch.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

Full behavior spec: [`automagik-dev/genie/docs/SPAWN-AUTO-RESUME.md`](https://github.com/automagik-dev/genie/blob/dev/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](#genie-spawn)) 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.

<Note>
  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.
</Note>

Full resolution spec: [`automagik-dev/genie/docs/SPAWN-TEAM-RESOLUTION.md`](https://github.com/automagik-dev/genie/blob/dev/docs/SPAWN-TEAM-RESOLUTION.md).