hermes-ao 1.0.0

Agent Orchestrator plugin for Hermes — spawn and manage parallel AI coding agents from chat

hermes-ao

Agent Orchestrator (AO) plugin for Hermes. Gives your Hermes bot 17 tools to spawn, monitor, and manage parallel AI coding agents from chat.

What it does

Once installed, your Hermes bot (Discord, Slack, CLI, etc.) can:

• Spawn agents on GitHub/Linear issues (ao_spawn)
• List active sessions and their status (ao_sessions)
• Send messages to running agents (ao_send)
• Kill sessions (ao_kill)
• Check health of the AO server (ao_doctor)
• Review and verify agent work (ao_review_check, ao_verify)
• Manage issues — create, list backlog (ao_create_issue, ao_backlog)
• Merge PRs created by agents (ao_merge_pr)
• Monitor system observability (ao_observability)
• ...and more (17 tools total)

It also includes a pre_llm_call hook that automatically injects live AO context (active sessions, open issues) into conversations when the user mentions work-related topics.

Prerequisites

• Hermes installed and running
• Agent Orchestrator installed and running somewhere accessible

Install

pip install hermes-ao

Configuration

Set these environment variables before starting Hermes:

Required

Variable	Description	Example
AO_CWD	Path to your project directory (where agent-orchestrator.yaml lives)	/home/user/my-project

Optional

Variable	Default	Description
AO_API_URL	http://127.0.0.1:3000	AO server URL
AO_PUBLIC_URL	(empty)	Public URL for dashboard links shown to users (e.g. http://your-server:3000)
AO_PATH	ao	Path to the ao CLI binary
GH_PATH	gh	Path to the gh CLI binary
AO_API_TIMEOUT	10	API request timeout (seconds)
AO_SPAWN_TIMEOUT	30	Agent spawn timeout (seconds)
AO_CLI_TIMEOUT	15	CLI command timeout (seconds)

Example setup

# Add to your shell profile (~/.bashrc, ~/.zshrc) or systemd service file
export AO_CWD=/home/user/my-project
export AO_API_URL=http://localhost:3000
export AO_PUBLIC_URL=http://your-server:3000

Then restart Hermes:

hermes restart
# or start a new session

Verify it works

hermes chat -q "What AO sessions are running?"

Or in Discord, ask your bot: "What agents are running?"

Alternative install: directory-based

If you prefer not to use pip, copy the plugin directly:

mkdir -p ~/.hermes/plugins/
cp -r hermes_ao ~/.hermes/plugins/hermes-ao

Set the environment variables and restart Hermes.

Tools reference

Tool	Description
ao_sessions	List active agent sessions
ao_issues	List open issues from the tracker
ao_spawn	Spawn a new coding agent (single, batch, or orchestrator mode)
ao_send	Send a message to a running agent session
ao_kill	Terminate an agent session
ao_doctor	Run AO health diagnostics
ao_review_check	Check for PRs needing review
ao_verify	Verify agent work on an issue
ao_session_cleanup	Clean up sessions with merged/closed PRs
ao_session_restore	Restore a stopped session
ao_session_claim_pr	Link a PR to a session
ao_create_issue	Create a new issue in the tracker
ao_list_projects	List configured AO projects
ao_backlog	Show the issue backlog
ao_merge_pr	Merge a PR
ao_observability	Get system metrics and health data
ao_session_output	Get recent output from a session

Architecture

Discord/Slack/CLI → Hermes → LLM → ao_* tools → AO HTTP API → coding agents

The plugin talks to AO's REST API. If the API is unreachable, it falls back to shelling out to the ao CLI. A circuit breaker prevents hammering a down server.

License

MIT