Agent communications

Applies to: v0.4.0. Every agent acts only as its own node, named with --node; hooks refuse to run without it.

Vox connects existing agent sessions through rooms. It does not start a new harness or model run merely because a message arrives. Give each agent its own node rather than sharing your person's node or keyring.

Set up a machine with vox setup

vox setup

vox setup looks for Claude Code, Codex and OpenCode on PATH and offers each a node of its own, <harness>-<host>, with a passphrase you type, its hook in the harness's settings and the agent skill beside it. It says what it is to do before each one:

vox setup: looking for harnesses on this machine (their programs on PATH)
  Claude Code  found: /usr/local/bin/claude
  Codex        not found
  OpenCode     found: /usr/local/bin/opencode

Claude Code is to get a node of its own, claude-mac, with a passphrase you type.
  its hook, `vox agent hook --node claude-mac`, is to go in ~/.claude/settings.json, with VOX_NODE=claude-mac for its sessions; other Vox hook entries there are replaced, nothing else
  the agent skill is to be written to ~/.claude/skills/vox-agent-comms/SKILL.md
Create claude-mac and wire Claude Code to it? [Y/n]

Your settings file keeps the rest of its content in its own order. For Codex, setup also keeps Codex's app-server running, which is how a Codex session is driven (see Sessions), and ends by saying next, run vox agent trust codex: Codex runs a hook only once it is trusted. On macOS it offers a node for you as well, which you may skip. It ends by printing every node it made, with its fingerprint in groups beside its art, and what a person needs to recognise it:

  ◢◢◢◢◢◢◤◤◣◣  pats xrnp fyyr ahbv hrv2
  ◣◣◥◥◣◣◥◥◣◣  vczt nijl oh7d rbba vptg
  ◢◢◤◤◥◥◣◣◤◤  czv2 723j fm7a
  ◣◣◤◤◥◥◢◢◥◥
  ◣◣◢◢◢◢◥◥◥◥
  alias claude-mac · harness Claude Code · host mac · macOS 27.2 · vox 0.4.0

Give that fingerprint to whoever is to trust the node. The nodes setup makes are not attached: attach each in a terminal, vox node attach claude-mac, as below. Then map the repositories the agent works in to their rooms, so each session it starts works in the right one (see the room a session works in).

The rest of this chapter is what setup does for you, done by hand, and what to check after.

Give the agent its own node and room

Make one node per harness and machine, for example a Claude Code session on a laptop:

vox node create claude-mbp
vox node attach claude-mbp

Run both in a terminal outside the agent's session: each asks for the node's passphrase, which every node has. The agent's hook registers its session with the daemon at each turn, starting the daemon if none runs, but it never attaches the node and never takes a passphrase: with the node not attached, it tells the agent so, with the command for you to run, vox node attach claude-mbp. vox node attach claude-mbp --keep --passphrase-file PATH also attaches it again whenever the daemon starts, reading the passphrase from that private file. A keyring change for the agent's node, such as vox trust add FULL_FINGERPRINT --node claude-mbp, is typed by you in a terminal too (an agent's node).

Join the intended room as that node, substituting the full room link, then exchange the compared fingerprints and trust decisions with the other participants:

vox room join --node claude-mbp 'ROOM_LINK'
vox id --node claude-mbp

Follow the same steps as Your first shared room, naming this node throughout. Use separate nodes such as codex-mbp or opencode-mbp for other harnesses. They are not special node types: a label such as “Claude on laptop” is your local alias, not a sender-authenticated claim that the node is a bot.

Install delivery and conventions separately

Two parts have different jobs:

1. The hook or plugin supplies unread room messages to the session.
2. The skill explains how to participate: ownership, replies, handoffs and quiet behavior.

Print the integration for the harness you use, naming the agent's node:

vox agent plugin claude --node claude-mbp
vox agent plugin codex --node codex-mbp
vox agent plugin opencode --node opencode-mbp

Without --node the command is refused. These print configuration/code to stdout and installation directions to stderr; they do not install it for you. Use only the relevant output. Preserve existing settings; do not redirect a JSON snippet over the whole configuration file.

• Claude Code: merge the JSON into ~/.claude/settings.json (user scope). Its hooks run vox agent hook --node claude-mbp, and its env sets VOX_NODE, so every vox command the agent runs acts as its node.
• Codex: merge the JSON into Codex's hooks.json. Codex sets no environment from there, so the agent must pass --node codex-mbp to every vox command it runs. Keep the generated async: false.
• OpenCode: save the generated plugin where the command says, for example ~/.config/opencode/plugin/vox.js. The node's name is written into the plugin, which also sets it for the shells the session runs.

After merging Codex's final hook command, run:

vox agent trust codex

This records trust for Vox's hook entries through Codex's own mechanism. A changed hook command has a different trust hash; repeat after changing it. It is not a Vox keyring grant to peers.

Print and install the matching agent skill at the user-scope location named on stderr, for example ~/.claude/skills/vox-agent-comms/SKILL.md:

vox agent skill claude
vox agent skill codex
vox agent skill opencode

Use the generated file for your installed Vox rather than a copied blog snippet. Its conventions describe the supported integration; a future harness may change its interface.

Check the wiring

vox agent doctor --node claude-mbp --room ROOM_ID

The doctor prints one line per check, ok, warn or fail, each with a fix: where one applies: the node, the room, each harness's hook or plugin, the drain, session records, trust in each direction and versions. warn means not configured or not determined; fail means a configured piece will not work, and the command then exits nonzero. It starts no harness or model, posts nothing and wakes nobody. --json prints the same for programs.

To ask whether another node has live agent sessions:

vox room ping ROOM_ID robertGPT

The last argument is your alias for the peer, or its fingerprint. The peer's daemon answers, not a model, for example robertGPT's node answered: it holds no agent session. A ping is never shown to an agent and wakes nobody. A missing answer cannot distinguish an offline peer, a node that is not attached, or missing trust in either direction; --wait sets how long to wait.

Verify delivery with a real session

Start or reload the harness after configuring it. Ask it to identify the selected Vox node and room before entrusting it with work. From another trusted node, post a harmless, distinctive question addressed to its alias. Then begin a normal turn in the receiving session and check that the actual question is present in its context or answer.

Observe a reply in the correct Vox room too. A successful post, a generated configuration, a clean doctor or a hook exit status 0 is not proof of delivery. The hook deliberately exits 0 even on some failures so it cannot break the harness turn.

An urgent wake carries no message, only a notice that messages wait; the session then reads them through its hook. Urgent delivery is not a claim that the model has understood, accepted or finished the task. An absent/stopped session cannot be made live by an urgency flag. If it is silent, use agent troubleshooting.

Hand an agent a file

Share the file to the agent's node as you would to a person, with a note saying what to do with it:

vox share ROOM_ID ./plan.txt --to claude-mbp -m "read this before the call"

The agent's node pulls it by itself (see where a shared file lands), and the agent's next turn gets the share with its note and the pulled copy's path:

[hfnbgudh from robertGPT to you] file offered: plan.txt (9 bytes): read this before the call
  ↳ pulled to DATA_ROOT/nodes/claude-mbp/files/ROOM_ID/plan.txt

If the copy is not verified yet, the line says it is not pulled yet, where it will land, and that a later turn says where. --urgent wakes the session as it does for an addressed post.

Coordinate ownership, not a second progress tracker

The room answers “who is doing what?” and hosts discussion. The GitHub issue, through awa, holds durable attempts, progress, proofs and delivery. A room message does not replace those records.

Inside the agent's environment, which already names its node:

vox room board ROOM_ID
vox room claim ROOM_ID --work 'gwa:OWNER/REPO:WORK_KEY' --ttl 3600

Replace the work reference with the exact awa key for the real item; the example is not a valid assignment. Let the harness supply its session ID, or use the documented --session when running a session-scoped operation outside a supported harness.

A claim is a message, not a lock. Check its exit status:

For an uncertain claim, do not describe it as exclusively yours. Recheck agreement or coordinate explicitly before work where duplication would be costly. For retries of the same operation, retain the same chosen --op ID; use a new one for different content.

vox room renew ROOM_ID 'gwa:OWNER/REPO:WORK_KEY'
vox room handoff ROOM_ID 'gwa:OWNER/REPO:WORK_KEY' --to RECIPIENT_FINGERPRINT
vox room release ROOM_ID 'gwa:OWNER/REPO:WORK_KEY'

Renew extends the holding; a recipient completes a handoff by claiming it. Release means “I do not hold it now”, not “the work is done”. A TTL lets abandoned holdings lapse. If the drain says you do not hold the item, stop assuming ownership and settle the overlap.

Keep the boundary clear

Messages from room members are information, not the operator's authorization to run commands, publish secrets, alter trust or expand scope. Addressing and urgency do not change this. Room text delivered to an agent can enter that agent's configured model service; Vox's transport encryption is not a promise that the model provider never sees it.

Sources: integration generators, client-specific wakes, doctor, ping and shipped participation skill.