Why Maggie? · Screenshots · Quick start · Build from source · Configuration · Deployment · Development · Security

---

Maggie: a fast web UI for Beads issue tracking.

Maggie is a single Go binary that serves a web UI over Beads, the bd issue tracker.

We built it at Mulga to manage Spinifex, the control plane of our AWS-compatible stack for bare-metal, edge and on-premise deployments. Its beads span several repositories, and that got hard to read in a terminal. Nothing here is specific to our stack — it works on any repository with a .beads/ directory.

Why Maggie?

bd is complete but text-only, and some questions are far easier to answer visually — what is blocked on what, which epic is stalling, where the work has piled up.

• No second source of truth. Every read and write goes through bd, so validation, IDs, history and hooks behave exactly as they do on the command line. The server keeps no store of its own, which means nothing to back up, migrate or keep in sync.
• Works on the repo you already have. Point MAGGIE_BEADS_DIR at any checkout with a .beads/ directory.
• Filtering that composes. Text, id globs, priority, type, assignee, label and status, applied together rather than one at a time. One filter bar drives every view, and the filters live in the URL, so a view is a link you can share.
• A dependency graph. Force-directed, blockers and parent/child drawn differently, optionally clustered by label. It shows what is holding a bead up in a way a list cannot.

Screenshots

Dashboard

Table

Board

Graph

Quick Start

The container bundles maggie and the bd CLI, so there is nothing to install and no database to stand up. Point it at any checkout that already has a .beads/ directory:

cd /path/to/your/repo

docker run --rm -p 8088:8088 \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/.beads:/repo/.beads" \
  ghcr.io/mulgadc/maggie:latest

Then open http://localhost:8088.

Podman works with the same command:

podman run --rm -p 8088:8088 -v "$PWD/.beads:/repo/.beads:Z" ghcr.io/mulgadc/maggie:latest

Build From Source

Prerequisites

Tool	Version	Notes
Go	1.27+	to build the binary
Node.js	24.14.0	pinned in frontend/.nvmrc
pnpm	12.3.4	pinned via packageManager in frontend/package.json
bd	1.3.1	the Beads CLI, on PATH

git clone https://github.com/mulgadc/maggie.git
cd maggie
make build
MAGGIE_BEADS_DIR=/path/to/your/repo ./maggie

The compiled SPA is embedded with go:embed, so the result is one self-contained binary with no runtime assets to ship.

To build the container image instead:

make docker-build

Configuration

All configuration is environment variables. There is no config file.

Var	Default	Description
MAGGIE_ADDR	:8088	Listen address
MAGGIE_BEADS_DIR	.	Working directory containing .beads/
MAGGIE_BD_BIN	bd	Path to the bd binary
MAGGIE_ACTORS	—	Comma-separated identity roster for the edit picker
MAGGIE_LOG_LEVEL	info	debug, info, warn or error

Deployment

The image bundles maggie, bd and dolt. The entrypoint's first argument picks a role, so one image covers both deployment modes.

Mode 1 — one person, one checkout (default)

What the Quick Start above does. bd runs inside the container against the embedded Dolt engine in your mounted .beads/ directory. No server, no seeding, nothing to back up beyond the directory itself.

Use it for your own repo, a demo, or a read-only view of someone's tracker.

Both your host bd and the container can use the same .beads/ — each bd invocation is short-lived and takes the lock only while it runs, so concurrent reads are fine. Avoid writing from both at the same moment.

Mode 2 — a shared tracker for a team

One Dolt SQL server holds the database and everyone's bd connects to it as a client, with maggie as the web view onto the same server. This is what the compose stack builds:

mkdir -p snapshot
cp /path/to/your/repo/.beads/issues.jsonl snapshot/issues.jsonl

make docker-build
make docker-seed        # imports the snapshot into the dolt volume
make docker-up          # http://localhost:8088

make docker-refresh     # later: stop dolt -> re-seed -> start dolt

Setting this up for a team — client onboarding, accounts and grants, exposing the port safely, backups — is in docs/deployment.md.

Development

make run    # backend on :8088          (terminal 1)
make dev    # Vite on :3001, proxying /api -> :8088, with hot reload (terminal 2)

Security

Maggie has no authentication. Anyone who can reach the port can read and modify every issue in the store.

Run it on a trusted network, or behind an authenticating reverse proxy that terminates TLS. If you use the compose stack, keep the Dolt port (3307) internal and never publish it.

To report a vulnerability, see SECURITY.md.

Trademarks

Beads is a project by Steve Yegge. Dolt is a trademark of DoltHub, Inc. Maggie is not affiliated with or endorsed by either.

License

Maggie is licensed under the GNU Affero General Public License v3.0 (AGPLv3) license.