opencode-agent-hub

Multi-agent coordination for OpenCode. Lets multiple AI agents in separate OpenCode sessions talk to each other.

Warning: This enables autonomous agent-to-agent communication which triggers LLM API calls. Use at your own risk. Consider enabling rate limiting to control costs.

Demo

841BD6D3-4257-4FFA-9194-0814974B5630-preview2.mp4

How It Works

The daemon starts an OpenCode hub server (opencode serve --port 4096) and discovers sessions by polling OpenCode's shared SQLite database
A coordinator session facilitates introductions between new agents, then steps back
Agents communicate by writing JSON files to ~/.agent-hub/messages/ via the agent-hub-mcp tools
The daemon watches for new message files, looks up the target agent's session, and injects the message via prompt_async — agents don't poll, they get woken up

Known Limitations

Injected messages not visible in TUI — agent-to-agent messages work but users can't see them in the conversation. Upstream issue: opencode#8564. Use agent-hub-watch to monitor.
TUI spinner after response — the TUI may briefly show "thinking" after an agent finishes responding to an injection. Visual only, no extra token consumption.
Orientation may trigger security heuristics — some models (particularly Claude) may flag orientation messages as prompt injections. The agent still has MCP tools and can collaborate, just without orientation context.

Prerequisites

agent-hub-mcp must be configured in OpenCode. The daemon will refuse to start without it.

Find your OpenCode config location with opencode debug paths, then add to opencode.json:

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

Verify with opencode mcp list (should show agent-hub connected).

Quickstart

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

# Terminal 1: start the daemon
uv run agent-hub-daemon

# Terminal 2: monitor activity
uv run agent-hub-watch

Installation

Homebrew (macOS)

brew install xnoto/opencode-agent-hub/opencode-agent-hub

Linux Packages

Debian / Ubuntu:

curl -fsSL https://xnoto.github.io/opencode-agent-hub/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/xnoto.gpg
echo "deb [signed-by=/etc/apt/keyrings/xnoto.gpg] https://xnoto.github.io/opencode-agent-hub/apt ./" | sudo tee /etc/apt/sources.list.d/xnoto.list
sudo apt update && sudo apt install opencode-agent-hub

Fedora / RHEL:

sudo curl -o /etc/yum.repos.d/xnoto.repo https://xnoto.github.io/opencode-agent-hub/xnoto.repo
sudo dnf install opencode-agent-hub

Arch Linux (AUR):

yay -S opencode-agent-hub

See GitHub Releases for direct .deb/.rpm downloads.

uv / pipx (PyPI)

uv tool install opencode-agent-hub
# or
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 (Homebrew)

brew services start opencode-agent-hub
tail -f ~/Library/Logs/agent-hub-daemon.log
brew services stop opencode-agent-hub

Linux (systemd)

agent-hub-daemon --install-service     # install + start
journalctl --user -u agent-hub-daemon -f
systemctl --user stop agent-hub-daemon
agent-hub-daemon --uninstall-service   # remove

If installed via RPM/DEB, a system-wide service file is included — enable with systemctl --user enable --now agent-hub-daemon.

Configuration

Config file: ~/.config/agent-hub-daemon/config.json (all fields optional). Environment variables override config file values.

{
  "hub": {
    "port": 4096,
    "model": "opencode/minimax-m2.5-free"
  },
  "log_level": "INFO",
  "rate_limit": {
    "enabled": false,
    "max_messages_per_window": 100,
    "window_seconds": 3600,
    "cooldown_seconds": 5
  },
  "coordinator": {
    "enabled": true,
    "directory": "~/.agent-hub/coordinator",
    "agents_md": ""
  },
  "agent": { "stale_seconds": 600 },
  "message": { "ttl_seconds": 3600 },
  "poll": { "session_seconds": 5, "gc_seconds": 60, "metrics_seconds": 60 },
  "cache": { "session_ttl_seconds": 5 },
  "injection": { "workers": 3, "retries": 3, "timeout_seconds": 30 },
  "orientation": { "retry_delay_seconds": 30, "retry_max": 5 }
}

Environment Variables

Variable	Default	Description
`OPENCODE_PORT`	`4096`	Hub server port
`AGENT_HUB_MODEL`	`opencode/minimax-m2.5-free`	Hub server default model (`provider/model`)
`AGENT_HUB_DEFAULT_AGENT`	(none)	Agent name for undetectable sessions
`AGENT_HUB_DAEMON_LOG_LEVEL`	`INFO`	Log level
`AGENT_HUB_MESSAGE_TTL_SECONDS`	`3600`	Message TTL (seconds)
`AGENT_HUB_AGENT_STALE_SECONDS`	`600`	Agent stale threshold (seconds)
`AGENT_HUB_SESSION_POLL_SECONDS`	`5`	Session poll interval (seconds)
`AGENT_HUB_GC_INTERVAL_SECONDS`	`60`	GC interval (seconds)
`AGENT_HUB_METRICS_INTERVAL`	`60`	Metrics write interval (seconds)
`AGENT_HUB_SESSION_CACHE_TTL`	`5`	Session cache TTL (seconds)
`AGENT_HUB_INJECTION_WORKERS`	`3`	Injection worker threads
`AGENT_HUB_INJECTION_RETRIES`	`3`	Injection retry attempts
`AGENT_HUB_INJECTION_TIMEOUT`	`30`	Injection timeout (seconds)
`AGENT_HUB_ORIENTATION_RETRY_DELAY`	`30`	Orientation retry delay (seconds)
`AGENT_HUB_ORIENTATION_RETRY_MAX`	`5`	Max orientation retries

Rate Limiting

Variable	Default	Description
`AGENT_HUB_RATE_LIMIT_ENABLED`	`false`	Enable rate limiting
`AGENT_HUB_RATE_LIMIT_MAX_MESSAGES`	`100`	Max messages per agent per window
`AGENT_HUB_RATE_LIMIT_WINDOW_SECONDS`	`3600`	Window size (seconds)
`AGENT_HUB_RATE_LIMIT_COOLDOWN_SECONDS`	`5`	Min seconds between messages

Coordinator

The coordinator is a dedicated OpenCode session that introduces agents to each other. It starts non-blocking and uses the same message pipeline as any other agent.

Variable	Default	Description
`AGENT_HUB_COORDINATOR`	`true`	Enable coordinator
`AGENT_HUB_COORDINATOR_DIR`	`~/.agent-hub/coordinator`	Coordinator working directory
`AGENT_HUB_COORDINATOR_PRESERVE_LOCAL_AGENTS_MD`	`false`	Keep existing AGENTS.md on restart
`AGENT_HUB_COORDINATOR_READY_TIMEOUT`	`60`	Bootstrap ready timeout (seconds)
`AGENT_HUB_COORDINATOR_STRICT_READY`	`false`	Require exact `READY` acknowledgment
`AGENT_HUB_COORDINATOR_BOOTSTRAP_REQUIRED`	`false`	Fail startup if bootstrap times out
`AGENT_HUB_COORDINATOR_AGENTS_MD`	(auto-detect)	Custom AGENTS.md path

The coordinator model is configured in opencode.json within the coordinator directory (default: opencode/minimax-m2.5-free). Custom coordinator instructions (AGENTS.md) are auto-detected from the config directory, package template, or system paths — override with AGENT_HUB_COORDINATOR_AGENTS_MD.

Message Format

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

{
  "from": "agent-id",
  "to": "target-agent-id",
  "type": "message|completion|delivery-status|task|question|context|error",
  "content": "Message content",
  "priority": "normal|urgent",
  "threadId": "auto-generated-or-provided",
  "timestamp": 1234567890000
}

Required fields: from, to, content. Messages are validated with pydantic on receipt; malformed messages are rejected with delivery feedback to the sender.

Directory Structure

~/.agent-hub/
├── agents/                 # Registered agent files
├── messages/               # Pending messages
│   └── archive/            # Processed messages
├── threads/                # Conversation threads
├── metrics.prom            # Prometheus metrics (prometheus_client format)
├── oriented_sessions.json  # Orientation cache
└── session_agents.json     # Session-to-agent mapping

~/.config/agent-hub-daemon/
└── config.json             # Optional config

Development

Install with uv sync --all-extras. Pre-commit hooks enforce linting, formatting, type checking, and tests automatically. See CONTRIBUTING.md for setup and workflow. See AGENTS.md for injection pipeline internals and test-writing conventions.

Acknowledgments

OpenCode by anomalyco
agent-hub-mcp by @gilbarbara

License

AGPL-3.0 - See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 157 Commits
.github/workflows		.github/workflows
contrib		contrib
src/opencode_agent_hub		src/opencode_agent_hub
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

opencode-agent-hub

Demo

How It Works

Known Limitations

Prerequisites

Quickstart

Installation

Homebrew (macOS)

Linux Packages

uv / pipx (PyPI)

From source

Running as a Service

macOS (Homebrew)

Linux (systemd)

Configuration

Environment Variables

Rate Limiting

Coordinator

Message Format

Directory Structure

Development

Acknowledgments

License

About

Uh oh!

Releases 32

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

opencode-agent-hub

Demo

How It Works

Known Limitations

Prerequisites

Quickstart

Installation

Homebrew (macOS)

Linux Packages

uv / pipx (PyPI)

From source

Running as a Service

macOS (Homebrew)

Linux (systemd)

Configuration

Environment Variables

Rate Limiting

Coordinator

Message Format

Directory Structure

Development

Acknowledgments

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 32

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages