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

# Agents

> Agent lifecycle commands — spawn, kill, stop, resume, ls, history, read, answer. For register, see Directory.

# Agent Commands

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

<Note>
  To **register** an agent in the directory before spawning, see [`genie agent register`](/genie/cli/directory#genie-agent-register).
</Note>

## Agent Lifecycle at a Glance

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

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

    ```bash Read & Interact theme={"dark"}
    $ 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).
    ```

    ```bash Stop & Cleanup theme={"dark"}
    $ 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).
    ```
  </CodeGroup>
</Frame>

## `genie spawn`

Spawn a new agent in a tmux pane.

```bash theme={"dark"}
genie spawn <name> [options]
```

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

```bash theme={"dark"}
genie resume <name>
genie resume --all
```

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

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

```bash Terminal theme={"dark"}
$ genie kill engineer
Killed agent "engineer" (pane %42).
```

## `genie stop`

Gracefully stop an agent (preserves state for resume).

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

```bash Terminal theme={"dark"}
$ genie stop engineer
Stopped agent "engineer". Use 'genie resume engineer' to continue.
```

## `genie ls`

List registered agents with runtime status.

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

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

```bash theme={"dark"}
genie history <agent> [options]
```

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

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

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

<ParamField path="name" type="string" required>
  Agent name (or any target the resolver accepts — pane id, session label, etc.).
</ParamField>

<ParamField path="choice" type="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.
</ParamField>

<CodeGroup>
  ```bash Pick a menu option theme={"dark"}
  $ genie answer engineer 2
  Selected option 2 for engineer (pane %42)
  ```

  ```bash Type free-form text theme={"dark"}
  $ genie answer engineer 'text:focus on edge cases in token refresh'
  Sent feedback: "focus on edge cases in token refresh"
  ```

  ```bash No prompt pending theme={"dark"}
  $ genie answer engineer 1
  No question pending (state: working)
  ```
</CodeGroup>

<Note>
  `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/cli/messaging#genie-send).
</Note>

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

```bash theme={"dark"}
genie approval <subcommand> [options]
```

Subcommands: [`request`](#genie-approval-request), [`resolve`](#genie-approval-resolve), [`list`](#genie-approval-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.

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

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

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

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

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

```bash Terminal theme={"dark"}
$ genie approval list
  ID                                     AGENT                TOOL            TIMEOUT
  ─────────────────────────────────────────────────────────────────────────────────────
  7b1f3c20-8d4e-4c8a-9bf1-2a18c4ad7e9e   engineer             Bash            14:32:08

  1 pending approval
```

<Note>
  Workspace defaults for approvals (`permissions.timeout`, `permissions.defaultAction`) are configured in the workspace config — see [Configuration](/genie/config/files).
</Note>