Skip to content
Docs menu

venom-board, GitHub issues as an agent control plane

Run a GitHub issue board where agents file ranked proposals, an owner approves with labels, and agents build, gate and merge what was approved.

View .md

venom-board is a Claude Code plugin in the venom repository (.claude/plugins/venom-board). It runs GitHub issues as the control plane for coding agents: agents file ranked proposals, the owner decides with a label, and agents build, gate and merge what was approved. It is an example of running agents against a repository's own backlog, and it loads in Claude Code (and venom, as a Claude Code plugin).

Labels

Label Meaning
[Rnn] in the title rank; work top down within a priority
P0 to P3 priority
area:<component> component
status:proposal waiting on the owner
status:approved build it
status:iterate the owner wants changes (in a comment); an agent revises the proposal
status:rejected closed as not planned
status:in-progress, status:needs-review, status:blocked set by agents

Only labels added by an approver count (BOARD_APPROVERS, default the gh user). Agents never add status:approved. Agents read only the body and approvers' comments, through an injection filter: other people's text is dropped and logged, tool-call-shaped text is stripped, and the rest is wrapped as untrusted.

Skills

  • /venom-board:board-suggest [loop] [count] files new proposals in the board format, each borrowing a pattern from another field with a cited source. It stops while 150 proposals wait.
  • /venom-board:board-work [loop|once] [build|iterate|triage #N] takes the best approved item, builds it with subagents, gates it, squash-merges it and closes the issue. It also revises iterate items and triages issues the owner files by hand.

Running it unattended

board.sh watch polls with plain gh (no model cost) every 10 minutes and starts a headless worker in its own worktree only when there is work.

.claude/plugins/venom-board/scripts/board.sh watch
Variable Default What
BOARD_MAX_WORKERS 2 workers at once
BOARD_MAX_RUNS_PER_DAY 12 runs per day
BOARD_BUDGET_USD 10 cap per run
BOARD_SUGGEST_HOURS 6 hours between suggest passes
BOARD_PROPOSAL_CAP 150 no new proposals while this many wait
BOARD_REBASE_HOURS 1 hours between rebases of behind or conflicting board PRs (only append-only conflicts are resolved)

Logs go to ~/.venom/board/logs/<issue>.log and ~/.venom/board/watch.log. board.sh health [--json] [--days N] reports queue depth, claims, time per issue, gate pass rate and the merge queue.

venom's own board command (venom board, the /board notes) is a separate feature, documented with automation.