fancybeans

fancybeans turns a beans work tree into a single, self-contained HTML page displaying the work-item hierarchy, with status, priorities, blocking links, per-milestone progress, search, and every bean's full spec. Use it instead of beans list / beans tui when you want to see a project at a glance, or share it with non-engineers.

Install

You need the beans CLI on your PATH. Get fancybeans one of two ways:

With Node — if you have Node 18+, it's a single ~50 KB file:

mkdir -p ~/tools
curl -fsSL https://raw.githubusercontent.com/bravenut/fancybeans/main/fancybeans.mjs -o ~/tools/fancybeans.mjs
chmod +x ~/tools/fancybeans.mjs

Without Node — grab a prebuilt binary from the latest release:

mkdir -p ~/tools
curl -fsSL https://github.com/bravenut/fancybeans/releases/latest/download/fancybeans-linux-x64.tar.gz | tar xz -C ~/tools

Assets: fancybeans-{linux,macos}-{x64,arm64}. On macOS the binary is unsigned, so the first run may need right-click → Open or xattr -d com.apple.quarantine ~/tools/fancybeans-*.

Then put it on your PATH so you can type fancybeans anywhere — symlink it into a directory that's on your PATH (create one like ~/bin if you need to):

mkdir -p ~/bin && echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc; then run: exec $SHELL
ln -s ~/tools/fancybeans.mjs ~/bin/fancybeans        # …or ~/tools/fancybeans-linux-x64 for the binary

Or if you prefer not to touch PATH, use an alias: alias fancybeans='node ~/tools/fancybeans.mjs'.

Use

Run it from any directory beans can resolve a .beans store for. By default it serves the work tree over HTTP on a local port and re-renders live on each refresh:

fancybeans                        # serve at http://127.0.0.1:7373/
fancybeans --open                 # serve, then open in your browser
fancybeans --port 8080            # bind a specific port (falls back to a free one if taken)
fancybeans --host 0.0.0.0         # bind a non-loopback address (exposes it on your network)
fancybeans --project myproj       # set the project header name

Prefer a file? Pass -o and it writes a single self-contained HTML page instead — no external dependencies, all bean data embedded, so it works offline:

fancybeans -o roadmap.html
fancybeans -o roadmap.html --open

Features

• Masthead — a single stacked bar showing the shape of the work (every bean by status), plus counts: beans, % complete, blocked, and a top-level count auto-labelled from the shallowest type in use (Milestones, Epics, Features, …).
• Work tree — the full hierarchy with a status marker per bean (dashed ring = draft, hollow = todo, half-filled = in progress, filled ✓ = completed, ✕ = scrapped). Any bean with children carries a progress meter of its subtree.
• Filters & search — toggle by status, type, priority, or tag; the status legend doubles as a filter. / focuses search (matches titles and bodies). Ancestors of matches stay visible so context is never lost.
• Detail drawer — click any bean for its rendered markdown spec, breadcrumb, metadata, and clickable blocked-by / blocks / children links.
• Light/dark aware, keyboard-navigable, responsive down to mobile, print-friendly.

Contributing

Bug reports and PRs welcome — see CONTRIBUTING.md. It's a tiny tool with no runtime dependencies; the goal is to keep it that way.

License

MIT.