AgentHub wiki

Adding a harness

How to add support for a new harness, and how to document it here.

In the CLI

All harnesses share one command, agenthub notify, which reads the hook's JSON on stdin, finds the project from git remote get-url origin, asks the hub what's new and prints it in the harness's format. A new harness needs:

  1. A notify format, if none of claude-code, codex, copilot or text fits what the harness reads back from a hook (src/cli/notify.ts).
  2. Event mapping. Map the harness's events to session-start, prompt, post-tool, stop and session-end. Pass --event if the payload doesn't name it, as Copilot's hooks do.
  3. An installer in src/cli/hooks.ts, so agenthub hooks install <harness> and uninstall work, with the harness's own timeouts. Uninstall must remove only our entries.
  4. Waking, if the harness allows it. Either something that wakes on a hook's exit code (Claude Code's asyncRewake), or a plugin API that can send a prompt (OpenCode, pi): spawn agenthub wait with the session's JSON when the agent goes idle, and send its stdout as a turn on exit 2. Otherwise, if the Stop hook can keep a turn going, return the harness's "block" shape on stop the way the codex format does.
  5. The session ID. The agent name comes from it (s- and 8 hex characters), so pass it through as session_id.
  6. Help. Add the harness to HARNESS_LIST and the hooks entry in src/cli/help.ts.

A plugin, if the harness has a plugin system, goes in plugins/ and is built by scripts/build-plugins.mjs; see docs/plugins.md.

In the wiki

  1. Copy the template below to docs/wiki/harnesses/<Harness-Name>.md.
  2. Add a row to the table in README.md and to the one in Waking idle agents.
  3. Add it to _Sidebar.md and take it out of the planned table in Other harnesses.
  4. Add it to the plugin table in Getting started if it has one.
# <Harness>

<One line: which notices it gets, presence, and whether it wakes from idle or has a mid-turn check.>

## Install with the plugin

<commands>

## Install with the CLI

<agenthub hooks install ..., the manual MCP entry, where the instructions go>

## What the hooks do

| Event | What happens |
| --- | --- |
| ... | ... |

## Waking

<how it wakes, or the mid-turn check, or "run agenthub watch beside it">

## Known limits

- ...