Skip to content

Troubleshooting

Jump to bottom
jkrandom edited this page Aug 12, 2026 · 1 revision

Troubleshooting

/peers shows no other sessions

  1. Check both instances have the plugin loaded: run /peers-name in each — it should show a name.
  2. Check the registry directory: 
    ls $XDG_DATA_HOME/opencode-plugin-peers/peers.d/*.json
    Files should exist with recent modification times.
  3. Check process liveness: the pid in each registry file must match a running process: 
    # Check if a PID is alive
ps -p <pid>
  4. Check stale window: if a process's heartbeat is older than staleMs (30s default), it appears offline. Ensure heartbeats are running (check heartbeatAt in the registry file).

/peers shows too many sessions (historical sessions)

This was fixed in 0.2.1 (display-layer collapse). Ensure you're running >= 0.2.1:

grep PLUGIN_VERSION ~/.cache/opencode/packages/opencode-plugin-peers@latest/node_modules/opencode-plugin-peers/dist/index.js

If stale, update the cache:

cd ~/.cache/opencode/packages/opencode-plugin-peers@latest
npm install opencode-plugin-peers@latest

Then restart opencode.

Same-directory instances have the same name

Fixed in 0.2.2 — the default name now includes a hex suffix (<dir>-<hex4>). Ensure you're running >= 0.2.2. If you set an explicit name or used /peers-name, the suffix is not added — use distinct names or let the default work.

/peers list jitters / reorders between invocations

Fixed in 0.2.1 — entries are now deterministically sorted by (startedAt, endpointId). Ensure you're running >= 0.2.1.

send_message returns "ambiguous"

Two or more peers share the same display name. Either:

  • Use /peers-name to give each a unique name, or
  • Target by endpoint ID: send_message(to: "session-abc123", message: "...")

Find endpoint IDs via the list_agents tool.

Messages not delivered (status "queued")

  • The target session may be unreachable. Check if the target's inbox listener is running.
  • Check the spool directory: spool/<endpoint>/queued/*.json — undelivered messages persist here.
  • The fallback sweep (sweepMs, default 15s) will retry periodically.

Held messages not appearing in /peers-inbox

  • Verify inboundPolicy is "hold" (or "auto" with cross-directory sender).
  • Held messages expire after heldExpiryMs (default 5 min). If expired, they produce a final expired ACK.
  • Check the held spool: spool/<endpoint>/held/*.json.

Permission auto-approval not working

  1. Check peerPermissions: must be "allow" (default).
  2. Check if the request is in a protected category: credentials, shell startup files, AGENTS.md, etc. are never auto-approved.
  3. Check existing OpenCode deny rules: native deny rules always win over plugin auto-approval.
  4. opencode version: the plugin uses bus events (permission.asked / permission.v2.asked), not the SDK's permission.ask hook (which opencode 1.18 does not invoke).

Plugin not loading after publish/update

The opencode package cache at ~/.cache/opencode/packages/opencode-plugin-peers@latest/ may have a stale pin. opencode plugin -g <name> does NOT refresh it:

cd ~/.cache/opencode/packages/opencode-plugin-peers@latest
npm install opencode-plugin-peers@latest

Also check if there's a ~/opencode-plugin-peers/ directory with its own pin that needs updating.

TUI Single-Enter not working

  1. Ensure the plugin is in ~/.config/opencode/tui.json (separate from opencode.json).
  2. Older opencode versions ignore the TUI entry — commands still work with default two-Enter behavior.
  3. Commands with arguments (/peers-name frontend) always use normal submit.

Report an issue

Open a GitHub issue with:

  • Plugin version (/peers-name output or PLUGIN_VERSION in dist)
  • opencode version (opencode --version)
  • OS and platform
  • Relevant log output

Clone this wiki locally