Command line · Open source

beacon-board

A kanban board backed by markdown files, with a CLI that people and coding agents can both drive.

Tickets are files in a directory. The board is a single static HTML page. There is no server and no database, so the backlog lives in your repository, moves with it, and reviews like code.

Get it on PyPI → Source on GitHub Python 3.11+ · no runtime dependencies · MIT

The board

The beacon-board kanban board with Later, Next, Now and Done columns

One static HTML page, rebuilt from the ticket files on demand.

Install and run

uvx beacon-board --help     # run it
pipx install beacon-board   # or keep it

beacon-board init
beacon-board new --app AB \
  --title "First ticket" --type Task
beacon-board build --open

# AB-07: [Bug] Search drops a result

**Assignee:** rae
**Type:** Bug
**Status:** Next

## Objective

The final match is missing from
every result page.

Why it exists

Agents

A backlog an agent can drive

Coding agents are good at writing markdown and bad at remembering which ID comes next. The CLI allocates IDs atomically, refuses malformed tickets at creation, and reports problems instead of silently dropping files.

Guardrails

Protected statuses

Mark a column protected and the CLI refuses to set it without --force. Useful when you want an agent to do the work but not to declare it finished.

Structure

Three levels, no ceremony

The ID prefix groups tickets into apps, the epic field groups them within an app, and everything else is a ticket. With one prefix in play, the app level disappears from the board.

Scripting

Exit codes you can branch on

0 ok, 1 usage or runtime error, 2 validation failed, 3 refused by rule. list --json gives machine-readable output, so pipelines never parse message text.

Where it came from

beacon-board started as Beacon, the private ticket store behind everything else on this page. Bouncer, FLY, JUMP and LoadBear were all built against it, with the agents reading and writing the same files I did. It was extracted and published once it had earned the trust.

Run beacon-board agent-docs to print an instruction block to paste into whatever your assistant reads. Nothing in it is specific to one tool.