beans: an issue tracker that lives in your repository as Markdown

Tasks as Markdown files in a .beans directory

beans is described as a CLI based, flat-file issue tracker for humans and robots. Instead of tracking tasks in a separate application, beans stores them alongside your code, in a `.beans` directory, as plain old Markdown files.

The design decision is the whole idea. A task tracker that lives in the repository is diffable, reviewable in a pull request, and visible in the same history as the code it describes. There is no server to run, no account to create, and no API to rate limit. The readme's point about robots is that an agent reading and writing Markdown is doing something it already knows how to do.

The CLI covers the ordinary operations: create, list, view, update and archive beans. The human interface is a built-in terminal UI, described as a beautiful built-in TUI for browsing and managing beans from the terminal. There is also a `frontend/` directory and a `conductor.json` at the top level, so a web interface exists in the repository as well.

The implementation is Go, with `go.mod` requiring go 1.24.6. The dependency list gives a good picture of the internals. `github.com/99designs/gqlgen` is the GraphQL code generator, `github.com/blevesearch/bleve/v2` is a full text search index, `github.com/charmbracelet/bubbletea` with `bubbles`, `lipgloss` and `glamour` build the terminal UI, `github.com/spf13/cobra` provides the command structure, and `github.com/fsnotify/fsnotify` watches files so the tool reacts to changes on disk.

The licence is Apache-2.0 with the text in the LICENSE file, and the last push to the default branch was on 2026-04-06, with the newest release v0.4.2 published on 2026-03-10.

The GraphQL engine exists to keep agent token use down

The feature list explains that beans gives your robot friend full context about the project and its open tasks, and that a built-in GraphQL query engine allows the agent to get exactly the information it needs, keeping token use to a minimum.

That is a specific design goal rather than a generic one. An agent that reads a directory of Markdown files has to decide what to read, and the wrong decision costs tokens or misses state. A query engine lets the agent ask for exactly the fields it wants, in one request, and get exactly those fields back.

The repository supports that story. There is a `gqlgen.yml` configuration file, the generator is declared as a Go tool dependency so the schema can be regenerated, and `github.com/vektah/gqlparser/v2` is present for parsing. The `internal/` and `pkg/` directories hold the implementation, and `bleve` provides the search index behind the queries, which is why the project can answer questions like which beans match a term without scanning every file.

The interesting consequence is that beans is not only a storage format. It is a small local service surface with a typed query language over your task data, exposed to whatever agent you are running. For a project where the agent is the primary consumer of the tracker, that is the right shape.

beans prime is the handshake with the agent

Configuring the agent is the step the readme treats as the important one. The most basic approach is a single instruction added to your `AGENTS.md`, `CLAUDE.md` or equivalent file.

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

`beans prime` is what injects the context. The readme notes that since beans emits its own prompt instructions for the coding agent, most changes to the tool will just work without touching that instruction.

Some agents offer a way to automate the step, and the readme gives the concrete configuration for Claude Code. The official beans plugin for Claude is in the works, but for now it asks you to add hooks to your project's `.claude/settings.json` file.

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

Two hooks, at session start and before compaction. The second one matters more than it looks: compaction is where an agent loses detail, and re-priming before it happens is how the task context survives a long session.

For OpenCode the integration is a plugin file. The readme says to copy the plugin from `.opencode/plugin/beans-prime.ts` to your project's `.opencode/plugin/` directory, or to `~/.opencode/plugin/` for global availability across all projects. A global copy means every project you open gets a `beans prime` call, which is only useful if each of them is initialised with beans.

Installing the CLI and initialising a project

Installation has three steps according to the readme: install the `beans` CLI tool, configure your project to use it, and configure your coding agent to interact with it.

The CLI can be downloaded from the Releases section, installed with Homebrew, or installed directly through Go.

brew install hmans/beans/beans

go install github.com/hmans/beans@latest

Then inside the root directory of your project you initialise it.

beans init

That creates a `.beans/` directory and a `.beans.yml` configuration file at the project root. The readme is explicit that all of it is meant to be tracked in your version control system, which is consistent with the whole premise. The repository itself ships a `.beans/` directory and a `.beans.yml` at the top level, so you can see what a configured project looks like.

From there the CLI is self describing.

beans help

And the terminal UI is one command away.

beans tui

The Go install route needs the Go toolchain on the machine, while the Homebrew route packages a binary. Both land the same `beans` executable in your path.

Archived beans double as project memory

Completed beans are not deleted. They are archived and serve as project memory that the coding agent can query for context about past work.

That reframes the tracker. In a hosted tracker, closing an issue usually means the history becomes hard to reach, and a new contributor has no way to ask why a decision was made six months ago. Here the archive stays in the same searchable store as the open work, and the agent can query it.

The same data also produces a human artefact. beans generates a Markdown roadmap document for the project from its data, which gives a non technical reader a current view without needing the CLI or the agent.

The readme also suggests concrete things to ask an agent once the integration is in place. You can ask it to identify potential tasks and create beans for them, ask what to work on next, point it at a specific bean with an identifier such as `myproj-123`, or ask it to reorganise the beans into epics and milestones. You can also add project specific instructions such as including the relevant bean IDs in commit messages.

Those examples are the practical test of the design. If the agent can restructure your backlog into epics by writing Markdown files in a directory you can read and diff, the flat file approach is doing its job.

The data format can still change under you

The readme carries a stability warning that deserves to be read before anything is adopted. beans is still under heavy development, its features and APIs may still change significantly, and if you decide to use it now you should follow the release notes closely.

The reason is spelled out in the next paragraph. Since beans emits its own prompt instructions for the coding agent, most changes will just work. But sometimes the schema of the underlying data files is modified, and that may require manual migration steps. The readme's advice in that case is remarkably simple: your agent will often be able to migrate the data for you, given the instruction that the data format has changed and the project should be migrated.

The releases support that reading of the project's stage. Version 0.4.2 on 2026-03-10 sits on top of 0.4.0 from 2026-02-07 and 0.3.4 from 2025-12-25, all under a 0.x number, and the last push to the default branch was on 2026-04-06.

Two practical consequences. Pin the version if you depend on it, and read the release notes before upgrading rather than after. And if the project does not accept contributions yet, as the readme states, then when a schema change lands you are depending on one maintainer's migration path rather than on a community process.

Where beans is the wrong tool

The first case is a team that needs a hosted tracker with permissions. beans has no concept of users or roles in anything the documentation describes. It stores files, and anything that can read the repository can read the tasks. That is a feature in a single developer repository and a problem in an organisation where only some people should be able to close or reprioritise work.

The second case is where task data must live outside the repository. Some organisations require issue data in a system of record for audit, reporting or compliance reasons, and keeping it in Git means it is in the code history forever. beans cannot be pointed at an external tracker, since the tracker is the files.

The third case is the maturity question. The readme says the project does not accept contributions because it is too early, and it carries an explicit stability warning. For a personal tracker that is acceptable. For a company standard that other teams must rely on, the missing pieces are predictable ones: no notifications, no dashboards, no SLA or due date handling, no stable data format guarantee.

The fourth is scale and shape. The project assumes a flat directory of Markdown files and an agent that can query them. A backlog with tens of thousands of items, or one that needs custom fields and views, is a different kind of problem.

What beans does offer is rare: a tracker whose history is in the same commit graph as the code, and an agent that can treat the backlog as a queryable part of the repository instead of a web page to fetch.

Editorial conclusion

beans suits a solo developer or small team that wants tasks versioned next to the code and wants a coding agent to read and write them, and it is the wrong tool for an organisation that needs multi user permissions, notifications, a hosted dashboard or a stable data format. Before adopting it, read the release notes between the version you pin and the current one, since the readme warns that the underlying data file schema can change and require manual migration, and keep the `.beans` directory in version control as the readme instructs, because that directory is the only copy of the tracker.

Frequently asked questions

Official sources

1. hmans/beans on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases