https://github.com/selfagency/beans-vscode
🫘 Bring the full Beans experience into VS Code with native tree views, AI integration, and powerful workflow automation.
https://github.com/selfagency/beans-vscode
beans github-copilot issue-tracker mcp-server project-management remote-development task-management vscode-extension
Last synced: 21 days ago
JSON representation
🫘 Bring the full Beans experience into VS Code with native tree views, AI integration, and powerful workflow automation.
- Host: GitHub
- URL: https://github.com/selfagency/beans-vscode
- Owner: selfagency
- License: mit
- Created: 2026-02-16T04:06:01.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T04:40:24.000Z (21 days ago)
- Last Synced: 2026-04-06T06:25:42.878Z (21 days ago)
- Topics: beans, github-copilot, issue-tracker, mcp-server, project-management, remote-development, task-management, vscode-extension
- Language: TypeScript
- Homepage: https://beans.self.agency/
- Size: 2.33 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Beans VS Code Extension
**Beautifully integrated Beans issue tracking for VS Code**
[Beans](https://github.com/hmans/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.
[](https://github.com/selfagency/beans-vscode/releases)
[](https://github.com/selfagency/beans-vscode/actions/workflows/tests.yml)
[](https://codecov.io/github/selfagency/beans-vscode)
[](https://github.com/selfagency/beans-vscode/actions/workflows/remote-test.yml)
[](https://github.com/selfagency/beans-vscode/actions/workflows/release.yml)
[](https://opensource.org/licenses/MIT)
## 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**: Consolidated MCP tools for query/update/batch/file/log workflows, `@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](https://github.com/hmans/beans)
## Quick Start
### Install the [`beans`](https://github.com/hmans/beans#installation) CLI
#### macOS (Requires Homebrew)
```bash
brew install hmans/beans/beans
```
#### Linux, MacOs, Windows (Requires Go)
```bash
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:
```bash
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
```bash
cd
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](beans.self.agency).
## Support the Project
If you find this extension useful, please leave a review on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=selfagency.beans-vscode) or [Open VSX](https://open-vsx.org/extension/selfagency/beans-vscode). Reviews help other developers discover the extension.
## License
[MIT](./LICENSE)
## Credits
- **[Hendrik Mans](https://github.com/hmans)**: 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](https://accessibilityinsights.io/).
Feedback and accessibility improvement suggestions are welcome—please file an issue!