opencode-agent-hub 0.4.0

Multi-agent coordination daemon and tools for OpenCode

opencode-agent-hub

Multi-agent coordination daemon and tools for 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 to control costs.

Table of Contents

• Features
• How It Works
  • Session Discovery
  • Message Flow
  • The Relay Server
  • Coordination Flow
  • Push Model (No Polling Required by Agents)
  • Session Lifecycle
  • Known Issues
    • Injected Messages Not Visible in TUI
    • TUI May Show Continued Processing After Response
    • Orientation Messages May Trigger Security Heuristics
  • Coordination Test Results (Jan 2026)
• Architecture
• Prerequisites
• Quickstart
• Installation
  • Homebrew (macOS)
  • uv (PyPI)
  • pipx (PyPI)
  • From source
• Running as a Service
  • macOS (launchd)
  • Linux (systemd)
• Usage
  • Start the daemon
  • Monitor with the dashboard
  • Run as standalone scripts (uv)
• Configuration
  • Rate Limiting (Optional)
  • Coordinator (Optional)
• Directory Structure
• Message Format
• Integration with MCP
• Metrics
• Development
• Acknowledgments
• 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

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 by @gilbarbara to be configured in OpenCode. This MCP server provides the tools agents use to send messages.

The daemon will fail to start if agent-hub MCP is not configured. This is intentional - without it, agents cannot communicate.

Find your OpenCode config location

opencode debug paths
# Look for the "config" line, e.g.: config /home/user/.config/opencode

Add agent-hub MCP to your config

Edit opencode.json in your config directory:

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

Verify configuration

opencode mcp list
# Should show: ✓ agent-hub connected

Restart OpenCode after adding the configuration.

Quickstart

1. Install (pick one):

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

agent-hub-daemon

3. Monitor with the dashboard:

agent-hub-watch

4. (Optional) Run as a service (see Running as a Service).

Installation

Homebrew (macOS)

# 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):

# 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)

uv tool install opencode-agent-hub

pipx (PyPI)

pipx install opencode-agent-hub

From source

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

Running as a Service

macOS (launchd)

# 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)

# 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

agent-hub-daemon

The daemon will:

1. Verify agent-hub MCP is configured (exits with instructions if not)
2. Start an OpenCode hub server on port 4096 (if not already running)
3. Watch ~/.agent-hub/messages/ for new message files
4. Auto-register agents for any OpenCode session it discovers
5. Inject messages into the appropriate sessions

Note: If agent-hub MCP is not configured, the daemon will exit immediately with clear instructions on how to fix it. See Prerequisites.

Monitor with the dashboard

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:

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

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:

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/:

{
  "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 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

# 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 by anomalyco - The AI coding assistant this daemon integrates with
• agent-hub-mcp by @gilbarbara - The MCP server providing agent communication tools

Thank you for making your work available to the community.

License

MIT - See LICENSE for details.