<2-3 sentences summarising what the project addresses and solves, the target audience, and the benefit.> Beans is a CLI-based issue tracker designed to store tasks, bugs, and features directly alongside project code using plain Markdown files. It aims to provide both human developers and AI coding agents with a unified, version-controlled view of project status, significantly enhancing agent capabilities by offering rich contextual data. The primary benefit is streamlined workflow integration and supercharged AI assistance for task management.

How It Works

Beans stores all task data in a .beans directory using plain Markdown files, making it easily version-controlled and human-readable. A CLI tool (beans) facilitates human interaction, while a built-in GraphQL query engine allows AI agents to precisely retrieve task information, minimizing token usage. Completed tasks are archived as "project memory," providing agents with historical context for future decision-making. This approach integrates task management directly into the development workflow, offering a novel way to leverage AI agents.

Quick Start & Requirements

Installation involves installing the beans CLI tool, either by downloading from the Releases section, using Homebrew (brew install hmans/beans/beans), or via Go (go install github.com/hmans/beans@latest). After installation, run beans init in your project root to create the .beans/ directory and configuration file. Agent integration requires adding specific instructions or plugins to your agent's configuration files (e.g., AGENTS.md, .claude/settings.json, OpenCode plugins). Go toolchain is a prerequisite for go install. An announcement trailer is available at https://github.com/user-attachments/assets/dbe45408-d3ed-4681-a436-a5e3046163da.

Highlighted Details

• Flat-file, Markdown-based issue tracking stored alongside code.
• AI agent-native design with a GraphQL query engine for context retrieval.
• "Project memory" feature archives completed tasks for agent context.
• Built-in TUI for terminal-based management and Markdown roadmap generation.

Maintenance & Community

The project is currently under heavy development and explicitly states it "does not accept contributions" at this early stage, though feedback via issues is encouraged. For questions or suggestions, users can reach out on Bluesky or open an issue in the repository.

Licensing & Compatibility

This project is licensed under the Apache-2.0 License, which is permissive and generally compatible with commercial use and closed-source linking.

Limitations & Caveats

Beans is explicitly marked as being "under heavy development," with potential for significant changes to features and APIs. Schema changes to the underlying data files may necessitate manual data migration steps, although agents can sometimes assist with this process. The project is not currently open for contributions.