---
title: Teams of agents
description: 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.
section: automation
order: 100
audience: [user, operator, agent]
sources: [cli/src/fleet.ts, cli/src/handoff.ts, cli/src/team-handoff.ts, cli/src/board.ts, cli/src/board-health.ts, packages/harness/src/extensions/board.ts, cli/src/keys.ts, docs/board.md]
features: [automation.fleet, automation.handoff, automation.board]
---

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 {#fleet}

```bash
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 {#handoff}

Two kinds of handoff share the command.

### To a teammate, through Venom Cloud {#handoff-team}

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:

```bash
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 {#handoff-host}

```bash
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) {#board-tool}

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) {#board}

`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. |

```bash
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.

## Related

- [The inbox](/docs/automation/inbox.md)
- [Contract-first work](/docs/automation/contract-first.md) shows how the board splits cross-component work.
