> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Required commands and optional capabilities for external agent plugins

Every plugin must implement these subcommands.

## Required commands

### `info`

Returns metadata and declares which optional capabilities your plugin supports.

```bash theme={null}
entire-agent-myagent info
```

```json theme={null}
{
  "protocol_version": 1,
  "name": "myagent",
  "type": "MyAgent",
  "description": "MyAgent - AI-powered code editor",
  "is_preview": true,
  "protected_dirs": [".myagent"],
  "hook_names": ["session-start", "session-end", "stop"],
  "capabilities": {
    "hooks": true,
    "transcript_analyzer": true,
    "transcript_preparer": false,
    "token_calculator": false,
    "text_generator": false,
    "hook_response_writer": false,
    "subagent_aware_extractor": false
  }
}
```

| Field              | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `protocol_version` | Must match the CLI's expected version (currently `1`)                       |
| `name`             | Registry name (must match the `<name>` in the binary name)                  |
| `type`             | Display name / type identifier                                              |
| `description`      | Human-readable description                                                  |
| `is_preview`       | Whether the agent is in preview                                             |
| `protected_dirs`   | Directories the CLI should not modify (excluded from checkpoints and diffs) |
| `hook_names`       | Agent lifecycle hooks this plugin handles                                   |
| `capabilities`     | Object declaring which optional capabilities are supported                  |

### `detect`

Returns whether the agent is available in the current environment. Return `{"present": false}` if the agent's dependencies are not met — the CLI will skip enabling the agent.

```bash theme={null}
entire-agent-myagent detect
```

```json theme={null}
{"present": true}
```

### `get-session-id`

Extracts a session ID from a hook input event.

**stdin:** [HookInput](/agents/external-agent-plugins/data-model#hookinput) JSON

```json theme={null}
{"session_id": "abc123"}
```

### `get-session-dir --repo-path <path>`

Returns where agent sessions are stored.

```json theme={null}
{"session_dir": "/path/to/sessions"}
```

### `resolve-session-file --session-dir <dir> --session-id <id>`

Resolves the session file path from a session directory and ID.

```json theme={null}
{"session_file": "/path/to/session/file.jsonl"}
```

### `read-session`

Reads session data from a hook input event.

**stdin:** [HookInput](/agents/external-agent-plugins/data-model#hookinput) JSON

**stdout:** [AgentSession](/agents/external-agent-plugins/data-model#agentsession) JSON

### `write-session`

Persists session data to disk. The plugin is responsible for choosing the storage location and format.

**stdin:** [AgentSession](/agents/external-agent-plugins/data-model#agentsession) JSON

Exit `0` on success.

### `read-transcript --session-ref <path>`

Reads a transcript file and returns its raw bytes on stdout.

### `chunk-transcript --max-size <n>`

Splits a transcript (raw bytes on stdin) into chunks.

```json theme={null}
{"chunks": ["<base64-encoded-chunk>", "..."]}
```

### `reassemble-transcript`

Reassembles chunks back into a transcript. Called during `entire checkpoint rewind` to reconstruct transcript data from stored chunks.

**stdin:**

```json theme={null}
{"chunks": ["<base64-encoded-chunk>", "..."]}
```

**stdout:** Raw transcript bytes.

### `format-resume-command --session-id <id>`

Returns the command a user would run to resume a session.

```json theme={null}
{"command": "myagent --resume abc123"}
```

## Optional capabilities

Set capabilities to `true` in your `info` response to enable these. The CLI will never call subcommands for capabilities you don't declare.

### `hooks`

Manage agent lifecycle hooks for Entire integration.

| Subcommand                              | Description                                                                                                                                                    |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse-hook --hook <name>`              | Parse a raw hook payload (stdin) into an [Event](/agents/external-agent-plugins/data-model#event). Return `null` if not relevant.                              |
| `install-hooks [--local-dev] [--force]` | Install hooks. `--local-dev` installs hooks pointing to a local development build. `--force` overwrites existing hook files. Returns `{"hooks_installed": 3}`. |
| `uninstall-hooks`                       | Remove installed hooks. Exit `0` on success.                                                                                                                   |
| `are-hooks-installed`                   | Check hook status. Returns `{"installed": true}`.                                                                                                              |

### `transcript_analyzer`

Extract data from agent transcripts.

| Subcommand                                          | Description                                            |
| --------------------------------------------------- | ------------------------------------------------------ |
| `get-transcript-position --path <path>`             | Returns `{"position": 12345}` (byte offset).           |
| `extract-modified-files --path <path> --offset <n>` | Returns `{"files": [...], "current_position": 12345}`. |
| `extract-prompts --session-ref <path> --offset <n>` | Returns `{"prompts": ["prompt text", ...]}`.           |
| `extract-summary --session-ref <path>`              | Returns `{"summary": "...", "has_summary": true}`.     |

### `transcript_preparer`

| Subcommand                                | Description                                         |
| ----------------------------------------- | --------------------------------------------------- |
| `prepare-transcript --session-ref <path>` | Pre-process a transcript file. Exit `0` on success. |

### `token_calculator`

| Subcommand                      | Description                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `calculate-tokens --offset <n>` | Calculate token usage from transcript bytes (stdin). `--offset` is the byte offset into the transcript to start counting from. |

Output:

```json theme={null}
{
  "input_tokens": 1500,
  "output_tokens": 500,
  "cache_creation_tokens": 0,
  "cache_read_tokens": 200,
  "api_call_count": 3
}
```

Only `input_tokens` and `output_tokens` are required. Other fields default to `0`.

### `text_generator`

| Subcommand                      | Description                                                     |
| ------------------------------- | --------------------------------------------------------------- |
| `generate-text --model <model>` | Generate text from a prompt (stdin). Returns `{"text": "..."}`. |

### `hook_response_writer`

| Subcommand                            | Description                                                 |
| ------------------------------------- | ----------------------------------------------------------- |
| `write-hook-response --message <msg>` | Write a message in the agent's native hook format (stdout). |

### `subagent_aware_extractor`

For agents that spawn subagents.

| Subcommand                                                      | Description                                                                                                                                                           |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extract-all-modified-files --offset <n> --subagents-dir <dir>` | Extract modified files from main + subagent transcripts (stdin: main transcript). Returns `{"files": [...]}`.                                                         |
| `calculate-total-tokens --offset <n> --subagents-dir <dir>`     | Calculate total tokens across main + subagent transcripts (stdin: main transcript). Same format as `calculate-tokens`, with optional `subagent_tokens` nested object. |