BEADS WEB

Beads CLI is powerful for task tracking, but:

• No visual overview of task status across columns
• No drag-and-drop to move tasks between states
• No way to see epic progress at a glance
• No visual diff between blocked, ready, and in-progress

Beads Web gives you a real-time Kanban board, multi-project dashboard, and git operations — without leaving the browser.

Inspired by Beads-Kanban-UI by Aviv Kaplan. The original author appears to have stopped development — PRs go unreviewed for months.

This fork has diverged significantly: 84 files changed, ~9500 lines added.

Full changelog with rationale: docs/changelog.md

• Multi-project dashboard — all projects in one place with status donut charts
• Kanban board — Open → In Progress → In Review → Closed with drag-to-update
• Epic support — group tasks with visual progress bars, view subtasks
• GitOps — create, view, and merge PRs from the board. CI status, merge conflicts, auto-close
• Memory panel — browse, search, edit knowledge base entries
• 11 themes — Default Dark, Glassmorphism, Neo-Brutalist, Linear Minimal, Soft Light, Notion Warm, GitHub Clean, plus Catppuccin Latte, Frappe, Macchiato, and Mocha
• Dolt integration — connect to Dolt databases directly, no filesystem path needed
• Real-time sync — SSE file watcher for local projects, polling for Dolt

Soft Light theme is shown in the main screenshot above.

• Frontend: Next.js 14, React 18, TypeScript, Tailwind CSS, Radix UI, dnd-kit
• Backend: Rust (Axum), SQLite, Dolt SQL
• Build: Static export embedded into Rust binary via rust-embed

• Beads CLI (bd) installed and available in PATH

Download the binary for your platform from GitHub Releases:

Each release also ships a SHA256SUMS.txt to verify your download.

Scoop (Windows):

scoop bucket add beads-web https://github.com/weselow/beads-web
scoop install beads-web

Update later with scoop update beads-web.

Nix (macOS / Linux / WSL):

nix run github:weselow/beads-web

Homebrew (macOS / Linux):

brew install weselow/beads-web/beads-web

winget (Windows):

winget install weselow.beads-web

winget becomes available once the submission is accepted into the winget community repository.

# macOS/Linux — make executable, then run
chmod +x beads-web-*
./beads-web-darwin-arm64

# Windows
beads-web-win-x64.exe

Open http://localhost:3008. The frontend is embedded in the binary — no Node.js or Rust needed.

Prerequisites: Node.js 20+, Rust toolchain, and the Beads CLI (bd) in PATH.

git clone https://github.com/weselow/beads-web.git
cd beads-web
npm install

There are two workflows: Dev Mode (frontend hot-reload) and Build from Source (release binary).

The Next.js dev server (port 3007) serves the frontend with hot-reload; the Rust backend (port 3008) serves the API. They talk cross-origin — CORS is open on the backend.

1. Point the frontend at the backend:

   cp .env.local.example .env.local   # sets NEXT_PUBLIC_BACKEND_URL=http://localhost:3008

2. Generate the out/ folder once (with output: 'export' still enabled). The Rust server embeds out/ via rust-embed, so it must exist before you build the backend:

   npm run build

3. Then comment out output: 'export' in next.config.js — next dev is incompatible with static export.

4. Run both servers in separate terminals:

   npm run dev              # Terminal 1 — frontend on http://localhost:3007
   cd server && cargo run   # Terminal 2 — backend/API on http://localhost:3008

5. Open http://localhost:3007. Frontend edits hot-reload; API requests go to the backend on :3008.

The .env.local / NEXT_PUBLIC_BACKEND_URL step is dev-only. Remove it (or leave it unset) for a release build, where frontend and backend share one origin.

Produces the same self-contained binary that CI publishes to Releases — the frontend is embedded, so no Node.js or Rust is needed at runtime.

npm install
# keep `output: 'export'` enabled in next.config.js (the default)
npm run build                 # static export → out/
cd server
cargo build --release         # binary → server/target/release/beads-server (.exe on Windows)

Run the binary and open http://localhost:3008:

./server/target/release/beads-server

Q: Do I need Dolt? A: No. Beads Web works with local filesystem projects using bd CLI. Dolt adds direct SQL access and remote database support.

Q: How do I add a project? A: Click "Add Project" on the dashboard. Browse to your project folder or enter a dolt:// URL.

• Beads-Kanban-UI by Aviv Kaplan — original project
• beads by Steve Yegge — git-native task tracking
• Claude Protocol — orchestration framework (works great together)

MIT