Metadata-Version: 2.4
Name: opencode-agent-hub
Version: 0.3.5
Summary: Multi-agent coordination daemon and tools for OpenCode
Project-URL: Homepage, https://github.com/xnoto/opencode-agent-hub
Project-URL: Repository, https://github.com/xnoto/opencode-agent-hub
Project-URL: Issues, https://github.com/xnoto/opencode-agent-hub/issues
Author: xnoto
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,coordination,daemon,mcp,opencode
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: requests>=2.28.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-requests>=2.28.0; extra == 'dev'
Description-Content-Type: text/markdown

# opencode-agent-hub

Multi-agent coordination daemon and tools for [OpenCode](https://github.com/sst/opencode).

Enables multiple AI agents running in separate OpenCode sessions to communicate, collaborate, and coordinate work through a shared message bus.

> **Warning**: This software enables autonomous agent-to-agent communication which triggers LLM API calls. Use at your own risk. The authors are not responsible for any token usage, API costs, or other expenses incurred. Consider enabling [rate limiting](#rate-limiting-optional) to control costs.

## Table of Contents

- [Features](#features)
- [How It Works](#how-it-works)
  - [Session Discovery](#session-discovery)
  - [Message Flow](#message-flow)
  - [The Relay Server](#the-relay-server)
  - [Coordination Flow](#coordination-flow)
  - [Push Model (No Polling Required by Agents)](#push-model-no-polling-required-by-agents)
  - [Session Lifecycle](#session-lifecycle)
  - [Known Issues](#known-issues)
    - [Injected Messages Not Visible in TUI](#injected-messages-not-visible-in-tui)
    - [TUI May Show Continued Processing After Response](#tui-may-show-continued-processing-after-response)
    - [Orientation Messages May Trigger Security Heuristics](#orientation-messages-may-trigger-security-heuristics)
  - [Coordination Test Results (Jan 2026)](#coordination-test-results-jan-2026)
- [Architecture](#architecture)
- [Prerequisites](#prerequisites)
- [Quickstart](#quickstart)
- [Installation](#installation)
  - [Homebrew (macOS)](#homebrew-macos)
  - [uv (PyPI)](#uv-pypi)
  - [pipx (PyPI)](#pipx-pypi)
  - [From source](#from-source)
- [Running as a Service](#running-as-a-service)
  - [macOS (launchd)](#macos-launchd)
  - [Linux (systemd)](#linux-systemd)
- [Usage](#usage)
  - [Start the daemon](#start-the-daemon)
  - [Monitor with the dashboard](#monitor-with-the-dashboard)
  - [Run as standalone scripts (uv)](#run-as-standalone-scripts-uv)
- [Configuration](#configuration)
  - [Rate Limiting (Optional)](#rate-limiting-optional)
  - [Coordinator (Optional)](#coordinator-optional)
- [Directory Structure](#directory-structure)
- [Message Format](#message-format)
- [Integration with MCP](#integration-with-mcp)
- [Metrics](#metrics)
- [Development](#development)
- [Acknowledgments](#acknowledgments)
- [License](#license)

## Features

- **Message Bus**: Filesystem-based message passing between agents via `~/.agent-hub/messages/`
- **Session Integration**: Automatically discovers and injects messages into OpenCode sessions
- **Thread Management**: Conversations tracked with auto-created thread IDs and resolution
- **Agent Auto-Registration**: Sessions automatically registered as agents by project path
- **Garbage Collection**: Stale messages, agents, and threads cleaned up (1hr TTL)
- **Prometheus Metrics**: Exportable metrics at `~/.agent-hub/metrics.prom`
- **Dashboard**: Real-time terminal UI showing agents, threads, and messages

## How It Works

The daemon operates as a **message broker** between OpenCode sessions, using a local relay server to inject messages directly into agent conversations and to **proactively encourage coordination** via a coordinator agent.

### Session Discovery

1. **Daemon starts** an OpenCode relay server on port 4096 (if not already running)
2. **Polls the relay API** (`GET /session`) every 5 seconds to discover active sessions
3. **Auto-registers agents** based on each session's working directory (project path)
4. **Injects an orientation message** into newly discovered sessions, informing the agent of its registered identity
5. **Notifies the coordinator** to capture the agent's task and introduce related agents

### Message Flow

When Agent A sends a message to Agent B:

```
Agent A                    Daemon                      Agent B
   │                         │                            │
   │  write JSON to          │                            │
   │  ~/.agent-hub/messages/ │                            │
   │ ───────────────────────>│                            │
   │                         │  detect new file           │
   │                         │  (watchdog)                │
   │                         │                            │
   │                         │  lookup Agent B's session  │
   │                         │  via relay API             │
   │                         │                            │
   │                         │  POST /session/{id}/prompt │
   │                         │ ──────────────────────────>│
   │                         │                            │
   │                         │                   Agent B wakes,
   │                         │                   sees message with
   │                         │                   response instructions
```

### The Relay Server

The daemon auto-starts `opencode serve --port 4096` which provides:

- **Session listing**: `GET /session` - returns all active OpenCode sessions
- **Message injection**: `POST /session/{id}/prompt_async` - injects a prompt that wakes the agent

This relay server sees **all** OpenCode TUI instances on the machine, allowing the daemon to route messages to any session regardless of which terminal it's running in. The coordinator relies on the relay server to inject **task capture prompts** and **introductions** that encourage agents to collaborate.

### Coordination Flow

The coordinator uses the relay server to proactively connect agents without requiring the user to manually broker introductions.

```
New Session         Daemon                 Coordinator             Other Agent
    │                 │                        │                      │
    │  OpenCode TUI    │                        │                      │
    │ ────────────────>│                        │                      │
    │                 │  notify NEW_AGENT       │                      │
    │                 │ ───────────────────────>│                      │
    │                 │                        │ ask: "What are you    │
    │                 │                        │ working on?"          │
    │                 │                        │ ─────────────────────>│
    │                 │                        │                      │
    │                 │                        │ analyze tasks         │
    │                 │                        │ send introductions    │
    │                 │                        │ ─────────────────────>│
    │                 │                        │                      │
```

This keeps the coordination overhead low while still ensuring agents know who to talk to.

### Push Model (No Polling Required by Agents)

Agents don't need to poll for messages. The daemon:
1. Watches the filesystem for new message files
2. Looks up the target agent's active session
3. Injects the message directly into that session via the relay API
4. The injection **wakes** the agent and triggers an LLM response

Each injected message includes full response instructions, so agents don't need special hub protocol knowledge.

### Session Lifecycle

The daemon only tracks sessions created **after** it starts:

- **New sessions**: OpenCode TUIs started after the daemon will receive an orientation message and be tracked for message routing
- **Pre-existing sessions**: Sessions that were running before the daemon started are ignored (no orientation spam)
- **Daemon restart**: Gives a clean slate - only sessions created after restart are tracked

This design ensures no unnecessary token generation on historical sessions while reliably catching all new agent work.

### Known Issues

#### Injected Messages Not Visible in TUI

Injected messages (orientation and inter-agent communication) are not visible in the OpenCode TUI. This is a known upstream issue: [opencode#8564](https://github.com/sst/opencode/issues/8564)

**Impact**: Agent-to-agent communication happens "invisibly" from the user's perspective. Agents receive and process the messages, but users don't see them in the conversation.

**Workaround**: Use `agent-hub-watch` dashboard to monitor agent activity, message flow, and conversation threads in real-time.

#### TUI May Show Continued Processing After Response

After an agent completes a response, the TUI may briefly show continued "thinking" indicators (spinning tokens). This appears to be a TUI display artifact related to how `prompt_async` injections are handled, not actual token consumption.

**Impact**: Visual only - the agent has completed its work despite the spinner.

#### Orientation Messages May Trigger Security Heuristics

Some models (particularly Claude) may flag orientation messages as potential prompt injections due to their structured format. The daemon uses a minimal plain-text format to reduce this, but highly security-conscious model configurations may still flag them.

**Impact**: Agent may acknowledge hub tools but report "no connection message received."

**Workaround**: The agent will still have access to hub tools via MCP and can collaborate - it just won't have the orientation context.

### Coordination Test Results (Jan 2026)

Observed a minimal coordination run with two agents (frontend + backend) and a coordinator configured to **introduce once, then stand down**.

**Test setup**:
- Frontend task: login form that calls `POST /api/auth/login`
- Backend task: implement `/api/auth/login` with JWT response
- Coordinator model: `opencode/claude-opus-4-5`

**Observed interaction** (3 total messages):
1. Frontend → Backend: asked for API contract details (request/response/error shapes)
2. Backend → Frontend: provided full contract (status codes, schemas, CORS, JWT)
3. Frontend → Backend: confirmed receipt and implementation

**QA follow-up**:
- A third agent (QA) was spawned with only the instruction to test the end-to-end login flow.
- The QA agent asked for ports/credentials and received the details directly from frontend/backend without explicit user brokering.

**Outcomes**:
- ✅ Agents coordinated directly without broadcast spam
- ✅ Coordinator stayed silent (no redundant acknowledgments)
- ✅ Contract handshake completed in 3 messages
- ✅ QA agent successfully obtained testing details from other agents without manual coordination

**Cost overhead (estimate)**:
- ~5–7 message injections (frontend/backend + QA) → ~5–7 LLM calls
- Approx total tokens: **~8k–12k** (context + responses)
- Approx cost: **$0.08–$0.25** depending on model/provider


## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         agent-hub-daemon                             │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │ File Watcher │  │ Session Poll │  │  GC Worker   │               │
│  │  (watchdog)  │  │   (5s loop)  │  │  (60s loop)  │               │
│  └──────┬───────┘  └──────┬───────┘  └──────────────┘               │
│         │                 │                                          │
│         │  new message    │  new session                             │
│         ▼                 ▼                                          │
│  ┌──────────────────────────────────┐                               │
│  │      Message Processing Queue     │                               │
│  │  (async workers with retries)     │                               │
│  └──────────────┬───────────────────┘                               │
│                 │                                                    │
│                 │ POST /session/{id}/prompt_async                    │
│                 ▼                                                    │
│  ┌──────────────────────────────────┐    ┌────────────────────────┐ │
│  │   OpenCode Relay Server (4096)   │───▶│  OpenCode Sessions     │ │
│  │   - Lists all active sessions    │    │  (TUI instances)       │ │
│  │   - Injects prompts into any     │    │                        │ │
│  └──────────────────────────────────┘    └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```

## Prerequisites

This daemon requires [agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp) by [@gilbarbara](https://github.com/gilbarbara) to be configured in OpenCode. This MCP server provides the tools agents use to send messages.

Add to your `~/.config/opencode/config.json`:

```json
{
  "mcp": {
    "agent-hub": {
      "type": "local",
      "command": ["npx", "-y", "agent-hub-mcp@latest"],
      "enabled": true
    }
  }
}
```

Restart OpenCode after adding the configuration.

## Quickstart

1. Install (pick one):

```bash
# Homebrew (macOS)
brew tap xnoto/opencode-agent-hub
brew install opencode-agent-hub

# uv (PyPI)
uv tool install opencode-agent-hub

# pipx (PyPI)
pipx install opencode-agent-hub
```

2. Start the daemon:

```bash
agent-hub-daemon
```

3. Monitor with the dashboard:

```bash
agent-hub-watch
```

4. (Optional) Run as a service (see [Running as a Service](#running-as-a-service)).

## Installation

### Homebrew (macOS)

```bash
# Tap + install
brew tap xnoto/opencode-agent-hub
brew install opencode-agent-hub

# Or one command
brew install xnoto/opencode-agent-hub/opencode-agent-hub
```

Service + manual usage (matches the Homebrew tap docs):

```bash
# Start as a service
brew services start opencode-agent-hub

# Run manually
agent-hub-daemon
agent-hub-watch

# Stop service
brew services stop opencode-agent-hub
```

### uv (PyPI)

```bash
uv tool install opencode-agent-hub
```

### pipx (PyPI)

```bash
pipx install opencode-agent-hub
```

### From source

```bash
git clone https://github.com/xnoto/opencode-agent-hub
cd opencode-agent-hub
uv sync
```

## Running as a Service

### macOS (launchd)

```bash
# Install
cp contrib/launchd/com.xnoto.agent-hub-daemon.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.xnoto.agent-hub-daemon.plist

# Or with Homebrew
brew services start opencode-agent-hub

# View logs
tail -f ~/Library/Logs/agent-hub-daemon.log

# Stop
launchctl unload ~/Library/LaunchAgents/com.xnoto.agent-hub-daemon.plist
```

### Linux (systemd)

```bash
# Install
mkdir -p ~/.config/systemd/user
cp contrib/systemd/agent-hub-daemon.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now agent-hub-daemon

# View logs
journalctl --user -u agent-hub-daemon -f

# Stop
systemctl --user stop agent-hub-daemon
```

## Usage

### Start the daemon

```bash
agent-hub-daemon
```

The daemon will:
1. Start an OpenCode hub server on port 4096 (if not already running)
2. Watch `~/.agent-hub/messages/` for new message files
3. Auto-register agents for any OpenCode session it discovers
4. Inject messages into the appropriate sessions

### Monitor with the dashboard

```bash
agent-hub-watch
```

Shows a live view of:
- Daemon status (running/stopped)
- Registered agents and their last seen time
- Active conversation threads
- Recent messages

### Run as standalone scripts (uv)

The scripts can also run directly without installation:

```bash
# Daemon
uv run src/opencode_agent_hub/daemon.py

# Dashboard
uv run src/opencode_agent_hub/watch.py
```

## Configuration

Configuration via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENCODE_PORT` | `4096` | Port for OpenCode relay server |
| `AGENT_HUB_DAEMON_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |

### Rate Limiting (Optional)

To prevent excessive agent chatter, enable rate limiting:

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_HUB_RATE_LIMIT` | `false` | Enable rate limiting (`true`, `1`, or `yes`) |
| `AGENT_HUB_RATE_LIMIT_MAX` | `10` | Max messages per agent per window |
| `AGENT_HUB_RATE_LIMIT_WINDOW` | `300` | Window size in seconds (default: 5 min) |
| `AGENT_HUB_RATE_LIMIT_COOLDOWN` | `0` | Min seconds between messages from same agent |

Example - limit agents to 5 messages per 10 minutes with 30s cooldown:

```bash
export AGENT_HUB_RATE_LIMIT=true
export AGENT_HUB_RATE_LIMIT_MAX=5
export AGENT_HUB_RATE_LIMIT_WINDOW=600
export AGENT_HUB_RATE_LIMIT_COOLDOWN=30
```

Rate-limited messages are archived with `rateLimited: true` for debugging.

### Coordinator (Optional)

The coordinator is a dedicated OpenCode session that facilitates **initial** agent introductions, then steps back.

Configuration via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_HUB_COORDINATOR` | `true` | Enable the coordinator agent (`true`, `1`, or `yes`) |
| `AGENT_HUB_COORDINATOR_MODEL` | `opencode/claude-opus-4-5` | OpenCode model for the coordinator session |
| `AGENT_HUB_COORDINATOR_DIR` | `~/.agent-hub/coordinator` | Directory used for the coordinator session |

Example - run coordinator on a different model:

```bash
export AGENT_HUB_COORDINATOR_MODEL=opencode/claude-sonnet-4-5
```

## Directory Structure

```
~/.agent-hub/
├── agents/           # Registered agent JSON files
├── messages/         # Pending messages (JSON files)
│   └── archive/      # Processed/expired messages
├── threads/          # Conversation thread tracking
├── metrics.prom      # Prometheus metrics export
└── oriented_sessions.json  # Session orientation cache
```

## Message Format

Messages are JSON files in `~/.agent-hub/messages/`:

```json
{
  "from": "agent-id",
  "to": "target-agent-id",
  "type": "task|question|context|completion|error",
  "content": "Message content here",
  "priority": "normal|urgent|high|low",
  "threadId": "auto-generated-or-provided",
  "timestamp": 1234567890000
}
```

### Message Types

| Type | Purpose |
|------|---------|
| `task` | Request work from another agent |
| `question` | Ask for information |
| `context` | Share context/information |
| `completion` | Report task completion (include "RESOLVED" to close thread) |
| `error` | Report an error |

## Integration with MCP

The daemon works with [agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp) which provides tools for agents to:

- `register_agent` - Register with the hub
- `send_message` - Send messages to other agents
- `get_messages` - Retrieve pending messages
- `sync` - Get all pending work

When the daemon is running, agents don't need to poll - messages are pushed directly into their sessions.

## Metrics

Prometheus-compatible metrics exported to `~/.agent-hub/metrics.prom`:

### Counters

| Metric | Description |
|--------|-------------|
| `agent_hub_messages_total` | Total messages processed |
| `agent_hub_messages_failed_total` | Messages that failed to process |
| `agent_hub_injections_total` | Messages injected into sessions |
| `agent_hub_injections_retried_total` | Injection retries attempted |
| `agent_hub_injections_failed_total` | Injections that failed after retries |
| `agent_hub_sessions_oriented_total` | Sessions that received orientation |
| `agent_hub_agents_auto_created_total` | Agents auto-registered from sessions |
| `agent_hub_gc_runs_total` | Garbage collection runs |
| `agent_hub_gc_sessions_cleaned_total` | Stale sessions cleaned up |
| `agent_hub_gc_agents_cleaned_total` | Stale agents cleaned up |
| `agent_hub_gc_messages_archived_total` | Messages archived during GC |
| `agent_hub_cache_hits_total` | Session cache hits |
| `agent_hub_cache_misses_total` | Session cache misses |

### Gauges

| Metric | Description |
|--------|-------------|
| `agent_hub_active_agents` | Current registered agents |
| `agent_hub_oriented_sessions` | Sessions with active orientation |
| `agent_hub_injection_queue_size` | Pending injections in queue |
| `agent_hub_message_queue_size` | Pending messages in queue |

## Development

```bash
# Clone and setup
git clone https://github.com/xnoto/opencode-agent-hub
cd opencode-agent-hub
uv sync --all-extras

# Run linting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run mypy src/

# Run tests
uv run pytest
```

## Acknowledgments

This project builds on the work of:

- **[OpenCode](https://github.com/anomalyco/opencode)** by [anomalyco](https://github.com/anomalyco) - The AI coding assistant this daemon integrates with
- **[agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp)** by [@gilbarbara](https://github.com/gilbarbara) - The MCP server providing agent communication tools

Thank you for making your work available to the community.

## License

MIT - See [LICENSE](LICENSE) for details.
