# Add your own agent

> Teach Hivemind a coding agent it does not know yet, with one agent.yaml file: how to start it, read its screen and answer it.

Source: https://hivemind.griiken.com/guide/agent-providers/

Add an <Tooltip tip="A coding agent's own program running in a tile, which Hivemind reads and answers." cta="Glossary" href="https://hivemind.griiken.com/guide/glossary/#agent">agent</Tooltip> when you use a coding agent's program that HiveHub does not list yet. You write one file, `agent.yaml`. No code and no rebuild.

<AgentPrompt description="Paste this into your coding agent to write an agent file for a program you use, check it on the real program, and offer it to everyone." page="agent-providers">{`
Write a Hivemind agent file (\`agent.yaml\`) for a coding-agent program on this computer, check it against the real program, and, if I want, offer it to everyone.

1. Probe the real program first. Never guess one agent from another. Ask me which program it is. Find it with \`command -v\`, then run its \`--version\` and \`--help\`, and \`--help\` on its main subcommand. Read its own docs too. For each of these, write down the answer and the line or page that says so, or "could not find it":
   - how a task is passed: as an argument, or typed into its screen;
   - whether it has hooks that run when it finishes replying, or before a tool runs, and whether a hook can block;
   - where it keeps sessions, and how to resume one;
   - what its screen shows while it works, when it asks permission, and when it asks a question;
   - which keys allow, deny, or pick an option on those screens.
2. Write \`~/.config/hivemind/agents/<id>/agent.yaml\` from the "agent.yaml reference" page: \`manifestVersion: 2\`, an \`id\` equal to the folder name, \`bin\` as the bare program name (never a path), and every field under \`caps\`. Claim a capability only if step 1 proved it. \`turnSignal: true\` and \`supervise: broker\` need \`launch.hcp\` and a hook file beside the manifest. \`resume\` other than \`none\` needs \`session.resume\`. Regular expressions are not allowed in \`detect.rules\`.
3. Check it: \`hive agents validate <folder>\`, until it passes. Then \`hive agents install <folder>\`, and check \`hive agents list\` shows it with no problem.
4. If Hivemind is open, try it: \`hive ctl spawn --agent <id> --prompt "list the files here"\`. Watch \`hive ctl agents\`: it must read working while the agent works, and waiting when it asks permission. \`hive ctl stream <tile> --snapshot\` shows its screen. If you set answer keys, check each with \`hive ctl keys\` on a real question.
5. Offer it to everyone only if I say so. New agents are listed by pull request to the GitHub repository dip497/hivemind-plugins, in \`agents/<id>/\` with a \`README.md\`. Use my GitHub account through \`gh\`; if \`gh\` is not signed in, ask me to sign in myself.

At the end, show me the file. Say which capabilities you proved and from where, which you left off and why, and the pull request link if you opened one.
`}</AgentPrompt>

## Before you start [#before-you-start]

- Hivemind is installed. See [Install and run your first agent](https://hivemind.griiken.com/guide/getting-started/).
- The agent's own program is installed and on your `PATH`.
- You have read its `--help`. Everything you claim in the file must come from the real program.

<Warning>
An agent file starts a program in your terminal, with your permissions. There is no sandbox. Before
you install someone else's, read its `bin` and `spawn`, and install only agents whose author you
trust.
</Warning>

## Write the file [#write-the-file]

<Steps>
  <Step title="Learn what the program can do">
    Run `<program> --help` and read its docs. Write down how it takes a task, whether it has hooks,
    and where it keeps sessions. Then note what its screen shows while it works and while it waits
    on you.

    Check: you have an answer, with a source, for each. "Could not find it" is an answer.
  </Step>
  <Step title="Make the folder">
    The folder name is the agent's id:

    ```bash
    mkdir -p ~/.config/hivemind/agents/acme
    ```
  </Step>
  <Step title="Write agent.yaml">
    Start small. Claim only what you proved in step 1:

    ```yaml ~/.config/hivemind/agents/acme/agent.yaml
    manifestVersion: 2
    id: acme
    label: Acme Coder
    bin: acme-coder          # the program's name on your PATH, never a path
    enabled: true

    caps:
      promptDelivery: typed  # typed into its screen; argv if it takes the task as an argument
      turnSignal: false      # true only with launch.hcp and a hook file
      resume: none
      supervise: human       # it has its own permission questions
      blockedDetection: true

    detect:
      default: idle
      rules:
        - when: { contains: "approve this?" }
          then: blocked
        - when: { line: [{ gerundAfterPrefix: ["braille"] }] }   # "⠋ Reading files…"
          then: working
    ```

    Every field is described in the [agent.yaml reference](https://hivemind.griiken.com/guide/agent-yaml/).
  </Step>
  <Step title="Validate it">
    ```bash
    hive agents validate ~/.config/hivemind/agents/acme
    ```

    Check: it passes. If not, it names each field it refuses. Fix them and run it again.
  </Step>
  <Step title="Install it">
    ```bash
    hive agents install ~/.config/hivemind/agents/acme
    ```

    Check: `hive agents list` shows `acme`, on, with no problem.
  </Step>
</Steps>

## Check it worked [#check-it-worked]

1. Start it in the open app:

   ```bash
   hive ctl spawn --agent acme --prompt "list the files here"
   ```

2. Watch its tile. While it works, the tile shows **working**.
3. Give it a task that needs permission, such as editing a file.

Check: its tile turns amber and shows **needs you**, and the bell in the Layers panel counts it.
`hive ctl agents` shows the same status.

## If it didn't [#if-it-didnt]

| You see | Do this |
|---|---|
| `hive agents validate` refuses a capability | You claimed something that needs wiring. Add the block it names, or set the claim to `false` / `none`. |
| The tile stays **idle** while the agent works | Add a `detect` rule for what its screen shows while it works. Capture the real screen with `hive ctl stream <tile> --snapshot`. |
| A permission question reads as finished, not **needs you** | Add a `blocked` rule for that screen, and set `blockedDetection: true`. |
| Something else | [Troubleshooting](https://hivemind.griiken.com/guide/troubleshooting/) |

## Where agent files live [#where-agent-files-live]

| Folder | Used for |
|---|---|
| `~/.config/hivemind/agents/<id>/agent.yaml` | your agents, in every workspace |
| `<repo>/.hivemind/agents/<id>/agent.yaml` | agents a repository ships for everyone who opens it |

A repository can only add agents. It can never change what an id you already have runs.

```bash
hive agents list                # every agent, where it came from, and why any is unavailable
hive agents remove acme
```

## Share it [#share-it]

Agents are listed on HiveHub by pull request: see [Publish an agent](https://hivemind.griiken.com/guide/publish-to-hivehub/#publish-an-agent).
Once it is merged, `hive agents install acme` works for everyone.

## Related [#related]

- [agent.yaml reference](https://hivemind.griiken.com/guide/agent-yaml/): every field.
- [Run agents](https://hivemind.griiken.com/guide/agents/): install, start and put agents to sleep.
- [Plugins](https://hivemind.griiken.com/guide/plugins/): the other kinds of plugin.

<LastValidated />