Beads Kanban
A visual Kanban board VS Code extension for managing Beads issues directly in your editor. View, create, edit, and organize your .beads issues with an intuitive drag-and-drop interface.
Screenshots
Kanban View
Drag-and-drop cards between columns to manage your workflow.
Table View
Sort, filter, and customize columns for detailed issue management.
Dependency Graph View
Visualize issue relationships and dependencies with an interactive graph.
Comprehensive issue editing with all metadata fields, dependencies, and comments.
Features
✨ Visual Kanban Board
- Drag-and-drop cards between columns (Ready, In Progress, Blocked, Closed)
- Real-time updates with your
.beads database
- Incremental loading for large issue databases (10,000+ issues)
📊 Table View
- Sortable columns with multi-column sorting (Shift+Click)
- Customizable column visibility
- Pagination with configurable page sizes
- Filter by priority, type, status, and search
🔗 Dependency Graph
- Interactive visualization of issue relationships
- Hierarchical layout with parent-child and blocking dependencies
- Focus mode to explore specific issues and their dependencies
- Drag nodes, zoom/pan controls
- Color-coded by status with visual legend
🔧 Full Issue Management
- Create, edit, and update issues
- Add comments, labels, and dependencies
- Markdown support with live preview
- Rich metadata fields (priority, assignee, estimated time, etc.)
⚡ Daemon Integration
- Uses
bd CLI daemon for all database operations
- Auto-starts daemon when extension loads
- Efficient incremental data loading
Installation
From VSIX (Recommended)
- Download the latest
.vsix file from Releases
- In VS Code:
Extensions > ... > Install from VSIX...
- Select the downloaded file
- Reload VS Code
From VS Code Marketplace
- Open VS Code Extensions view (
Ctrl+Shift+X)
- Search for "Beads Kanban"
- Click Install
Prerequisites
- Beads CLI (
bd): Required for all database operations. Install from github.com/steveyegge/beads
- The extension auto-starts the
bd daemon when needed
Quick Start
Initialize Beads in your project (if not already done):
bd init
Open the Kanban board:
- Command Palette (
Ctrl+Shift+P): "Beads: Open Kanban Board"
- Or use the status bar button
Start managing issues:
- Create issues with the "New" button
- Drag cards between columns to update status
- Click cards to view/edit details
- Switch to Table view for sorting and filtering
What is Beads?
Beads is an AI-native issue tracking system that lives directly in your codebase. Issues are stored in .beads/*.db SQLite files and sync with git, making them perfect for AI coding agents and developers who want issues close to code.
Learn more: github.com/steveyegge/beads
Configuration
| Setting |
Default |
Description |
beadsKanban.readOnly |
false |
Enable read-only mode (no edits) |
beadsKanban.initialLoadLimit |
100 |
Issues per column on initial load |
beadsKanban.pageSize |
50 |
Issues to load when clicking "Load More" |
beadsKanban.preloadClosedColumn |
false |
Load closed issues on initial load |
beadsKanban.lazyLoadDependencies |
true |
Load dependencies on-demand |
Development
Prerequisites
- Node.js 20+
- VS Code 1.90+
Build from Source
# Clone the repository
git clone https://github.com/davidcforbes/beads-kanban.git
cd beads-kanban
# Install dependencies
npm install
# Compile
npm run compile
# Run tests
npm test
# Package VSIX
npx @vscode/vsce package
Development Workflow
- Press
F5 to launch Extension Development Host
- Make changes to source files
- Press
Ctrl+Shift+F5 to reload extension
- Use
npm run watch for automatic compilation
Testing
# Run all tests
npm test
# Watch mode
npm run test:watch
# Coverage report
npm run test:coverage
# Integration tests
npm run test:adapter
Architecture
The extension uses a clean architecture with three main layers:
- Extension Host (
src/extension.ts): Command registration, webview lifecycle, message routing
- Data Adapter (
src/daemonBeadsAdapter.ts): CLI-based daemon adapter for all database operations
- Webview UI (
media/board.js, media/styles.css): Reactive UI with incremental loading
See CLAUDE.md for detailed architecture documentation.
Contributing
Contributions are welcome! This is an actively maintained fork where the original author became non-responsive.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Development Guidelines
- Follow existing code style (use ESLint)
- Add tests for new features
- Update documentation as needed
- Keep commits focused and well-described
Attribution
This project is a fork of the original work by sebcook-ctrl. When the original author became non-responsive, this repository was established to continue active development and accept community contributions.
Original Project: agent.native.activity.layer.beads
License
MIT License - see LICENSE file for details.
Copyright (c) 2024 Agent Native Kanban Contributors
Original work Copyright (c) 2024 sebcook-ctrl
Gratitude
Made with ❤️ for the Beads community
Questions? Open an issue or start a discussion!
