{"id":33340004,"url":"https://github.com/assimelha/bdui","last_synced_at":"2026-04-15T16:33:06.106Z","repository":{"id":325074344,"uuid":"1099725638","full_name":"assimelha/bdui","owner":"assimelha","description":"Real-time Text User Interface for bd (beads) issue tracker with Kanban, Tree, Graph views, and notifications","archived":false,"fork":false,"pushed_at":"2025-11-26T10:19:14.000Z","size":491,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-29T09:20:17.543Z","etag":null,"topics":["beads","bun","cli","ink","issue-tracker","kanban","terminal","tui"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/assimelha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-19T11:12:38.000Z","updated_at":"2025-11-27T01:03:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/assimelha/bdui","commit_stats":null,"previous_names":["assimelha/bdui"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/assimelha/bdui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assimelha%2Fbdui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assimelha%2Fbdui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assimelha%2Fbdui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assimelha%2Fbdui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/assimelha","download_url":"https://codeload.github.com/assimelha/bdui/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assimelha%2Fbdui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31849790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beads","bun","cli","ink","issue-tracker","kanban","terminal","tui"],"created_at":"2025-11-21T12:00:27.660Z","updated_at":"2026-04-15T16:33:06.100Z","avatar_url":"https://github.com/assimelha.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BD TUI 🎯\n\nA beautiful, real-time Text User Interface (TUI) visualizer for the [bd (beads)](https://github.com/steveyegge/beads) issue tracker.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)\n![Bun](https://img.shields.io/badge/runtime-Bun-f472b6.svg)\n\n![BD TUI Screenshot](assets/screenshot.png)\n\n## ✨ Features\n\n### 📊 Multiple Visualizations\n- **Kanban Board** - Classic 4-column view (Open, In Progress, Blocked, Closed)\n- **Tree View** - Hierarchical parent-child relationships with interactive navigation\n- **Dependency Graph** - ASCII art visualization of issue dependencies\n- **Statistics Dashboard** - Comprehensive analytics with visual bar charts\n\n### 🎨 Rich User Experience\n- **Real-time Updates** - File watching with automatic refresh\n- **Search \u0026 Filter** - Full-text search across title, description, and ID\n- **Custom Themes** - 5 built-in color schemes (Default, Ocean, Forest, Sunset, Monochrome)\n- **Responsive Layout** - Adapts to terminal size with smart column hiding\n- **Vim-style Navigation** - hjkl keys supported alongside arrow keys\n\n### ⚡ Issue Management\n- **Create Issues** - Add new issues directly from the TUI\n- **Edit Issues** - Modify any field (title, description, priority, status, assignee, labels)\n- **Export/Copy** - Export issues in Markdown, JSON, or plain text format\n- **Desktop Notifications** - Native OS notifications with custom icons for status changes\n\n### 🎯 Smart Features\n- **Per-column Pagination** - Independent scroll positions for each status column\n- **Detail Panel** - View full issue details including all dependencies\n- **Blocked Status Detection** - Automatically moves issues with blockers to \"Blocked\" column\n- **Keyboard-first** - Every action accessible via keyboard shortcuts\n\n## 🚀 Installation\n\n### Prerequisites\n- [Bun](https://bun.sh) runtime (required)\n- [bd (beads)](https://github.com/steveyegge/beads) issue tracker\n- A `.beads/` directory with `beads.db` in your project\n\n### Homebrew (macOS)\n\nThe easiest way to install on macOS:\n\n```bash\nbrew tap assimelha/tap\nbrew install bdui\n```\n\nTo upgrade to the latest version:\n\n```bash\nbrew upgrade bdui\n```\n\n### Download Pre-built Binary\n\nDownload the latest release for your platform:\n- **macOS (ARM64)**: `bdui-macos-arm64`\n- **macOS (x64)**: `bdui-macos-x64`\n- **Linux (x64)**: `bdui-linux-x64`\n- **Windows (x64)**: `bdui-windows-x64.exe`\n\nMake it executable (Unix systems):\n```bash\nchmod +x bdui-macos-arm64\n./bdui-macos-arm64\n```\n\n### Build from Source\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd bdui\n\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run dev\n\n# Or build single binary for your platform\nbun run build\n./bdui\n```\n\n### Building for All Platforms\n\n```bash\n# Build for macOS (both ARM64 and x64)\nbun run build:macos\n\n# Build for Linux x64\nbun run build:linux\n\n# Build for Windows x64\nbun run build:windows\n\n# Build for all platforms\nbun run build:all\n```\n\nBinaries will be created in the `dist/` directory (~50-60 MB each, includes Bun runtime).\n\n## 📖 Usage\n\n### Basic Usage\n\nNavigate to a directory containing a `.beads/` folder and run:\n\n```bash\nbdui\n```\n\nOr from the source directory:\n\n```bash\nbun run dev\n```\n\nThe app will automatically discover the `.beads/` directory by walking up the directory tree (like git).\n\n### Keyboard Shortcuts\n\n#### Navigation\n- `↑/↓` or `k/j` - Move up/down (select issue)\n- `←/→` or `h/l` - Move left/right (change column in Kanban view)\n- `Enter` or `Space` - Toggle detail panel\n\n#### Views\n- `1` - Kanban board view (default)\n- `2` - Tree view (hierarchical)\n- `3` - Dependency graph\n- `4` - Statistics dashboard\n\n#### Actions\n- `N` (Shift+N) - Create new issue\n- `e` - Edit selected issue\n- `x` - Export/copy selected issue\n- `t` - Change theme\n\n#### Search \u0026 Filter\n- `/` - Open search (searches title, description, ID)\n- `f` - Open filter panel (filter by assignee, tags, priority, status)\n- `c` - Clear all filters and search\n- `ESC` - Close search/filter/form panels\n\n#### Other\n- `r` - Refresh data from database\n- `n` - Toggle notifications\n- `?` - Show help\n- `q` or `Ctrl+C` - Quit\n\n## 🎨 Views\n\n### Kanban View (Default)\nThe main view shows issues organized in 4 columns:\n- **Open** - New or ready-to-work issues\n- **In Progress** - Currently being worked on\n- **Blocked** - Issues waiting on dependencies\n- **Closed** - Completed issues\n\nFeatures:\n- Color-coded priorities (P0-P4)\n- Type indicators (epic, feature, bug, task, chore)\n- Label tags\n- Per-column pagination and selection\n- Responsive layout (adapts to terminal size)\n\n### Tree View\nShows hierarchical parent-child relationships:\n- Navigate with ↑/↓ or k/j\n- Press Enter/Space to toggle details\n- Press `e` to edit selected issue\n- Visual tree structure with connection lines\n- Depth-aware indentation\n\n### Dependency Graph\nVisualizes issue dependencies:\n- Issues organized by dependency levels\n- Shows blocking relationships\n- Navigate with ↑/↓ or k/j\n- Color-coded by type and status\n- Displays parent-child and blocking relationships\n\n### Statistics Dashboard\nComprehensive analytics:\n- **Status Distribution** - Visual bar chart of issue statuses\n- **Priority Breakdown** - Distribution across P0-P4\n- **Issue Type Distribution** - Epic, feature, bug, task, chore counts\n- **Key Metrics** - Completion rate, blocked rate, dependency count\n- **Top Assignees** - Most active team members\n- **Top Labels** - Most used labels\n\n## 🔔 Notifications\n\nBD TUI supports native desktop notifications for important events:\n\n### Notification Types\n- **Task Completed** ✅ - When an issue status changes to \"closed\"\n  - Green checkmark icon\n  - System sound (macOS)\n  - Shows issue ID and priority\n\n- **Task Blocked** 🚫 - When an issue becomes blocked\n  - Red prohibition icon\n  - Silent notification\n  - Shows number of blocking issues\n\n### Notification Icons\nCustom icons are located in `assets/icons/`:\n- `completed.png` - Green circle with white checkmark (512x512)\n- `blocked.png` - Red circle with prohibition symbol (512x512)\n\nPlatform support:\n- **macOS** - Full support with custom icons in Notification Center\n- **Linux** - Freedesktop.org notification spec\n- **Windows** - Toast notifications\n\nToggle notifications with the `n` key. Current state is shown in the footer (🔔 ON / 🔕 OFF).\n\n### Testing Notifications\n```bash\nbun run test:notifications\n```\n\n## ✏️ Creating and Editing Issues\n\n### Create New Issue\nPress `N` (Shift+N) to open the create issue form:\n- Tab/Shift+Tab to navigate between fields\n- Fill in: title, description, priority (P0-P4), type, assignee, labels\n- Press Enter to submit\n- ESC to cancel\n\n### Edit Existing Issue\nSelect any issue and press `e` to open the edit form:\n- All fields pre-populated with current values\n- Tab/Shift+Tab to navigate\n- Use ↑/↓ to change priority and status\n- Press Enter to save changes\n- ESC to cancel\n\nChanges are immediately written to the bd database and reflected in the UI.\n\n## 📤 Exporting Issues\n\nPress `x` on any selected issue to open the export dialog:\n\n### Format Options (←/→ to navigate)\n- **Markdown** - Formatted markdown with headers and lists\n- **JSON** - Complete issue data in JSON format\n- **Plain Text** - Simple text format with clear structure\n\n### Action Options (↑/↓ to navigate)\n- **Copy to Clipboard** - Copy formatted issue to system clipboard\n- **Export to File** - Save to `{issue-id}.{extension}` in current directory\n\nPress Enter to execute. Works on macOS, Linux, and Windows.\n\n## 🎨 Themes\n\nBD TUI includes 5 built-in color schemes. Press `t` to open the theme selector:\n\n### Available Themes\n- **Default** - Classic blue/cyan theme with high contrast\n- **Ocean** - Blue and cyan tones for a calm, aquatic feel\n- **Forest** - Green-focused theme inspired by nature\n- **Sunset** - Warm magenta and yellow tones\n- **Monochrome** - Clean grayscale theme for distraction-free work\n\nUse ↑/↓ or k/j to browse themes. Each theme shows a live color preview. Press Enter to apply.\n\n## 🔍 Search \u0026 Filter\n\n### Search (/)\n- Full-text search across title, description, and issue ID\n- Type to search incrementally\n- ESC to close\n\n### Filter (f)\n- **Assignee** - Filter by assigned person\n- **Tags** - Filter by labels (multi-select)\n- **Priority** - Filter by P0-P4\n- **Status** - Filter by open/in_progress/blocked/closed\n- Tab to cycle between filter types\n- Space/Enter to toggle selections\n- ESC to close\n\n### Clear Filters (c)\nRemoves all active search and filter criteria.\n\n## 📊 Responsive Layout\n\n### Terminal Size Adaptation\n- **Wide (\u003e160 cols)**: All 4 columns + detail panel\n- **Medium (80-160 cols)**: All 4 columns\n- **Narrow (40-80 cols)**: 2 columns\n- **Very narrow (\u003c40 cols)**: 1 column\n\n### Minimum Requirements\n- Width: 80 columns (recommended: 120+)\n- Height: 24 rows (recommended: 30+)\n- True color support recommended but not required\n\nTerminal dimensions are shown in the header (e.g., \"120x30\").\n\n## 🧪 Testing\n\n### Test with Sample Data\nA test project with sample issues is included:\n\n```bash\ncd /tmp/bdui-test\nbun run /path/to/bdui/src/index.tsx\n```\n\nThe test project includes:\n- 11 diverse issues (varied priorities, types, statuses)\n- Multiple assignees (alice, bob, charlie, diana)\n- Parent-child relationships (epic with children)\n- Blocking dependencies\n- Various labels and metadata\n\nSee `/tmp/bdui-test/README.md` for a complete feature walkthrough.\n\n### Manual Testing\n```bash\n# Test notifications\nbun run test:notifications\n\n# Run in development mode\nbun run dev\n\n# Test with your own bd project\ncd /path/to/your/project\nbun run /path/to/bdui/src/index.tsx\n```\n\n## 🏗️ Architecture\n\n### Technology Stack\n- **Runtime**: Bun (native SQLite, faster than Node.js)\n- **UI Framework**: Ink (React for CLIs)\n- **State Management**: Zustand\n- **Database**: SQLite (direct reads from bd's database via `bun:sqlite`)\n- **Notifications**: node-notifier (cross-platform)\n\n### Data Flow\n1. **Database Reading** - Direct SQLite queries to `beads.db`\n2. **File Watching** - Debounced `fs.watch` monitoring with 100ms debounce\n3. **State Management** - Zustand store with normalized data structure\n4. **Real-time Updates** - Pub/sub pattern for database changes\n5. **Notifications** - Status change detection with OS notifications\n\n### Project Structure\n```\nbdui/\n├── src/\n│   ├── components/       # React/Ink components\n│   │   ├── App.tsx       # Main app with keyboard handling\n│   │   ├── Board.tsx     # View router\n│   │   ├── KanbanView/   # 4-column Kanban board\n│   │   ├── TreeView.tsx  # Hierarchical tree view\n│   │   ├── DependencyGraph.tsx\n│   │   ├── StatsView.tsx\n│   │   ├── CreateIssueForm.tsx\n│   │   ├── EditIssueForm.tsx\n│   │   ├── ExportDialog.tsx\n│   │   ├── ThemeSelector.tsx\n│   │   └── ...\n│   ├── bd/               # bd integration\n│   │   ├── parser.ts     # SQLite database reading\n│   │   ├── watcher.ts    # File watching\n│   │   └── commands.ts   # bd CLI integration\n│   ├── state/            # State management\n│   │   └── store.ts      # Zustand store\n│   ├── themes/           # Theme definitions\n│   │   └── themes.ts\n│   ├── utils/            # Utilities\n│   │   ├── notifications.ts\n│   │   └── export.ts\n│   ├── types.ts          # TypeScript types\n│   └── index.tsx         # Entry point\n├── assets/\n│   └── icons/            # Notification icons\n│       ├── completed.png\n│       ├── blocked.png\n│       └── README.md\n├── CLAUDE.md             # Development documentation\n├── package.json\n└── README.md             # This file\n```\n\n## 🤝 Contributing\n\nContributions are welcome! This project uses [bd (beads)](https://github.com/steveyegge/beads) for issue tracking.\n\n### Development Setup\n```bash\n# Clone repository\ngit clone \u003crepository-url\u003e\ncd bdui\n\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run dev\n```\n\n### Code Guidelines\nSee `CLAUDE.md` for detailed architecture documentation and guidelines for:\n- Adding new view modes\n- Adding new filters\n- Creating new components\n- Modifying the data flow\n\n## 📄 License\n\nMIT License - See LICENSE file for details\n\n## 🙏 Acknowledgments\n\n- [bd (beads)](https://github.com/steveyegge/beads) - The issue tracker that powers this TUI\n- [Ink](https://github.com/vadimdemedes/ink) - React for CLIs\n- [Bun](https://bun.sh) - Fast JavaScript runtime\n- [Zustand](https://github.com/pmndrs/zustand) - State management\n- [node-notifier](https://github.com/mikaelbr/node-notifier) - Cross-platform notifications\n\n## 📞 Support\n\nFor issues, questions, or contributions:\n1. Check the documentation in `CLAUDE.md`\n2. Review existing bd issues in this repository\n3. Create a new bd issue with detailed information\n\n---\n\n**Made with ❤️ for developers who love the command line**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassimelha%2Fbdui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fassimelha%2Fbdui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassimelha%2Fbdui/lists"}