Forum

vx forum lets agents show you something richer than terminal text.

forum: review in your browserCopy Anchor Link

vx forum .vexillum/forum/plan.html

Agents write their artifacts to .vexillum/forum/ in the project. vx init adds a .vexillum/.gitignore that keeps that folder out of git; any path you pass on the command line still works.

Serves an HTML file the agent wrote to your browser and carries your feedback back to it. One local server per user runs on 127.0.0.1 and stops itself when nothing is connected. You can chat, queue messages, fill in decision forms and annotate elements, then send it all to the agent. A Mermaid diagram becomes an editable whiteboard.

On the agent's side:

Sessions are identified by the file's absolute path. forum is built into the binary: no Node, no npx, no network.

The server stays putCopy Anchor Link

The server tries hard not to move or disappear under an open tab:

• Same port. It records the port it bound in ~/.vexillum/forum/last-port and prefers it on the next start (waiting a few seconds for the previous server to release it), so an open tab keeps working. Only if that port stays taken by something else does it fall back to a free one and record that.
• No replacing a server in use. After you upgrade vexillum, a running server may come from an older build. It is replaced by the new build only when it has no open session, no connected tab and no waiting poll. Otherwise the new vx reuses it when its protocol is compatible, and stops with an error telling you what to do when it is not (finish or end the sessions and close the tabs, or run vx forum stop). A server too old to report its activity is reused, never stopped.
• Tabs recover on their own. When the server does restart, an open tab shows a reconnecting banner and retries on its own against the same address. Sessions, queued messages and the transcript are restored from disk, and the session link keeps working.

The listener and the inboxCopy Anchor Link

A small background process holds the blocking poll for every session, so it does not die when the agent gets busy: vx forum listen (hidden; vx forum <file> starts it when it is not running, one per user, guarded by a pid lock). It is plain code with no model behind it, so it can only forward. For every prompt you send from a session that was opened inside a vexillum project it:

1. writes the prompt, with every field and the paths of any attached images, to the project's durable inbox (forum-inbox/<session>/<uid>.json, one atomic file per prompt, so a crash or a redelivery never loses or duplicates one),
2. records a forum wake, one per session however many messages arrived,
3. posts one fixed line in the panel ("Received. Forwarded to the commander, who will answer here.") that does not count as an answer,
4. and only then acknowledges the server.

The commander is woken the same way as for soldiers (the Stop hook in Claude Code, the wake extension in Pi, the sentinel posting into the session through OpenCode's API; see Sentinel), with a line like forum session <file>: 2 new messages (ended: false). Run vx forum inbox. It runs vx forum inbox, which prints the unread prompts in the poll's output format (bounded in size, attachments by path only, as data), acts, answers with vx forum reply <file> --reply "..." and confirms with vx forum inbox --ack <uid>.... A prompt is shown again until it is confirmed, so a restarted commander loses nothing. Send & End forwards the final prompts with ended: true; only that authorizes the commander to implement.

The listener tells the browser whether a commander is there ("no commander session is known for the project" otherwise). A commander counts when its Stop hook has a live vx sentinel await, or when the project's commander registry holds a live entry. vx dispatch and vx forum <file> record the herdr pane they were typed in (HERDR_PANE_ID) under the harness herdr reports for it, one entry per harness, so a commander on Pi or OpenCode, which has no Stop hook, is still found. An entry is live while herdr agent get still answers for its pane with the same harness working inside the project; after herdr renumbers its panes the pane is found again by directory, and otherwise the entry counts as absent. A commander with a live Stop hook behaves exactly as before.

A session opened outside any project has no commander to wake: the listener leaves it undelivered and vx forum poll works for it as before. The listener exits by itself when no session is open or every review window is gone, and vx forum stop stops it first.

Several sessions at onceCopy Anchor Link

Every polled session needs a listener, and a poll dies when it delivers feedback, when its background task times out, or when the agent is busy. With several sessions open, some of them can be left with nobody listening. vx forum poll --all fixes it with one listener for all of them:

• It covers every open session (sessions opened while it waits join it), so every panel shows the agent as listening.
• Each call delivers the feedback of one session, the one waiting longest, and prints its session and file so the agent knows which artifact to edit. other_sessions_pending says how many more are waiting; the next call delivers them.
• --reply-to <file> names the session a --reply answers.
• A session that ends while it waits is reported once as ended. no_sessions means none is open. browser_disconnected means every review window is gone.

vx forum poll <file> keeps working for a single session.

A dying poll never loses feedbackCopy Anchor Link

A poll does not consume feedback by returning it. The prompts stay on the server until the command confirms it printed them. If the poll was killed, timed out or lost its output in between, running poll again delivers the same prompts again, marked redelivered: true with the same uids and ahead of anything newer, so the agent can skip what it already applied. This survives a server restart.

What the panel says about your agentCopy Anchor Link

After you press Send to Agent the Agent is working on your feedback overlay stays up until the commander really answers (a vx forum reply), the artifact changes, or you press Stop waiting. The listener's "Received" line and its polling again do not clear it.

The agent's playbook is the forum skill, installed by vx init (full text on Skill: forum).