A lightweight, standalone desktop application for managing Beads issues outside of your IDE.

Beads is an AI-native issue tracker that stores issues directly in your codebase (in a .beads folder). Compatible with both br (Rust, recommended) and bd (Go).

Planet57's vscode-beads extension provides an excellent interface for managing these issues. However, VS Code can be resource-intensive. If you want to browse and manage your Beads issues without keeping VS Code open, this standalone app is for you.

This project is a reimplementation of the Beads UI as a native desktop app using Tauri, resulting in:

• Minimal memory footprint (~50MB vs VS Code's 500MB+)
• Fast startup (instant vs several seconds)
• Dedicated window for issue management
• Works alongside any editor (Vim, Emacs, JetBrains, etc.)

The app uses a native file watcher on the .beads directory. When an AI agent (or anyone) creates, updates, or closes an issue via br or bd, the change appears in real time — no refresh button, no polling interval. This is critical when monitoring AI-driven workflows where issues change rapidly.

• Add/remove blockers from the issue preview via a search modal
• Navigate to any dependency or relation by clicking its row (short ID + title)
• Blocked indicator in the issue table for issues with unresolved blockers
• Add/remove relations (relates-to, duplicates, supersedes, caused-by, etc.) between any issues, including closed ones
• Dynamic relation types adapted to your CLI client (bd or br)

• Dashboard: Visual overview of issues by status, type, and priority
• Issue Management: Create, edit, close, and comment on issues
• Epic Hierarchy: Parent/child relationships with collapsible groups and inline progress bars
• Multi-Project Support: Save favorite projects and switch between them instantly

• Image Attachments: Attach and preview screenshots directly in issues (thumbnail gallery)
• Markdown Attachments: Attach .md files with full preview, inline editing, and save workflow
• Markdown Search: Find text within markdown previews with match highlighting and navigation (Cmd/Ctrl+F)
• Gallery Navigation: Browse multiple attached files with arrow keys or buttons

• Extended Status Support: All Beads statuses handled — deferred, pinned, hooked, and tombstone (deleted) issues filtered from default view
• Advanced Filters: Multi-select filters by type, status, priority, labels, and assignee
• Exclusion Filters: Hide specific issues by criteria (inverse filtering)
• Search: Find issues by title, ID, or description
• Column Customization: Show/hide and configure table columns per project
• Smart Short IDs: Common prefix is automatically detected and hidden for readability
• Collapsible Sections: All preview sections (description, attachments, dependencies, etc.) are independently collapsible with persistent state

• Multi-Select: Toggle multi-select mode to select issues individually or all at once
• Bulk Delete: Delete multiple selected issues in one operation
• Sortable Columns: Click any column header to sort (ascending, descending, or clear)
• Zoom Controls: Adjust UI scale from 75% to 150% (Alt+Click to reset)

• Dual CLI support: Auto-detects br (Rust, recommended) and bd (Go) — switch between them via Settings (Cmd/Ctrl+,), feature profiles adapt automatically
• Theme System: 4 themes — Classic Light, Classic Dark, Dark Flat, and Neon — with per-theme badge styling, glow effects, and one-click cycling via the header icon
• Debug Panel: Live log viewer with auto-refresh, accessible via Cmd/Ctrl+Shift+L
• Database Repair: Automatic detection and repair of schema migration issues
• Keyboard Shortcuts: Cmd/Ctrl+, (settings), Cmd/Ctrl+F (search in markdown), Cmd/Ctrl+Shift+L (debug logs), arrow keys (gallery navigation)

The Beads CLI has no built-in attachment support. This app implements its own filesystem-based attachment system using the .beads/attachments/ directory as the sole source of truth.

When you attach files to an issue:

1. Files are copied into .beads/attachments/{issue-id}/
2. The app detects attachments by scanning the filesystem directory
3. Multiple files (images and markdown) can be attached in a single operation
4. Files are categorized automatically by extension (image, markdown, or external reference)

This means the attachment storage lives inside the .beads directory and gets versioned alongside your issues.

For developers: If you want to script attachment creation (e.g., automatically attach files when creating issues), see the detailed technical documentation in docs/attachments.md.

Beyond just viewing issues, this app is part of a broader development workflow powered by Claude Code:

• Centralized task management: Beads issues live in the codebase, making them accessible to AI coding assistants
• AI-driven development: Claude Code can read, create, and update issues directly via br or bd, keeping context within the coding session
• External bug sync: Custom commands can import bugs from external systems (Jira, Redmine, etc.) into Beads
• Daily planning: Quickly review and prioritize tasks for the day without switching contexts

Important: This app requires a Beads CLI to be installed on your system. It acts as a graphical interface for the Beads command-line tool.

beads_rust (br) is our recommended CLI — it's faster, more optimized, and built on the proven SQLite + JSONL architecture. This is our primary choice going forward.

1. Install br — follow the instructions at github.com/Dicklesworthstone/beads_rust

2. Initialize Beads in your project

   cd your-project
   br init

3. Verify installation

   br --version

The app auto-detects which CLI is installed. You can switch between br and bd at any time via Settings (Cmd/Ctrl+,).

bd (bd) version 0.49.x remains fully supported as a fallback. This is the last stable Go version with embedded Dolt and native file watcher support.

Do not upgrade to bd 0.50–0.56+ which switched to server mode, introducing regressions for standalone desktop use. See beads#2050 for details. If bd with Dolt regains comparable reactivity and performance in future versions, we'll reconsider.

# Install bd (check the repo for the latest method)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

br and bd can be installed simultaneously. The app lets you switch between them at any time via Settings — useful for comparing behavior or transitioning gradually.

If you use an AI coding assistant (Claude Code, Cursor, etc.) to pilot your issues, configure its skills/commands to use the CLI of your choice (br or bd). The app will reflect changes from either one in real time.

Download the latest release for your platform from the Releases page:

• macOS: .dmg file (Apple Silicon & Intel)
• Windows: .msi or .exe installer
• Linux: .deb (Debian/Ubuntu) or .AppImage

macOS may block the app because it's not signed with an Apple Developer certificate. You'll see a message saying the app "is damaged and can't be opened."

To fix this, run the following command after installing:

xattr -cr /Applications/Beads\ Task-Issue\ Tracker.app

Then open the app normally. This only needs to be done once.

# Clone the repository
git clone https://github.com/w3dev33/beads-task-issue-tracker.git
cd beads-task-issue-tracker

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm tauri:build

This application is built with modern web technologies, packaged as a native desktop app:

• bd Beads - The AI-native issue tracker by Steve Yegge
• Beads VS Code Extension - The Planet57 VS Code extension
• Community Tools - Other Beads community projects

Contributions are welcome! Please feel free to submit issues and pull requests.

MIT - Laurent Chapin

This project was developed with the assistance of Claude Code, Anthropic's AI-powered coding assistant.