External Agent Plugins

External agent plugins are standalone binaries that integrate any AI coding agent with the Entire CLI. The CLI discovers them automatically — no changes to the main repository required.

External agents must be enabled in your settings before the CLI will discover them. Add "external_agents": true to your .entire/settings.json file.

Plugins are arbitrary executables on your $PATH that receive repository paths and session data. Only install plugins you trust — they have the same filesystem access as the CLI itself.

How It Works

You create an executable named entire-agent-<name>
Place it anywhere on your $PATH
The CLI discovers it at startup and registers it as a new agent

The plugin communicates with the CLI through subcommands that read/write JSON over stdin/stdout. Each invocation is stateless. For a working example see roger-roger.

Environment

Every subcommand invocation receives these environment variables:

Variable	Description
`ENTIRE_REPO_ROOT`	Absolute path to the git repository root
`ENTIRE_PROTOCOL_VERSION`	Protocol version (currently `1`)

The working directory is always set to the repository root.

Conventions

Output: JSON on stdout (unless noted otherwise)
Errors: Non-zero exit code + message on stderr
Stateless: Each invocation is independent, no persistent connection

Lifecycle

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

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:

detect — Called to check whether your agent is available in the current environment.
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

parse-hook --hook <name> — Called on every hook invocation with the raw payload on stdin. Return a normalized 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.

get-session-id — Extract the session ID from the hook input (stdin).
get-session-dir --repo-path <path> — Return where sessions are stored.
resolve-session-file --session-dir <dir> --session-id <id> — Resolve the session file path.
read-session — Read existing session data (stdin: HookInput).
write-session — Persist updated session data.
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.

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

TurnEnd (type 3)

Fired when the agent finishes responding.

prepare-transcript --session-ref <path> — (if transcript_preparer capability) Pre-process the transcript.
read-transcript --session-ref <path> — Read the raw transcript bytes.
chunk-transcript --max-size <n> — Split large transcripts into storable chunks.
get-transcript-position --path <path> — (if transcript_analyzer capability) Get the current byte offset.
extract-modified-files --path <path> --offset <n> — (if transcript_analyzer capability) Extract newly modified files.
calculate-tokens --offset <n> — (if token_calculator capability) Calculate token usage.
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 rewind`	`read-transcript`, `reassemble-transcript`, `extract-modified-files`
`entire status`	`get-transcript-position`
`entire resume`	`format-resume-command`

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

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.

Required Subcommands

Every plugin must implement these subcommands.

`info`

Returns metadata and declares which optional capabilities your plugin supports.

entire-agent-myagent info

{
  "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.

entire-agent-myagent detect

{"present": true}

`get-session-id`

Extracts a session ID from a hook input event. stdin: HookInput JSON

{"session_id": "abc123"}

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

Returns where agent sessions are stored.

{"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.

{"session_file": "/path/to/session/file.jsonl"}

`read-session`

Reads session data from a hook input event. stdin: HookInput JSON stdout: AgentSession JSON

`write-session`

Persists session data to disk. The plugin is responsible for choosing the storage location and format. stdin: 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.

{"chunks": ["<base64-encoded-chunk>", "..."]}

`reassemble-transcript`

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

{"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.

{"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. 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:

{
  "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.

Data Types

HookInput

Passed via stdin to get-session-id and read-session.

{
  "hook_type": "stop",
  "session_id": "abc123",
  "session_ref": "/path/to/transcript.jsonl",
  "timestamp": "2026-01-13T12:00:00Z",
  "user_prompt": "Fix the login bug",
  "tool_name": "Write",
  "tool_use_id": "toolu_abc123",
  "tool_input": {"path": "/src/main.go"},
  "raw_data": {}
}

Field	Type	Required	Description
`hook_type`	string	Yes	`session_start`, `session_end`, `user_prompt_submit`, `stop`, `pre_tool_use`, `post_tool_use`
`session_id`	string	Yes	Agent session identifier
`session_ref`	string	Yes	Agent-specific session reference (typically a file path)
`timestamp`	string	Yes	RFC 3339 timestamp
`user_prompt`	string	No	User’s prompt text
`tool_name`	string	No	Tool name (from tool use hooks)
`tool_use_id`	string	No	Tool invocation ID
`tool_input`	object	No	Raw tool input JSON
`raw_data`	object	No	Agent-specific extension data

AgentSession

Used as input to write-session and output from read-session.

{
  "session_id": "abc123",
  "agent_name": "myagent",
  "repo_path": "/path/to/repo",
  "session_ref": "/path/to/transcript.jsonl",
  "start_time": "2026-01-13T12:00:00Z",
  "native_data": null,
  "modified_files": ["src/main.go"],
  "new_files": [],
  "deleted_files": []
}

Field	Type	Description
`session_id`	string	Agent session identifier
`agent_name`	string	Agent registry name
`repo_path`	string	Absolute path to the repository
`session_ref`	string	Path to session in agent’s storage
`start_time`	string	RFC 3339 timestamp
`native_data`	bytes/null	Opaque session content in agent’s native format
`modified_files`	string[]	Files modified during the session
`new_files`	string[]	Files created during the session
`deleted_files`	string[]	Files deleted during the session

Event

Returned by parse-hook. Represents a normalized lifecycle event.

{
  "type": 3,
  "session_id": "abc123",
  "session_ref": "/path/to/transcript.jsonl",
  "prompt": "Fix the login bug",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-01-13T12:00:00Z"
}

Event types:

Value	Name	Description
1	SessionStart	Agent session has begun
2	TurnStart	User submitted a prompt
3	TurnEnd	Agent finished responding
4	Compaction	Context window compression (triggers save + offset reset)
5	SessionEnd	Session terminated
6	SubagentStart	A subagent was spawned
7	SubagentEnd	A subagent completed

Optional event fields: previous_session_id, session_ref, prompt, model, timestamp, tool_use_id, subagent_id, tool_input, subagent_type, task_description, response_message, metadata. Only type and session_id are required.

Getting Started

CLI

Entire.io

Integrations

​How It Works

​Environment

​Conventions

​Lifecycle

​Phase 1: Discovery (CLI startup)

​Phase 2: Enable (entire enable)

​Phase 3: Agent session (hooks firing)

​SessionStart (type 1)

​TurnStart (type 2)

​TurnEnd (type 3)

​Compaction (type 4)

​SessionEnd (type 5)

​SubagentStart / SubagentEnd (types 6–7)

​Phase 4: User commands

​Phase 5: Disable (entire disable --uninstall)

​Error handling

​Required Subcommands

​info

​detect

​get-session-id

​get-session-dir --repo-path <path>

​resolve-session-file --session-dir <dir> --session-id <id>

​read-session

​write-session

​read-transcript --session-ref <path>

​chunk-transcript --max-size <n>

​reassemble-transcript

​format-resume-command --session-id <id>

​Optional Capabilities

​hooks

​transcript_analyzer

​transcript_preparer

​token_calculator

​text_generator

​hook_response_writer

​subagent_aware_extractor

​Data Types

​HookInput

​AgentSession

​Event

How It Works

Environment

Conventions

Lifecycle

Phase 1: Discovery (CLI startup)

Phase 2: Enable (`entire enable`)

Phase 3: Agent session (hooks firing)

SessionStart (type 1)

TurnStart (type 2)

TurnEnd (type 3)

Compaction (type 4)

SessionEnd (type 5)

SubagentStart / SubagentEnd (types 6–7)

Phase 4: User commands

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

Error handling

Required Subcommands

`info`

`detect`

`get-session-id`

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

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

`read-session`

`write-session`

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

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

`reassemble-transcript`

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

Optional Capabilities

`hooks`

`transcript_analyzer`

`transcript_preparer`

`token_calculator`

`text_generator`

`hook_response_writer`

`subagent_aware_extractor`

Data Types

HookInput

AgentSession

Event