basilisk-labs/agentplane-hermes-plugin

Name: agentplane-hermes-plugin
Author: basilisk-labs

🔌 Hermes plugin for spawning AgentPlane as an external worker lane.

★ 2 langPython licenseMIT updated2026-06-02

overview

This plugin integrates AgentPlane into the Hermes ecosystem by enabling external Kanban worker lanes. It functions by intercepting Kanban assignees matching specific patterns and resolving them to an external supervisor command rather than a standard Hermes profile. The integration maintains strict boundaries by requiring AgentPlane to manage task lifecycles through official APIs instead of direct database mutations. It supports path allowlisting for secure workspace management and includes a diagnostic tool for verifying registry and binary configurations.

Maps agentplane-* Kanban assignees to external supervisor commands
Requires explicit task ID mapping via card metadata
Enforces security through AGENTPLANE_HERMES_ALLOWED_ROOTS path allowlisting

full readme from github

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.