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.
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
🔧 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!
