BD TUI 🎯

A beautiful, real-time Text User Interface (TUI) visualizer for the bd (beads) issue tracker.

✨ Features

📊 Multiple Visualizations

• Kanban Board - Classic 4-column view (Open, In Progress, Blocked, Closed)
• Tree View - Hierarchical parent-child relationships with interactive navigation
• Dependency Graph - ASCII art visualization of issue dependencies
• Statistics Dashboard - Comprehensive analytics with visual bar charts

🎨 Rich User Experience

• Real-time Updates - File watching with automatic refresh
• Search & Filter - Full-text search across title, description, and ID
• Custom Themes - 5 built-in color schemes (Default, Ocean, Forest, Sunset, Monochrome)
• Responsive Layout - Adapts to terminal size with smart column hiding
• Vim-style Navigation - hjkl keys supported alongside arrow keys

⚡ Issue Management

• Create Issues - Add new issues directly from the TUI
• Edit Issues - Modify any field (title, description, priority, status, assignee, labels)
• Export/Copy - Export issues in Markdown, JSON, or plain text format
• Desktop Notifications - Native OS notifications with custom icons for status changes

🎯 Smart Features

• Per-column Pagination - Independent scroll positions for each status column
• Detail Panel - View full issue details including all dependencies
• Blocked Status Detection - Automatically moves issues with blockers to "Blocked" column
• Keyboard-first - Every action accessible via keyboard shortcuts

🚀 Installation

Prerequisites

• Bun runtime (required)
• bd (beads) issue tracker
• A .beads/ directory with beads.db in your project

Homebrew (macOS)

The easiest way to install on macOS:

brew tap assimelha/tap
brew install bdui

To upgrade to the latest version:

brew upgrade bdui

Download Pre-built Binary

Download the latest release for your platform:

• macOS (ARM64): bdui-macos-arm64
• macOS (x64): bdui-macos-x64
• Linux (x64): bdui-linux-x64
• Windows (x64): bdui-windows-x64.exe

Make it executable (Unix systems):

chmod +x bdui-macos-arm64
./bdui-macos-arm64

Build from Source

# Clone the repository
git clone <repository-url>
cd bdui

# Install dependencies
bun install

# Run in development mode
bun run dev

# Or build single binary for your platform
bun run build
./bdui

Building for All Platforms

# Build for macOS (both ARM64 and x64)
bun run build:macos

# Build for Linux x64
bun run build:linux

# Build for Windows x64
bun run build:windows

# Build for all platforms
bun run build:all

Binaries will be created in the dist/ directory (~50-60 MB each, includes Bun runtime).

📖 Usage

Basic Usage

Navigate to a directory containing a .beads/ folder and run:

bdui

Or from the source directory:

bun run dev

The app will automatically discover the .beads/ directory by walking up the directory tree (like git).

Keyboard Shortcuts

Navigation

• ↑/↓ or k/j - Move up/down (select issue)
• ←/→ or h/l - Move left/right (change column in Kanban view)
• Enter or Space - Toggle detail panel

Views

• 1 - Kanban board view (default)
• 2 - Tree view (hierarchical)
• 3 - Dependency graph
• 4 - Statistics dashboard

Actions

• N (Shift+N) - Create new issue
• e - Edit selected issue
• x - Export/copy selected issue
• t - Change theme

Search & Filter

• / - Open search (searches title, description, ID)
• f - Open filter panel (filter by assignee, tags, priority, status)
• c - Clear all filters and search
• ESC - Close search/filter/form panels

Other

• r - Refresh data from database
• n - Toggle notifications
• ? - Show help
• q or Ctrl+C - Quit

🎨 Views

Kanban View (Default)

The main view shows issues organized in 4 columns:

• Open - New or ready-to-work issues
• In Progress - Currently being worked on
• Blocked - Issues waiting on dependencies
• Closed - Completed issues

Features:

• Color-coded priorities (P0-P4)
• Type indicators (epic, feature, bug, task, chore)
• Label tags
• Per-column pagination and selection
• Responsive layout (adapts to terminal size)

Tree View

Shows hierarchical parent-child relationships:

• Navigate with ↑/↓ or k/j
• Press Enter/Space to toggle details
• Press e to edit selected issue
• Visual tree structure with connection lines
• Depth-aware indentation

Dependency Graph

Visualizes issue dependencies:

• Issues organized by dependency levels
• Shows blocking relationships
• Navigate with ↑/↓ or k/j
• Color-coded by type and status
• Displays parent-child and blocking relationships

Statistics Dashboard

Comprehensive analytics:

• Status Distribution - Visual bar chart of issue statuses
• Priority Breakdown - Distribution across P0-P4
• Issue Type Distribution - Epic, feature, bug, task, chore counts
• Key Metrics - Completion rate, blocked rate, dependency count
• Top Assignees - Most active team members
• Top Labels - Most used labels

🔔 Notifications

BD TUI supports native desktop notifications for important events:

Notification Types

• Task Completed ✅ - When an issue status changes to "closed"

  • Green checkmark icon
  • System sound (macOS)
  • Shows issue ID and priority

• Task Blocked 🚫 - When an issue becomes blocked

  • Red prohibition icon
  • Silent notification
  • Shows number of blocking issues

Notification Icons

Custom icons are located in assets/icons/:

• completed.png - Green circle with white checkmark (512x512)
• blocked.png - Red circle with prohibition symbol (512x512)

Platform support:

• macOS - Full support with custom icons in Notification Center
• Linux - Freedesktop.org notification spec
• Windows - Toast notifications

Toggle notifications with the n key. Current state is shown in the footer (🔔 ON / 🔕 OFF).

Testing Notifications

bun run test:notifications

✏️ Creating and Editing Issues

Create New Issue

Press N (Shift+N) to open the create issue form:

• Tab/Shift+Tab to navigate between fields
• Fill in: title, description, priority (P0-P4), type, assignee, labels
• Press Enter to submit
• ESC to cancel

Edit Existing Issue

Select any issue and press e to open the edit form:

• All fields pre-populated with current values
• Tab/Shift+Tab to navigate
• Use ↑/↓ to change priority and status
• Press Enter to save changes
• ESC to cancel

Changes are immediately written to the bd database and reflected in the UI.

📤 Exporting Issues

Press x on any selected issue to open the export dialog:

Format Options (←/→ to navigate)

• Markdown - Formatted markdown with headers and lists
• JSON - Complete issue data in JSON format
• Plain Text - Simple text format with clear structure

Action Options (↑/↓ to navigate)

• Copy to Clipboard - Copy formatted issue to system clipboard
• Export to File - Save to {issue-id}.{extension} in current directory

Press Enter to execute. Works on macOS, Linux, and Windows.

🎨 Themes

BD TUI includes 5 built-in color schemes. Press t to open the theme selector:

Available Themes

• Default - Classic blue/cyan theme with high contrast
• Ocean - Blue and cyan tones for a calm, aquatic feel
• Forest - Green-focused theme inspired by nature
• Sunset - Warm magenta and yellow tones
• Monochrome - Clean grayscale theme for distraction-free work

Use ↑/↓ or k/j to browse themes. Each theme shows a live color preview. Press Enter to apply.

🔍 Search & Filter

Search (/)

• Full-text search across title, description, and issue ID
• Type to search incrementally
• ESC to close

Filter (f)

• Assignee - Filter by assigned person
• Tags - Filter by labels (multi-select)
• Priority - Filter by P0-P4
• Status - Filter by open/in_progress/blocked/closed
• Tab to cycle between filter types
• Space/Enter to toggle selections
• ESC to close

Clear Filters (c)

Removes all active search and filter criteria.

📊 Responsive Layout

Terminal Size Adaptation

• Wide (>160 cols): All 4 columns + detail panel
• Medium (80-160 cols): All 4 columns
• Narrow (40-80 cols): 2 columns
• Very narrow (<40 cols): 1 column

Minimum Requirements

• Width: 80 columns (recommended: 120+)
• Height: 24 rows (recommended: 30+)
• True color support recommended but not required

Terminal dimensions are shown in the header (e.g., "120x30").

🧪 Testing

Test with Sample Data

A test project with sample issues is included:

cd /tmp/bdui-test
bun run /path/to/bdui/src/index.tsx

The test project includes:

• 11 diverse issues (varied priorities, types, statuses)
• Multiple assignees (alice, bob, charlie, diana)
• Parent-child relationships (epic with children)
• Blocking dependencies
• Various labels and metadata

See /tmp/bdui-test/README.md for a complete feature walkthrough.

Manual Testing

# Test notifications
bun run test:notifications

# Run in development mode
bun run dev

# Test with your own bd project
cd /path/to/your/project
bun run /path/to/bdui/src/index.tsx

🏗️ Architecture

Technology Stack

• Runtime: Bun (native SQLite, faster than Node.js)
• UI Framework: Ink (React for CLIs)
• State Management: Zustand
• Database: SQLite (direct reads from bd's database via bun:sqlite)
• Notifications: node-notifier (cross-platform)

Data Flow

1. Database Reading - Direct SQLite queries to beads.db
2. File Watching - Debounced fs.watch monitoring with 100ms debounce
3. State Management - Zustand store with normalized data structure
4. Real-time Updates - Pub/sub pattern for database changes
5. Notifications - Status change detection with OS notifications

Project Structure

bdui/
├── src/
│   ├── components/       # React/Ink components
│   │   ├── App.tsx       # Main app with keyboard handling
│   │   ├── Board.tsx     # View router
│   │   ├── KanbanView/   # 4-column Kanban board
│   │   ├── TreeView.tsx  # Hierarchical tree view
│   │   ├── DependencyGraph.tsx
│   │   ├── StatsView.tsx
│   │   ├── CreateIssueForm.tsx
│   │   ├── EditIssueForm.tsx
│   │   ├── ExportDialog.tsx
│   │   ├── ThemeSelector.tsx
│   │   └── ...
│   ├── bd/               # bd integration
│   │   ├── parser.ts     # SQLite database reading
│   │   ├── watcher.ts    # File watching
│   │   └── commands.ts   # bd CLI integration
│   ├── state/            # State management
│   │   └── store.ts      # Zustand store
│   ├── themes/           # Theme definitions
│   │   └── themes.ts
│   ├── utils/            # Utilities
│   │   ├── notifications.ts
│   │   └── export.ts
│   ├── types.ts          # TypeScript types
│   └── index.tsx         # Entry point
├── assets/
│   └── icons/            # Notification icons
│       ├── completed.png
│       ├── blocked.png
│       └── README.md
├── CLAUDE.md             # Development documentation
├── package.json
└── README.md             # This file

🤝 Contributing

Contributions are welcome! This project uses bd (beads) for issue tracking.

Development Setup

# Clone repository
git clone <repository-url>
cd bdui

# Install dependencies
bun install

# Run in development mode
bun run dev

Code Guidelines

See CLAUDE.md for detailed architecture documentation and guidelines for:

• Adding new view modes
• Adding new filters
• Creating new components
• Modifying the data flow

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• bd (beads) - The issue tracker that powers this TUI
• Ink - React for CLIs
• Bun - Fast JavaScript runtime
• Zustand - State management
• node-notifier - Cross-platform notifications

📞 Support

For issues, questions, or contributions:

1. Check the documentation in CLAUDE.md
2. Review existing bd issues in this repository
3. Create a new bd issue with detailed information

Made with ❤️ for developers who love the command line