Beadbox has a sister project, initech — a runtime for agents that collaborate with each other from one terminal, optimized for steerability. Beadbox is built and maintained with it; worth a look.
A fast, native GUI for the beads issue tracker.
Beadbox gives bd users a visual interface for the things a terminal can't show well — epic trees, dependency structure, pipeline state, and live activity — without making simple operations slower than typing bd show.
- Epic tree — hierarchical view of epics and child beads with status, priority, and progress at a glance
- Chart — a timeline per epic: when work on each bead started and closed, what is planned after what, and what blocks what; same filters as the Beads view
- Trains —
.beadtrainfiles in the workspace.beads/folder: ready cars, coupler joins, click through to the bead - Waiting — open
bdgates (human, timer, gh:run, gh:pr, bead), oldest first, with the work each one holds; resolve a human gate in place. The tab (⌘6) appears only while a gate is open - Live updates — changes made from the
bdCLI appear in the UI in real time; no refresh - Bead detail — full descriptions, comments, dependencies, and workflow advancement in a side panel or modal
- Filters — slice by status, type, priority, assignee, and label (any selected label matches); filters persist across sessions, and label selections clear when switching workspaces
- Activity feed — a timeline of what changed, by whom, across the workspace
- Multi-workspace — a rail of project tabs switches between local
.beads/projects and remote Dolt servers; rename a tab, give it an emoji, and switching back is instant - Keyboard-first — power-user paths work without touching the mouse
Requires the beads CLI, version 1.1.0 or newer (brew install beads). Beadbox is a GUI over bd; issue data lives in your beads database. .beadtrain files in .beads/ are optional plans (see Beadtrains) shown on the Trains tab.
brew install --cask beadbox/cask/beadboxOr download the DMG (Apple Silicon) from Releases. Builds are signed and notarized.
Download packages from Releases.
More at beadbox.app.
Prerequisites: Bun, Rust (stable), Node.js, and the platform prerequisites for Tauri v2.
git clone https://github.com/beadbox/beadbox.git
cd beadbox
bun install
# Run the desktop app in development
bun run tauri:dev
# Or run the web client + server without the native shell
bun run dev
# Build a release bundle
bun run tauri:buildTo try a change in a real app on macOS without touching an installed Beadbox, build a separate, locally signed copy:
bash scripts/build-local-macos.shNothing is installed. The app stays in the build tree at
src-tauri/target/release/bundle/macos/Beadbox Local.app, with a scratch
profile beside it in src-tauri/target/local-profile/. Open it from Finder
or with:
open -n "src-tauri/target/release/bundle/macos/Beadbox Local.app"How it stays separate from the installed app:
- Own bundle identifier (
app.beadbox.local) and name, so macOS keeps its window, WebView and app-data state apart from the installed Beadbox. - Scratch workspace registry. The app's
Info.plist(LSEnvironment) pointsBEADBOX_REGISTRY_PATHatsrc-tauri/target/local-profile/registry.jsonandBEADS_REGISTRY_PATHat a file in the same folder, so the app neither reads your registered workspaces nor imports them from the legacy~/.beads/registry.jsonon first run. It starts with no workspaces; add a test workspace from inside the app. - Own sidecar log at
src-tauri/target/local-profile/sidecar.log(viaBEADBOX_LOG_PATH) instead of~/Library/Logs/Beadbox/. - No updates. The build has no update endpoint, so it cannot replace itself with a release build; the update check reports that it failed.
- No analytics. The build blanks the analytics key.
What it still shares or leaves behind:
- The installed
bd. Any workspace you add in the local app is a real workspace on disk; opening one of your real workspaces from both apps at once works, but edits from either land in the same database. - Saved server-workspace credentials live in the same macOS keychain service
(
beadbox) as the installed app. - macOS and WebKit create per-app folders for
app.beadbox.local(for example under~/Library/WebKitand~/Library/Caches) when it first launches. They are separate from the installed app's; delete them with the build if you want a clean slate. - The build uses the usual toolchain caches (
~/.cargo,~/.bun).
The signature is ad hoc and the build is not notarized; it is for your own
machine only. The scratch paths are absolute and baked into the bundle at build
time: if you move the repository, rebuild. They apply whenever macOS opens the
app (Finder, Spotlight, open), but not if you run the executable inside
Contents/MacOS directly.
Beadbox is a Tauri v2 app. The Rust shell spawns a Bun sidecar process and talks to it over stdio (kkrpc) — the app itself opens no network ports. (One opt-in exception, off by default: if you enable the bd serve reads pilot for a local server-mode workspace, bd opens one token-authenticated listener on 127.0.0.1 for that workspace, which the app starts and stops with itself; see SECURITY.md for the helper process bd starts alongside it and the one case where that can outlive the app.) All issue data flows through the bd CLI; Beadbox never touches the database behind bd's back. Live updates come from watching the workspace filesystem (local) or polling Dolt table hashes (server workspaces).
See CONTRIBUTING.md. Contributions are accepted under the MIT license — no CLA.
To report a vulnerability, see SECURITY.md. Please don't open public issues for security reports.
Beadbox checks executable files in mise ($MISE_DATA_DIR/shims,
$XDG_DATA_HOME/mise/shims, and ~/.local/share/mise/shims), asdf
($ASDF_DATA_DIR/shims and ~/.asdf/shims), and Nix profiles before Homebrew,
Go and user-local installs, then falls back to its inherited PATH. Nix profiles
include ~/.nix-profile/bin, ~/.local/state/nix/profiles/profile/bin,
/etc/profiles/per-user/$USER/bin,
/nix/var/nix/profiles/per-user/$USER/profile/bin, and
/nix/var/nix/profiles/default/bin.
Existing version-manager directories are also added to child PATH so bd can
find tools installed beside it. The inherited PATH keeps its existing order.
Set a per-user path in Settings → General → bd executable, or directly on
any missing-bd or too-old-bd screen. Use the absolute executable path (spaces are
supported; surrounding whitespace is trimmed and ~/ is expanded). Beadbox
requires the selected basename to be bd (bd.exe on Windows), even for
symlinks. The target must be a regular executable owned by the current user or
root and must not be group- or world-writable. All static checks run before the
supported-version probe when saving. Use automatic detection clears the preference.
The active path and source are shown beside the controls.
Precedence is BD_PATH environment variable, then the saved path, then automatic
detection. An environment override stays active until it is removed from the
app's launch environment; saving or clearing a preference does not override it.
Corrupt settings are logged and treated as no saved path; resetting replaces the
invalid file. Saved paths and target permissions are checked again on every
read before spawning; invalid choices warn without logging their contents and
fall back to automatic detection.
The choice is stored in ~/.beadbox/settings.json, applies to every workspace,
and survives restarts. Changes apply to new commands immediately and refresh
active polling and bd serve processes. Commands already running may finish with
the previous binary. If a saved executable disappears later, automatic detection is used.
Version-manager shims select tool versions from the workspace, just as invoking
bd in that workspace from a terminal does; the version manager governs trust.
MIT © 2026 Nelson Melo

