hmans/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 ✨

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

As a human, you can get an overview of the CLI's functionalities by running:

beans help

You might specifically be interested in the interactive TUI:

beans tui

Example Workflows

But the real power of Beans comes from letting your coding agent manage your tasks for you.

Assuming you have integrated Beans into your coding agent correctly, it will already know how to create and manage beans for you. You can use the usual assortment of natural language inquiries. If you've just
added Beans to an existing project, you could try asking your agent to identify potential tasks and create beans for them:

Are there any tasks we should be tracking for this project? If so, please create beans for them.

If you already have some beans available, you can ask your agent to recommend what to work on next:

What should we work on next?

You can also specifically ask it to start working on a particular bean:

It's time to tackle myproj-123.

Consider that your agent will be just as capable to deal with beans as it is with code, so how about using it to quickly restructure your tasks?

Please inspect this project's beans and reorganize them into epics. Also please create 2-3 milestones to group these epics in a meaningful way.

You can also add Beans-specific instructions to your AGENTS.md, CLAUDE.md or equivalent file, for example:

When making a commit, include the relevant bean IDs in the commit message

Contributing

This project currently does not accept contributions -- it's just way too early for that!
But if you do have suggestions or feedback, please feel free to open an issue.

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

Getting in Touch

If you have any questions, suggestions, or just want to say hi, feel free to reach out to me on Bluesky, or open an issue in this repository.

{
  "name": "beans",
  "owner": {
    "name": "Beans - The CLI Issue Tracker for Humans and Robots",
    "email": "hendrik@mans.de"
  },
  "plugins": [
    {
      "name": "beans-prime",
      "source": "./extras/claude/plugins/beans-prime",
      "description": "Configure Claude Code to track work using Beans.",
      "version": "1.0.0"
    }
  ]
}