beans

A file-based issue tracker for developers, product teams, and AI coding agents.

Beans stores work as Markdown files beside the code it describes. Humans, scripts, and coding agents share one Git-versioned source of truth instead of synchronizing a second task system.

This repository is an actively maintained independent fork of hmans/beans. It preserves the original local-first, agent-first idea and extends it for richer planning models, safer automation, and presentation-ready terminal workflows.

Install · Quick start · Choose a profile · Browse the documentation

Why this fork

Hannes' original beans project established the core idea: issues should be plain files that live with the repository and remain equally accessible to people and coding agents. This fork builds on that Apache-2.0 codebase with clear attribution to hmans/beans.

Real product work needed more than a flat task loop. This continuation adds configurable project profiles, richer planning types, scoped roadmaps, consistent terminal rendering, batch lifecycle commands, ordering and rename workflows, completion policies, worktree-aware storage, structured automation interfaces, and dedicated browser and terminal applications.

The goal is not to turn beans into a hosted project-management platform. Beans remains a small, inspectable data and workflow layer that composes with Git, shells, editors, coding agents, and optional user interfaces.

Read the fork lineage · Review compatibility and upgrading

Feature overview

Markdown-native issue tracking

• Store each bean as a Markdown file with structured YAML front matter.
• Review task changes with the same Git tools used for code.
• Keep active work and archived project memory readable without a service or proprietary export.
• Configure types, statuses, priorities, display rules, and lifecycle policies per repository.

Planning that fits the project

• Select a bundled classic, todo, simple, or complex profile at initialization.
• Model milestones or releases, thematic work, executable stories and tasks, bugs, and roadmap-excluded buckets.
• Connect work through parent, child, blocking, and blocked-by relationships.
• Order siblings explicitly without rewriting the complete store.

Human-readable terminal views

• Render list, milestones, and roadmap as trees or tables with a consistent visual language.
• Switch roadmap output between terminal presentation and portable Markdown.
• Scope roadmaps and progress reports to the part of the hierarchy that matters now.
• Preserve machine-readable JSON modes for scripts and agents.

Hierarchical list	Bean detail

Agent-native workflows

• Run beans prime to give a coding agent the current project's types, statuses, relationships, policies, and command contract.
• Use beans list --ready or beans next to select actionable work rather than merely open work.
• Query only the required fields through GraphQL and consume stable JSON output where supported.
• Validate configuration, links, front matter, and policies with beans check before automation proceeds.

Complete work lifecycle

• Create and inspect work with create, list, show, and next.
• Move work through start, complete, scrap, and archive.
• Organize work with update, tag, order, and cascading rename modes.
• Report plans and outcomes with roadmap, milestones, progress, and graph.

Explore every capability · Open the full command index

Choose a project profile

Profiles are expanded into the repository's .beans.yml when beans init --profile runs. Later releases do not silently replace that explicit project configuration.

classic

• Existing beans migration: retain the original milestone → epic → feature → task/bug hierarchy when adopting the fork.
• Milestone-driven software delivery: organize checkpoints into thematic epics, user-facing features, and executable work.

todo

• Markdown todo list: track a flat set of tasks without planning containers or hierarchy overhead.
• AI agent backlog: give a coding agent a small, unambiguous queue grouped through tags.

simple

• Small project roadmap: plan milestones while keeping possible future work in roadmap-excluded buckets.
• Feature and bug tracking: separate thematic epics and user-facing features from executable tasks and defects.

complex

• Release planning for product teams: group everything that ships together under an explicit release.
• Customer-value prioritization: distinguish new features, visible improvements, internal chores, demonstrable stories, bugs, and tasks.

Compare exact profile hierarchies and use cases

Installation

Pick the channel that matches your platform. All four install the same three binaries: beans (CLI), beans-serve (web UI and GraphQL API), beans-tui (terminal UI).

Homebrew (macOS)

brew install xRiErOS/beans/beans

Install script (Linux, macOS)

curl -fsSL https://raw.githubusercontent.com/xRiErOS/beans/main/install.sh | sh

go install (Linux, macOS, Windows)

go install github.com/xRiErOS/beans/cmd/beans@latest
go install github.com/xRiErOS/beans/cmd/beans-tui@latest

A beans-serve built this way has no embedded web assets (only a placeholder is tracked in the source tree) and serves 404 for the browser UI. Use Homebrew, the install script, or a release archive if you need beans-serve with the web UI.

Build from source

git clone https://github.com/xRiErOS/beans.git
cd beans

mise install
mise run setup
mise run build

install -d "$HOME/.local/bin"
install -m 755 beans beans-serve beans-tui "$HOME/.local/bin/"
export PATH="$HOME/.local/bin:$PATH"

beans version

Installation details and prerequisites

Quick start

Initialize a disposable project with the smallest profile and create the first ready task:

mkdir beans-demo
cd beans-demo

beans init --profile todo
beans create "Ship the first documented change" --type task --priority high --status todo
beans list --ready
beans next

Beans creates .beans.yml plus a .beans/ directory. Commit both with the repository so task history and code history travel together.

For a hierarchical roadmap, initialize simple or complex, create top-level planning containers, and connect executable work with --parent.

Follow the complete hierarchy-to-roadmap tutorial

Use beans with coding agents

The smallest portable integration is a repository instruction that makes the installed binary describe itself and the current project:

Before managing project work, run `beans prime` and follow its project-specific instructions.

beans prime is preferable to a copied command manual because its output reflects the repository's configured types, statuses, priorities, relationships, and completion policies. Agents can then use natural-language requests while operating through exact CLI or GraphQL contracts.

Examples of useful requests:

Inspect the ready beans and recommend the highest-value next action.

Create a bug for the failure you found, relate it to the affected feature, and mark it blocked by the root-cause task.

Summarize progress for the current release and identify incomplete descendants.

Configure Claude Code, OpenCode, and generic agents · Read the data model

Browser workspace with beans-serve

beans-serve runs the optional planning workspace and GraphQL service over the same .beans/ store used by the CLI. The browser offers backlog, board, and workspace views without introducing a second database.

beans-serve --beans-path .beans

Network binding, CORS, routes, and authentication posture matter before exposing the service beyond a local machine.

Configure the Web UI and API

Terminal interfaces

The fork still builds the original hmans terminal UI as the separate beans-tui compatibility binary. Active UI development does not continue inside that original TUI path.

The actively developed companion is xRiErOS/beans-tui, launched as bt: a separate keyboard-first, mouse-friendly Product Owner cockpit built on beans as its data layer. It adds a multi-repository lobby, tree and detail navigation, backlog workflows, search, filters, and full mutation support while beans remains the source of truth.

Understand the two TUI paths · Review all separate binaries

Full feature reference

The reference is grouped by user intent instead of reproducing one long beans --help block:

• Project setup: init, path, prime, version, help, completion.
• Inspection and search: list, show, next.
• Lifecycle: create, start, complete, scrap, archive, delete.
• Organization and relationships: update, tag, order, rename.
• Planning and reporting: roadmap, milestones, progress, graph.
• Querying and automation: graphql, JSON output, and structured errors.
• Validation and maintenance: check, integrity rules, and policies.
• Separate applications: beans-serve and beans-tui.

The installed binary remains authoritative for version-specific options:

beans --help
beans <command> --help
beans prime

Documentation

• Documentation index — route to every guide and reference page.
• Configuration reference — stores, anchors, profiles, custom types, display, and policies.
• Data model and file format — front matter, bodies, IDs, relationships, order, and archive.
• Compatibility and upgrading — assess changes and migrate deliberately.
• Troubleshooting — diagnose store discovery, ready work, policies, configuration, and server startup.

Project status

This is an actively maintained independent continuation of hmans/beans. Features and file-format contracts may still evolve; review the fork's commit history and compatibility guide before upgrading a shared store.

Focused pull requests are welcome at xRiErOS/beans. Include the observed behavior, expected behavior, beans version, and smallest reproducible store shape.

Acknowledgements

Beans was created by Hannes Müller in hmans/beans. This fork is possible because that work was released under the Apache License 2.0.

License

Licensed under the Apache License 2.0.