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.

Install

uvx beacon-board --help        # run without installing
pipx install beacon-board      # or install it

Quickstart

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

That writes beacon.toml, a tickets/ directory and board.html.

Why the CLI matters

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

Give an agent access to the commands and it can read and update the same backlog you do:

beacon-board list --status Next --json
beacon-board set AB-07 --status Now
beacon-board comment AB-07 "Reproduced on a clean install."

beacon-board agent-docs prints an instruction block to paste into whatever your assistant reads. Nothing here is specific to one tool.

Tickets

One markdown file per ticket, in tickets/.

# AB-07: [Bug] Search drops the last result

**Epic:** [AB-03 Search overhaul](AB-03-epic-search-overhaul.md)
**Assignee:** rae
**Depends on:** None
**Related:** AB-04
**Estimate:** S
**Type:** Bug
**Status:** Next

## Objective

The final match is missing from every result page.

## Acceptance Criteria

- [ ] Searching a mailbox with exactly one match shows it.

## Acceptance Criteria renders as a checklist, so write items as - [ ] and tick them to - [x]. Plain bullets render as prose instead, which is why the section is worth writing consistently. ## Comments holds dated entries, oldest first: - **2026-08-14:** text.

Three levels: the ID prefix groups tickets into apps, **Epic:** groups them within an app, and everything else is a ticket. A ticket whose **Epic:** reads Self is an epic container. With only one prefix in play, the app level disappears from the board.

Configuration

beacon.toml, found by walking up from the working directory. Every key has a default, so the file is optional.

[meta]
name = "My Board"

[[apps]]
prefix = "AB"
label = "My Project"

[statuses]
columns   = ["Later", "Next", "Now", "Done"]
protected = ["Done"]

[assignees.rae]
label = "rae"
color = "#ffffff"

protected statuses are the ones the CLI refuses to set without --force. Useful when you want an agent to do the work but not to declare it finished.

Commands

Every command takes --help. beacon-board --version prints the version.

Exit codes: 0 ok, 1 usage or runtime error, 2 validation failed, 3 refused by rule. Branch on these rather than on the message text.

Requirements

Python 3.11 or newer. No runtime dependencies.

Contributing

Bug reports and pull requests are welcome on GitHub. To work on it:

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .

See CONTRIBUTING.md for the house rules.

Author

Built by Bojan Gasparovic. More work and writing at zeroemdashes.com.

License

MIT.

Generated boards embed Poppins, DM Sans and Fira Code, all licensed under the SIL Open Font License 1.1. The licence text ships with the package at beacon_board/templates/fonts/OFL.txt.