basilisk-labs
agentplane-hermes-plugin
Hermes plugin that spawns AgentPlane as an external Kanban worker lane for AI-driven task execution.
Repository last updated Jun 2, 2026
Overview
The AgentPlane Hermes Plugin integrates AgentPlane into the Hermes ecosystem by enabling external Kanban worker lanes. It intercepts Kanban assignees matching the pattern agentplane-* and resolves them to an external supervisor command instead of a standard Hermes profile. This allows AgentPlane to handle complex, AI-driven workflows while Hermes manages the Kanban board.
The plugin enforces strict boundaries: AgentPlane must manage task lifecycles through official Hermes APIs or CLI surfaces, and must not write directly to the Kanban database. Cards dispatched to an AgentPlane lane must carry an explicit AgentPlane task ID in card metadata (e.g., agentplane_task_id), preventing confusion with Hermes card IDs.
Security is maintained via path allowlisting: the environment variable AGENTPLANE_HERMES_ALLOWED_ROOTS restricts which directories AgentPlane workspaces can access. A diagnostic tool (hermes agentplane doctor) verifies registry existence, binary resolution, and lane configuration.
Highlights
- 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
- Includes doctor command for registry and binary verification
- Supports path allowlisting for secure workspace management
Features
External Worker Lane Integration
Intercepts Kanban assignees matching agentplane-* and spawns AgentPlane as an external supervisor process, enabling AI-driven task execution.
Explicit Task ID Mapping
Cards must carry an AgentPlane task ID in metadata (agentplane_task_id, agentplaneTaskId, or metadata.agentplane.task_id) to prevent ID collisions.
Path Allowlisting
Uses AGENTPLANE_HERMES_ALLOWED_ROOTS to restrict workspace directories, enhancing security by preventing unauthorized file access.
Diagnostic Doctor Tool
Provides a hermes agentplane doctor command to verify registry existence, binary resolution, and lane configuration.
Installation
Commands are reproduced exactly as published by the project maintainers. Always check the upstream repository for the current instructions.
mkdir -p ~/.hermes/plugins/agentplane
cp -R __init__.py agentplane_hermes_plugin plugin.yaml ~/.hermes/plugins/agentplane/plugins:
enabled:
- agentplaneexport AGENTPLANE_HERMES_LANE_REGISTRY=/opt/agentplane/lane-registry.json
export AGENTPLANE_BIN=/usr/local/bin/agentplane
export AGENTPLANE_HERMES_ALLOWED_ROOTS=/workspaceRequirements
- Hermes runtime with Node.js 24+
- PATH containing /opt/hermes/bin
- agentplane binary on PATH or AGENTPLANE_BIN set
- AGENTPLANE_HERMES_LANE_REGISTRY environment variable pointing to a lane registry JSON file
- Hermes plugin loader configured to load this plugin
How it's built
The plugin is written in Python and structured as a standard Hermes plugin with a plugin.yaml manifest. The core logic resides in agentplane_hermes_plugin/__init__.py. It relies on a lane registry file (JSON) that defines spawn commands and environment variables. The plugin expects the Hermes runtime to expose a register_worker_lane(match, spawn_fn) hook for native integration; otherwise, it provides registry checks without mutating kanban.db.
Key environment variables include AGENTPLANE_HERMES_LANE_REGISTRY (path to lane registry), AGENTPLANE_BIN (path to AgentPlane binary), and optional AGENTPLANE_HERMES_ALLOWED_ROOTS (colon-separated path allowlist). The plugin requires Node.js 24+ and the Hermes runtime to have /opt/hermes/bin in PATH.
Repository layout includes __init__.py at the top level, agentplane_hermes_plugin/ package, plugin.yaml, pyproject.toml, registry/lane-registry.example.json, scripts/check_integrity.py, and tests/test_plugin.py.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The basilisk-labs/agentplane-hermes-plugin repository is the authoritative source and the place to file issues or contribute.
Category: Autonomy & Orchestration · Licensed under MIT