Skip to content
Docs menu

Teams of agents

See your and your teammates' agents with venom fleet, hand a session to a teammate or another host with venom handoff, coordinate subagents on the shared board, and drive agents from your issue tracker with venom board.

View .md

Tools for more than one agent, or more than one person: a shared view of who is running what, moving a session to someone or somewhere else, a notice board for an agent tree, and an issue tracker as the agents' work queue.

venom fleet

venom fleet            # this repository
venom fleet --all      # every repository of your key group
venom fleet --json     # {"ok":true,"repo":…,"agents":[…]}

Your agents and your teammates' on this repository: who, agent, state (running, waiting, stuck, looping, idle), task, spend and file leases. In the TUI, /fleet shows the same.

It needs Venom Cloud: venom cloud login, or VENOM_CLOUD_URL and VENOM_CLOUD_KEY (a vck_… client key). The repository is the current directory's git remote. While venom runs with Cloud set up, it publishes its agents every 15 seconds (state, a one-line task, spend, leases; never prompts or file contents) and clears them on exit; rows older than 60 seconds are dropped. Without Cloud credentials nothing is published and no network call is made. venom serve publishes its served sessions the same way.

venom handoff

Two kinds of handoff share the command.

To a teammate, through Venom Cloud

In a session, /handoff @alice [message] (or /handoff team:Platform, to everyone holding a key of the Platform key group) drafts a handoff note, lets you edit it, shares the transcript, adds the branch and its diff stats, and sends it to Venom Cloud. Everything sent is redacted first and you confirm it. The teammate picks it up:

venom handoff inbox [--sent] [--json]
venom handoff show <id> [--json]
venom handoff accept <id> [--worktree [<path>]] [--no-launch] [--json]
venom handoff decline <id> [reason]

accept fetches the branch and switches to it (--worktree adds a git worktree instead, needed when your tree has uncommitted changes), then opens a session seeded with the note and a digest of the transcript.

To another venom serve host

venom handoff <session> --to https://build-box.example.com:8790 [--from <url>] [--cwd <root>] [--force] [--attach]
venom handoff --export <session> [--from <url>] -o bundle.vho
venom handoff --import bundle.vho --to <url> [--cwd <root>] [--force] [--attach]

This moves a persisted session between venom serve hosts. The destination restores the session and its uncommitted edits at the same commit; the source turns read-only (its prompts answer 409 lease_lost). --attach joins the session on the destination afterwards. --from defaults to http://127.0.0.1:8790.

Option What it does
--to <url> The destination server.
--from <url> The source server (default http://127.0.0.1:8790).
--cwd <root> Where on the destination to restore it.
--to-token-env <NAME> The env var holding the destination's token (default VENOM_SERVER_TOKEN).
--export / --import Write the bundle to a file (mode 0600) and load it elsewhere, for SSH transport.

The bundle may hold secrets from the transcript and the working tree: use https or an SSH tunnel.

The shared board (for agents)

When a session delegates to subagents, the main agent and its subagents share a notice board through the board tool: short notes under keys, such as finding/failing-test, claim/src/api.ts or decision/db-schema.

Op Arguments What it does
get key One note with its version and writer.
list prefix? Up to 50 notes with an 80-character preview each.
put key, value, version? Without version, only creates a new key; to change one, pass the version you last read.
delete key, version Delete, if the version still matches.

Every write is compare-and-swap, so two agents never overwrite each other silently: a stale write comes back with the current value to merge. Values are up to 4 KB, scrubbed of anything that looks like a secret, and shown to other agents as data, not instructions. The board lives in memory for one agent tree; it touches no file and no network, and the permission engine always allows it. The tool appears in the main agent from its first task call, so a session that never delegates keeps its tool list unchanged.

You can read it in the TUI with /board [prefix] or the leader key ctrl+g b. It also summarises a team's task list (notes under tasks/ whose values start with open:, claimed:, done: or failed:), for example tasks: 1 open, 2 claimed, 3 done, 0 failed.

venom board (issues as the work queue)

venom board makes your issue tracker the agents' control plane: you decide with labels, venom builds. GitHub works through gh and GitLab through glab; nothing else is contacted.

Label (added by an approver) What happens
status:approved watch claims it and starts a worker that builds it, opens a pull request and ships it.
status:iterate A worker rewrites the issue body from your comments; then it is a proposal again.
status:rejected Closed as not planned.
venom board watch                     # zero-token loop; a worker starts only when work exists
venom board queue                     # the next item, or nothing
venom board status                    # issues per status label, live workers
venom board health [--json] [--days 7]
venom board comments 370              # what a worker may read: the body plus approvers' comments
venom board claim|done|block|revised …
venom board gate-queue [--json]
venom board prompt build 370          # the prompt a worker would get
Option Env var Default What it does
--approvers a,b VENOM_BOARD_APPROVERS the forge's logged-in user Whose labels count. Other people's issue text never reaches a worker.
--repo owner/name VENOM_BOARD_REPO the origin remote The repository.
--forge github|gitlab VENOM_BOARD_FORGE from the remote The forge.
--poll <s> VENOM_BOARD_POLL 600 Seconds between watch ticks.
--max-workers <n> 2 Workers at once.
--max-runs-per-day <n> 12 Worker runs per day.
--model <id> The workers' model.
--once One tick, for cron.
VENOM_BOARD_WORKER venom -p Replaces the worker command; the prompt is the last argument.
VENOM_BOARD_STATE ~/.venom/board Logs, pid files and the run counter.

Order: iterations first, then priority P0 to P3, then rank. An issue whose "Depends on" issues are open waits. A claim with no update for 8 hours and no live worker is blocked by the sweep each tick. The board never merges anything itself; the worker ships through your merge gate.

venom serve --board [--board-poll 600] runs the same loop inside the server. Each tick is a few gh or glab calls and no model request. GET /v1/board serves the health report (cached a minute) for the console's Board page.