Metadata-Version: 2.4
Name: hermes-ao
Version: 1.0.0
Summary: Agent Orchestrator plugin for Hermes — spawn and manage parallel AI coding agents from chat
Author: ComposioHQ
License-Expression: MIT
Project-URL: Homepage, https://github.com/ComposioHQ/agent-orchestrator
Project-URL: Repository, https://github.com/ComposioHQ/agent-orchestrator
Project-URL: Issues, https://github.com/ComposioHQ/agent-orchestrator/issues
Keywords: hermes,agent-orchestrator,ai-agents,coding-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# hermes-ao

Agent Orchestrator (AO) plugin for [Hermes](https://hermes-agent.nousresearch.com/). 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](https://hermes-agent.nousresearch.com/) installed and running
- [Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) installed and running somewhere accessible

## Install

```bash
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

```bash
# 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:

```bash
hermes restart
# or start a new session
```

## Verify it works

```bash
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:

```bash
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
