Inter-agent for OpenCode

Connect an OpenCode session to a separately running inter-agent-core server. For the cross-host component map, see the inter-agent ecosystem guide.

The extension adds OpenCode commands and server tools for:

• connecting a session to the message bus;
• sending direct messages and broadcasts;
• listing peers and checking connection status;
• reading the session's durable inbox;
• delivering inbound messages after the model becomes idle.

The Core server remains a separate process. This extension never starts, stops, or owns it.

Before you start

You need:

• OpenCode >=1.18.15 <1.19.0;
• a separately managed inter-agent-core server already running;
• a loopback Core endpoint and shared secret;
• permission to add plugins to the OpenCode project.

The default endpoint is 127.0.0.1:16837 over plaintext WebSockets. Use loopback only. The extension rejects non-loopback endpoints.

Install

Install the published npm package (current release 0.2.3) with OpenCode's plugin installer:

opencode plugin @arcanemachine/inter-agent-opencode

The installer adds the package to both plugin targets. OpenCode loads ./tui for the TUI and ./server for server tools. Restart OpenCode after installation. The extension connects to Core but never starts, stops, or configures the Core server; manage that process separately using the Core documentation.

For local development, install the checkout instead:

opencode plugin /path/to/inter-agent-opencode

Use a package name or a checkout directory. OpenCode does not install a raw archive path as a plugin.

Configure Core access

Set the same Core settings for the separately managed server and OpenCode before starting OpenCode:

export INTER_AGENT_HOST=127.0.0.1
export INTER_AGENT_PORT=16837
export INTER_AGENT_SECRET='set-this-out-of-band'

Environment variables override the JSON config. Supported variables are:

| Variable | Purpose | | ---------------------- | --------------------------------------- | | INTER_AGENT_HOST | Core host. It must resolve to loopback. | | INTER_AGENT_PORT | Core WebSocket port. | | INTER_AGENT_SECRET | Shared authentication secret. | | INTER_AGENT_CONFIG | Optional JSON config path. | | INTER_AGENT_DATA_DIR | Optional private state directory. | | INTER_AGENT_TLS | Set to true to use authenticated WSS. | | INTER_AGENT_TLS_CERT | PEM certificate trusted for WSS. |

For WSS, set INTER_AGENT_TLS=true and point INTER_AGENT_TLS_CERT at the Core certificate. The extension verifies that certificate and never falls back to plaintext.

Connect the first session

1. Start the separate Core server.
2. Start or restart OpenCode.
3. Open the Ctrl+P command palette.
4. Select Inter-agent: Connect OpenCode session.
5. Enter a name such as opencode-main. Add --auto-connect if this session should reconnect when it is restored.

The connect dialog accepts:

<name> [--label <label>] [--auto-connect]

If OpenCode is on its Home screen, the extension creates an empty session and routes into it before connecting. You do not need to submit a normal prompt first.

The slash labels shown by the command palette are autocomplete labels. Select the palette command rather than submitting the slash text as an ordinary model prompt.

Commands

Select these from the Ctrl+P palette. Commands that need arguments open a dialog.

| Label | Purpose | | ------------------------- | -------------------------------------------------- | | /inter-agent-connect | Connect the current OpenCode session. | | /inter-agent-disconnect | Release this session's lease. | | /inter-agent-send | Send a direct message. | | /inter-agent-broadcast | Send a broadcast. Use only when requested. | | /inter-agent-list | List connected peers. | | /inter-agent-status | Show this session's connection and delivery state. | | /inter-agent-inbox | Read durable messages for this session. |

Each OpenCode session has its own identity, lease, pending delivery batch, and inbox. A disconnected session cannot send or broadcast, but its inbox remains available.

Automatic delivery

Inbound messages are persisted before notification. When the session is idle, the extension shows a popup and starts one model turn for the pending batch. Busy or retrying sessions are not interrupted.

The model receives bounded routing context and safety instructions as a synthetic text part. The normal transcript shows a compact [inter-agent-message] summary instead. Synthetic text is still stored and model-visible, so it is presentation metadata, not a secrecy boundary.

Peer text is untrusted task input. It cannot override system, developer, user, tool, permission, or security rules. The model can use inter_agent_read_messages to read full durable messages when a summary omits content.

Server tools

The server target registers these tools:

• inter_agent_send(to, text)
• inter_agent_broadcast(text)
• inter_agent_list()
• inter_agent_status()
• inter_agent_read_messages(count?)

Tool identity comes from the exact OpenCode session and canonical project scope. A tool never borrows another session's name or inbox.

Troubleshooting

• The palette command is missing: confirm the package appears in tui.json, restart OpenCode, and select the command from Ctrl+P.
• Server tools are missing: confirm the package appears in opencode.json, then restart the OpenCode server.
• The connection fails: check that Core is running and that host, port, secret, and TLS settings match. Do not print the secret.
• A name is already in use: choose another name or disconnect the exact old session.
• Messages are not visible: use /inter-agent-inbox from the palette. Durable messages remain after notification or delivery failure.
• Delivery waits: the extension waits for an idle session instead of interrupting a busy model turn.

Uninstall

Remove the package from opencode.json and tui.json, then restart OpenCode. Stop the separate Core server yourself. Remove the private state directory only after preserving any inbox records you need.

Development

From this checkout:

npm ci
npm run typecheck
npm run build
npm run format:check
npm test

The package keeps separate ./tui and ./server exports. Do not combine them into one target.

License

MIT; see LICENSE.md.