AgentPlane Hermes Plugin

Hermes plugin for spawning AgentPlane as an external worker lane.

This package makes Hermes Kanban assignees matching agentplane-* resolve to an external supervisor command instead of a Hermes profile.

Status

Compatibility plugin for current Hermes images, with a native registration path for Hermes runtimes that expose:

register_worker_lane(match, spawn_fn)

Without that hook, the plugin still provides doctor/registry checks and does not mutate kanban.db directly.

Runtime contract

Hermes image/runtime must provide:

• PATH containing /opt/hermes/bin
• Node.js 24+
• agentplane on PATH or AGENTPLANE_BIN=/path/to/agentplane
• AGENTPLANE_HERMES_LANE_REGISTRY=/opt/agentplane/lane-registry.json
• optional AGENTPLANE_HERMES_ALLOWED_ROOTS=/workspace:/srv/agentplane path allowlist for spawned AgentPlane workspaces
• Hermes plugin loader pointed at this plugin

Cards dispatched to an AgentPlane lane must carry an explicit AgentPlane task id in agentplane_task_id, agentplaneTaskId, or metadata.agentplane.task_id. The plugin intentionally does not treat a Hermes card id as an AgentPlane task id.

Example lane registry:

{
  "schema": "agentplane.hermes.lane-registry.v1",
  "lanes": [
    {
      "name": "agentplane-coder",
      "match": "agentplane-*",
      "kind": "agentplane",
      "spawn": {
        "command": "agentplane",
        "args": ["hermes", "supervise", "{agentplane_task_id}", "--root", "{repo}", "--execute-step", "--json"]
      },
      "env": [
        "HERMES_KANBAN_TASK",
        "HERMES_KANBAN_BOARD",
        "HERMES_KANBAN_RUN_ID",
        "HERMES_KANBAN_WORKSPACE",
        "HERMES_KANBAN_CLAIM_LOCK"
      ]
    }
  ]
}

Install

Copy this repository into a Hermes plugin path, for example:

mkdir -p ~/.hermes/plugins/agentplane
cp -R __init__.py agentplane_hermes_plugin plugin.yaml ~/.hermes/plugins/agentplane/

Enable it in Hermes config:

plugins:
  enabled:
    - agentplane

Set runtime variables:

export AGENTPLANE_HERMES_LANE_REGISTRY=/opt/agentplane/lane-registry.json
export AGENTPLANE_BIN=/usr/local/bin/agentplane
export AGENTPLANE_HERMES_ALLOWED_ROOTS=/workspace

Doctor

When Hermes exposes plugin CLI registration, run:

hermes agentplane doctor --json

Expected signal:

• registry exists
• AgentPlane binary resolves
• at least one kind: agentplane lane exists
• native worker-lane API is reported when Hermes exposes it

Development

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python scripts/check_integrity.py
python -m pytest

Boundaries

The plugin must not write directly to ~/.hermes/kanban.db. AgentPlane should complete, block, heartbeat, and reclaim work only through Hermes lifecycle APIs or CLI surfaces.