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 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: Features • **Track tasks, bugs, features**, and more right alongside your code. • **Plain old Markdown files** stored in a directory in your project. Easy to version control, readable and editable by humans and machines alike! • Use the 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: • Install the CLI tool. • Configure your project to use it. • Configure your coding agent to interact with it. Either download Beans from the Releases section, or install it via Homebrew: Alternatively, install directly via Go: Configure Your Project Inside the root directory of your project, run: This will create a directory and a 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 CLI. To get a list of available commands: 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 , , or equivalent file: 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 file: OpenCode Beans integrates with OpenCode via a plugin that injects task context into your sessions. To set it up, **copy the plugin** from to your project's directory (or for global availability across all projects). Usage Hints As a human, you can get an overview of the CLI's functionalities by running: You might specifically be interested in the interactive 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: If you already have some beans available, you can ask your agent to recommend what to work on next: You can also specifically ask it to start working on a particular bean: 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? You can also add Beans-specific instructions to your , or equivalent file, for example: 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.