## Build an agent plugin

Build an agent plugin when you want Entire to support a coding agent that is not built in yet. The [external-agents repository](https://github.com/entireio/external-agents) includes an agent skill that researches the target agent, scaffolds the binary, writes tests, and implements the protocol. The protocol is language-agnostic; this guide uses that Go-based repo and its skill. For the protocol itself, see [Architecture](https://docs.entire.io/agents/external-agent-plugins/architecture), [Commands](https://docs.entire.io/agents/external-agent-plugins/commands), [Lifecycle](https://docs.entire.io/agents/external-agent-plugins/lifecycle), and [Data Model](https://docs.entire.io/agents/external-agent-plugins/data-model).

**Building a private or internal plugin?** This guide is the upstream-contribution path (it ends in a pull request to `external-agents`). For a plugin you won’t contribute back, skip the issue and PR steps and follow the protocol reference above.

## Before you start

Open an issue in [`entireio/external-agents`](https://github.com/entireio/external-agents) before writing code. Adding support for a new agent creates a long-term support commitment, so align with maintainers first. You need:

- The target agent CLI installed and authenticated  
- [The Entire CLI installed](https://docs.entire.io/installation)  
- [Go](https://go.dev/doc/install) and [mise](https://mise.jdx.dev/getting-started.html)  
- A target agent with lifecycle hooks or another reliable event mechanism  
- Readable session or transcript data  
- A stable session ID

## Clone the repo

```bash
git clone https://github.com/entireio/external-agents.git
cd external-agents
mise trust
mise install
```

New integrations live under `agents/entire-agent-<slug>`. Each integration is a standalone binary named `entire-agent-<slug>`.

## Run the Agent Skill

The repo includes an agent skill named `entire-external-agent`, and supported tools auto-discover it with no additional configuration. See the [repo instructions](https://github.com/entireio/external-agents?tab=readme-ov-file#getting-started--zero-setup) for the current supported tools. Run the skill:

```bash
/entire-external-agent
```

When prompted, provide the target agent name and slug.

## What the Skill Does

The skill runs three phases:

| Phase   | What happens |
| ------- | ------------ |
| **Research** | Finds the target agent’s hooks, session IDs, transcript storage, CLI commands, and capabilities. |
| **Scaffold** | Creates the plugin structure, protocol stubs, and lifecycle test wiring. |
| **Implement** | Uses compliance and lifecycle failures to implement the plugin and add tests. |

You can also run a single phase when you need to restart or inspect part of the process.

```bash
/entire-external-agent research
/entire-external-agent write-tests
/entire-external-agent implement
```

## Reference examples

The [external-agents repository](https://github.com/entireio/external-agents) contains working plugins you can inspect while building your own:

| Plugin | Target agent | Notes |
| --- | --- | --- |
| [`entire-agent-amp`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-amp) | Amp | Project plugin with transcript preparation, token calculation, and compact transcript support. |
| [`entire-agent-goose`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-goose) | Goose | Project plugin that exports Goose sessions from SQLite-backed storage. |
| [`entire-agent-kiro`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-kiro) | Kiro | Lifecycle hooks and transcript analysis for Kiro sessions. |

For a minimal reference implementation outside the main examples repo, see [`roger-roger`](https://github.com/entireio/roger-roger).

## Review the output

When the skill finishes, review:

- `agents/entire-agent-<slug>/AGENT.md`  
- `agents/entire-agent-<slug>/README.md`  
- The declared capabilities  
- Protocol compliance results  
- Lifecycle test results  
- Any remaining gaps or local dependencies

Treat captured hook payloads and transcript fixtures as ground truth. Documentation can drift.

## Verify locally

Build the binary, put it on your `PATH`, and enable it in a test repository:

```bash
cd agents/entire-agent-<slug>
mise run build
export PATH="$PWD:$PATH"

cd /path/to/test-repo
entire enable --agent SLUG
```

Run the target agent and make a small file change. Then check that Entire captured the session:

```bash
entire status
entire checkpoint list
entire checkpoint explain CHECKPOINT_ID --short
```

Look for a checkpoint with the expected session, transcript, and modified files.

## Open the PR

Reference the approved issue and include:

- Agent name and binary name  
- Declared capabilities  
- Protocol compliance status  
- Lifecycle test status  
- Unit test coverage  
- Any local dependencies you could not test  
- Known limitations

CI will build the agent and run the shared checks.