## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.entire.io/llms.txt)

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

---

Understanding when each subcommand is called helps you build a correct integration. Here’s the full sequence from the CLI’s perspective.

## Phase 1: Discovery (CLI startup)

Every time the CLI starts, it scans `$PATH` for binaries matching `entire-agent-<name>`.

1. **`info`** — Called once per discovered binary. The CLI reads your metadata, validates the protocol version, and registers the agent. If this fails, the agent is silently skipped.

## Phase 2: Enable (`entire enable`)

When a user enables your agent for a repository:

1. **`detect`** — Called to check whether your agent is available in the current environment.
2. **`install-hooks [--local-dev] [--force]`** — Called to install your hooks into the agent (e.g., writing hook config files). Only called if you declare the `hooks` capability.

## Phase 3: Agent session (hooks firing)

Once enabled, your agent’s hooks fire during normal usage and the CLI processes them. This phase requires the `hooks` capability — agents that don’t declare it won’t participate in the hook lifecycle. Every hook invocation follows this flow:

```
Hook fires → parse-hook → Event dispatched by type
```

1. **`parse-hook --hook <name>`** — Called on every hook invocation with the raw payload on stdin. Return a normalized [Event](https://docs.entire.io/agents/external-agent-plugins/data-model#event), or `null` if the hook has no lifecycle significance (the CLI will do nothing).

The CLI then routes the event by type:

### SessionStart (type 1)

Fired when the agent begins a new session.

1. **`get-session-id`** — Extract the session ID from the hook input (stdin).
2. **`get-session-dir --repo-path <path>`** — Return where sessions are stored.
3. **`resolve-session-file --session-dir <dir> --session-id <id>`** — Resolve the session file path.
4. **`read-session`** — Read existing session data (stdin: [HookInput](https://docs.entire.io/agents/external-agent-plugins/data-model#hookinput)).
5. **`write-session`** — Persist updated session data.
6. **`write-hook-response --message <msg>`** — _(optional, if `hook_response_writer` capability)_ Write a startup message in your agent’s native format.

### TurnStart (type 2)

Fired when the user submits a new prompt.

1. **`extract-modified-files --path <path> --offset <n>`** — _(if `transcript_analyzer` capability)_ Extract files changed since last checkpoint.
2. The CLI creates a git checkpoint of the current state.

### TurnEnd (type 3)

Fired when the agent finishes responding.

1. **`prepare-transcript --session-ref <path>`** — _(if `transcript_preparer` capability)_ Pre-process the transcript.
2. **`read-transcript --session-ref <path>`** — Read the raw transcript bytes.
3. **`chunk-transcript --max-size <n>`** — Split large transcripts into storable chunks.
4. **`get-transcript-position --path <path>`** — _(if `transcript_analyzer` capability)_ Get the current byte offset.
5. **`extract-modified-files --path <path> --offset <n>`** — _(if `transcript_analyzer` capability)_ Extract newly modified files.
6. **`calculate-tokens --offset <n>`** — _(if `token_calculator` capability)_ Calculate token usage.
7. The CLI stores a checkpoint in git history.

### Compaction (type 4)

Fired when the agent compresses its context window. Follows the same flow as **TurnEnd** (save + reset offset).

### SessionEnd (type 5)

Fired when the session terminates. The CLI creates a final checkpoint and cleans up session state.

### SubagentStart / SubagentEnd (types 6–7)

Fired when the agent spawns or completes a subagent. If you declare the `subagent_aware_extractor` capability, the CLI calls:

- **`extract-all-modified-files --offset <n> --subagents-dir <dir>`**
- **`calculate-total-tokens --offset <n> --subagents-dir <dir>`**

## Phase 4: User commands

Some CLI commands invoke your plugin outside the hook flow:

| Command | Subcommands called |
| --- | --- |
| `entire checkpoint rewind` | `read-transcript`, `reassemble-transcript`, `extract-modified-files` |
| `entire status` | `get-transcript-position` |
| `entire session resume` | `format-resume-command` |

## Phase 5: Disable (`entire disable --uninstall`)

1. **`uninstall-hooks`** — Called to remove your installed hooks. Only called if you declare the `hooks` capability.

## Error handling

- **Timeout:** Each subcommand has a 30-second default timeout.
- **Output limits:** Stdout and stderr are each capped at 10 MB. Be mindful of this when implementing `read-transcript` for large sessions.
- **No retries:** The CLI does not retry failed subcommand calls. A non-zero exit code with a message on stderr is treated as a failure.
- **Graceful degradation:** If `parse-hook` returns `null`, the CLI takes no action. If the repo has Entire disabled, hooks exit silently.