Beans VS Code Extension

Beautifully integrated Beans issue tracking for VS Code

Beans is a file-based issue tracker that lives alongside your code. This extension brings the full Beans experience into VS Code with native tree views, AI integration, and powerful workflow automation.

Key Features

• 🌴 Tree Views: Organized sidebar panes for drafts, open, completed, and scrapped beans with hierarchical nesting, in-progress descendant badges, and item counts
• 📋 Details View: Rich webview panel with rendered markdown, interactive checklists, editable properties, relationship navigation, and browsing history with back navigation
• 🔍 Search & Filter: Full-text search across all fields, filter by status/type/priority/tags, five sort modes, and dedicated search results view with context menus
• 🎯 Drag & Drop: Create parent-child hierarchies visually with cycle detection and confirmation
• 🔗 Relationships: Parent-child hierarchies (milestone > epic > feature > task) and blocking/blocked-by dependency tracking
• 🤖 AI Integration: MCP tools for all operations, @beans chat participant with 7 slash commands, auto-generated Copilot skills & instructions, and "Start Work" templates for Copilot-assisted workflows
• 🌐 Remote Ready: Works seamlessly in SSH, WSL, containers, and Codespaces
• ⚡ Keyboard-First: Configurable shortcuts for all operations
• 📂 File Watching: Automatic tree refresh on filesystem changes with configurable debounce
• 🛡️ Resilient: Offline mode with caching, request deduplication, retry with exponential backoff, malformed bean detection, and structured error handling with actionable guidance
• 🧪 Extensively Tested: Comprehensive automated unit and integration test suite
• ♿ Accessible: Built following WCAG 2.2 Level AA guidelines
• 🤫 Privacy Respecting: No telemetry or data collection of any kind
• 🐶 Completely Dogfooded: The extension was used by the developer to project manage developing the extension

About Beans

Beans is a modern, file-based issue tracker designed for developers who want their issues to live alongside their code. Each "bean" is a markdown file in your repository—no databases, no external services, just version-controlled files.

Why file-based?

• ✅ Version controlled with your code
• ✅ Readable in any text editor
• ✅ Works offline
• ✅ No vendor lock-in
• ✅ Greppable and scriptable
• ✅ Perfect for remote development

Learn more about Beans: github.com/hmans/beans

Quick Start

Install the beans CLI

macOS (Requires Homebrew)

brew install hmans/beans/beans

Linux, MacOs, Windows (Requires Go)

go install github.com/hmans/beans@latest

Install the Beans extension

Use the IDE's Extension sidebar to search for beans or execute the following command:

code --install-extension selfagency.beans-vscode

Initialize Beans in your project

Option 1: Command Palette

1. Open your project in VS Code
2. Press Cmd+Shift+P / Ctrl+Shift+P
3. Run: "Beans: Initialize Beans in Workspace"

Option 2: Terminal

cd <project-folder>
beans init

Create Your First Bean

1. Click the + icon in the Beans sidebar
2. Enter a title: "My first bean"
3. Select type: "task"
4. Optionally add a description
5. Bean created! 🎉

View Beans

• Sidebar: Click any bean in the Active tree
• Details Panel: Opens with bean markdown content
• Edit: Click pencil icon to edit bean file directly

Remote Development

This extension fully supports VS Code Remote Development (SSH, WSL, containers, Codespaces).

Critical requirement: The Beans CLI must be installed on the remote machine, not your local machine.

Documentation

Full user and developer documentation can be found at beans.self.agency.

Support the Project

If you find this extension useful, please leave a review on the VS Code Marketplace or Open VSX. Reviews help other developers discover the extension.

License

MIT

Credits

• Hendrik Mans: Creator of Beans

Accessibility Note

This extension is built with accessibility in mind following WCAG 2.2 Level AA guidelines, but issues may still exist. Please manually test keyboard navigation and screen-reader workflows. Consider auditing with Accessibility Insights.

Feedback and accessibility improvement suggestions are welcome—please file an issue!