Configuration Guide

Configuration Guide

Basic setup

Install globally:

opencode plugin -g opencode-plugin-peers

Or add to opencode.json:

{
  "plugin": ["opencode-plugin-peers"]
}

Tuple form (with options)

{
  "plugin": [
    ["opencode-plugin-peers", { "inboundPolicy": "hold", "name": "frontend" }]
  ]
}

All options

Option	Default	Description
inboundPolicy	"accept"	accept delivers immediately; auto accepts same-directory peers and holds cross-directory; hold parks for review; refuse rejects
peerPermissions	"allow"	allow auto-approves ordinary tool requests; ask leaves native prompts; deny rejects
name	<dir>-<hex4>	Display name. Default: directory basename + hex suffix. Explicit value replaces default
storageDir	$XDG_DATA_HOME/opencode-plugin-peers	Registry and spool location
heartbeatMs	10000	Registry heartbeat interval
staleMs	30000	Peer offline threshold (heartbeat age)
maxQueue	50	Queued (accepted, undelivered) cap per endpoint
maxHeld	100	Held inbox cap
heldExpiryMs	300000	Held message expiry (5 min); expiry → expired ACK
maxMessageBytes	8192	Per-message size limit
sendRatePerMin	10	Outbound rate limit per peer
recvRatePerMin	20	Inbound rate limit per sender
sweepMs	15000	Fallback delivery/ACK sweep interval

Recommended setups

Trusted team workstation (default)

["opencode-plugin-peers"]

• inboundPolicy: "accept" — messages delivered immediately
• peerPermissions: "allow" — peer-triggered tool calls auto-approved
• Best for: solo developer with multiple opencode windows in the same trust environment

Review before delivery

["opencode-plugin-peers", { "inboundPolicy": "hold" }]

• Messages park in /peers-inbox for manual review
• Best for: shared workstation, untrusted peers, or sensitive codebase

Cross-directory boundary

["opencode-plugin-peers", { "inboundPolicy": "auto" }]

• Same-directory peers: accepted immediately
• Cross-directory peers: held for review
• Best for: monorepo with trusted inner loops but cautious about external directories

Lockdown

["opencode-plugin-peers", { "inboundPolicy": "refuse", "peerPermissions": "deny" }]

• All inbound messages refused
• No auto-approved permissions
• Best for: CI/CD or production environments where peer messaging should be disabled

Sensitive project (ask mode)

["opencode-plugin-peers", { "peerPermissions": "ask" }]

• Messages still delivered immediately
• Tool calls from peer-triggered turns get native permission prompts
• Best for: collaborative but cautious — you want to review what peers' agents do

TUI configuration

For Single-Enter command execution, also add to ~/.config/opencode/tui.json:

{
  "plugin": ["opencode-plugin-peers"]
}

Without this, commands still work but require the default two-Enter behavior.

Local development

npm install && npm run build
ln -sf "$PWD/dist/index.js" ~/.config/opencode/plugins/opencode-plugin-peers.js