Skip to content

Commands Reference

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

Commands Reference

User commands

All commands are registered via the config hook (INJECTED_COMMANDS). They are intercepted in command.execute.before; the result is written inline via consumeCommand.

/peers (alias /list-agents)

Lists other opencode sessions on this machine.

Other Opencode sessions (2):
  [idle]  ·  myapp-a3f2  ·  "Fix login bug"  ·  /Users/you/myapp  ·  started 9m ago
  [busy]  ·  backend-b7e1  ·  "Add unit tests"  ·  /Users/you/backend  ·  started 3m ago

Columns:

  • Status tag: [waiting] (turn running) or [idle]
  • Name (auto-suffixed with hex by default)
  • Session title (LLM-generated summary, omitted when empty)
  • Directory
  • Started time (relative)
  • Queued count (if > 0)

One row per running process (collapsed). Use list_agents tool for per-session detail including endpoint IDs.

/peers-name [name]

Set or show your peer display name.

/peers-name              # show current name
/peers-name frontend     # rename to "frontend"
  • Names must match [A-Za-z0-9 _-], max 32 characters.
  • An explicit name replaces the auto-generated <dir>-<hex> default entirely.
  • Renaming publishes immediately (next heartbeat).

/peers-inbox [action] [id]

Review and manage held messages (when inboundPolicy is "hold").

/peers-inbox              # list held messages
/peers-inbox accept 2     # deliver message #2
/peers-inbox accept all   # deliver all held messages
/peers-inbox drop 1       # discard message #1
/peers-inbox drop all     # discard all

Held messages expire after heldExpiryMs (default 5 minutes). Expiry produces a final expired ACK to the sender.

/peers-outbox

Show outbound message receipts and final delivery ACKs.

Outbox (3 messages):
  #1 → "backend" — receipt: accepted; final: delivered
  #2 → "frontend" — receipt: accepted; final: awaiting ACK
  #3 → "ci-bot" — receipt: accepted; final: refused

Agent tools

list_agents

Discovers same-machine opencode session endpoints. Returns each endpoint's name, ID, directory, session info, and inbound policy.

2 peer(s) online:
- "frontend" (id session-abc123) — /Users/you/frontend — session "Add login form" (sess-xyz) — inbound: accept
- "backend" (id session-def456) — /Users/you/backend — (no active session) — inbound: accept
You are "myapp" (id session-789abc).

Optional parameter: include_offline: true to also list stale/offline entries.

send_message

Sends a plain-text message to a peer.

send_message(to: "frontend", message: "The API contract changed, field is now user_id")
  • to: peer name or endpoint ID (from list_agents)
  • message: plain text only, max 8192 bytes

Returns: delivered, duplicate, queued, held, refused, full, or error. Includes a tracking ID for status lookup.

When a name matches multiple peers, returns an ambiguity error with endpoint IDs — use the ID for exact targeting.

peer_message_status

Query delivery status of a sent message.

peer_message_status(message_id: "msg-abc123")

Returns transport receipt and final ACK status from the durable outbox.

TUI integration

The package ships a TUI entry (exports["./tui"]) that enables Single-Enter execution: when the prompt holds exactly one plugin command (or a prefix uniquely identifying one), Enter runs it immediately instead of opencode's default two-Enter behavior.

Setup: add the plugin to ~/.config/opencode/tui.json:

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

Guards:

  • Dialogs open → falls through to stock bindings
  • Non-session route → falls through
  • Text with arguments → normal submit (preserves argument)
  • Ambiguous prefix → falls through

The handler stays synchronous (keymap treats Promise results as handled).

Clone this wiki locally