beans

Beans is an issue tracker for you, your team, and your coding agents. Instead of tracking tasks in a separate application, Beans stores them right alongside your code. You can use the beans CLI to interact with your tasks, but more importantly, so can your favorite coding agent!

This gives your robot friends a juicy upgrade: now they get a complete view of your project, make suggestions for what to work on next, track their progress, create bug issues for problems they find, and more.

You've been programming all your life; now you get to be a product manager. Let's go! 🚀

Announcement Trailer ✨

https://github.com/user-attachments/assets/dbe45408-d3ed-4681-a436-a5e3046163da

Stability Warning ⚠️

Beans is still under heavy development, and its features and APIs may still change significantly. If you decide to use it now, please follow the release notes closely.

Since Beans emits its own prompt instructions for your coding agent, most changes will "just work"; but sometimes, we modify the schema of the underlying data files, which may require some manual migration steps. If you get caught by one of these changes, your agent will often be able to migrate your data for you:

The Beans data format has changed. Please migrate this project's beans to the new format.

Features

• Track tasks, bugs, features, and more right alongside your code.
• Plain old Markdown files stored in a .beans directory in your project. Easy to version control, readable and editable by humans and machines alike!
• Use the beans CLI to create, list, view, update, and archive beans; but more importantly, let your coding agent do it for you!
• Supercharge your robot friend with full context about your project and its open tasks. A built-in GraphQL query engine allows your agent to get exactly the information it needs, keeping token use to a minimum.
• Project memory: Completed beans are archived and serve as project memory that your coding agent can query for context about past work.
• A beautiful built-in TUI for browsing and managing your beans from the terminal.
• Generates a Markdown roadmap document for your project from your data.

Installation

We'll need to do three things:

1. Install the beans CLI tool.
2. Configure your project to use it.
3. Configure your coding agent to interact with it.

Either download Beans from the Releases section, or install it via Homebrew:

brew install hmans/beans/beans

Alternatively, install directly via Go:

go install github.com/hmans/beans@latest

Configure Your Project

Inside the root directory of your project, run:

beans init

This will create a .beans/ directory and a .beans.yml configuration file at the project root. All of it is meant to be tracked in your version control system.

From this point onward, you can interact with your Beans through the beans CLI. To get a list of available commands:

beans help

But more importantly, you'll want to get your coding agent set up to use it. Let's dive in!

Agent Configuration

The most basic way to teach your agent about Beans is to simply add the following instruction to your AGENTS.md, CLAUDE.md, or equivalent file:

**IMPORTANT**: before you do anything else, run the `beans prime` command and heed its output.

Some agents provide mechanisms to automate this step:

Claude Code

An official Beans plugin for Claude is in the works, but for the time being, please manually add the following hooks to your project's .claude/settings.json file:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "beans prime" }] }
    ],
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "beans prime" }] }
    ]
  }
}

OpenCode

Beans integrates with OpenCode via a plugin that injects task context into your sessions. To set it up, copy the plugin from .opencode/plugin/beans-prime.ts to your project's .opencode/plugin/ directory (or ~/.opencode/plugin/ for global availability across all projects).

Usage Hints