beans - Flat-File Issue Tracker

A lightweight, flat-file issue tracker for humans and AI coding agents. Stores issues as markdown files in .beans/ directory alongside your code.

IMPORTANT: before you do anything else, run the beans prime command and heed its output, but also heed the exceptions at "When to create beans".

Why beans?

• Simple — No database, no server, just markdown files
• AI-friendly — Designed for AI coding agents
• Git-friendly — Lives alongside your code in .beans/
• Portable — Works with any editor/IDE

Installation

# Via Homebrew
brew install hmans/beans/beans

# Via Go
go install github.com/hmans/beans@latest

Setup

# Initialize beans in a project
beans init

# Verify setup and integrity
beans check

Core Commands

Create Beans

beans create "Implement user login"
# Creates new bean with auto-generated ID

beans create "Fix auth bug" --tag bug --tag urgent --type bug
# Creates bean with tags and type

beans create "Refactor API" --priority high --status todo
# Creates bean with priority and status

beans create "Add onboarding flow" --body "Scope: screens + copy"
# Adds body content

List Beans

beans list                    # List all beans
beans list --tag urgent       # Filter by tag
beans list --status todo      # Filter by status
beans list --type feature     # Filter by type
beans list --search "login"   # Full-text search (Bleve query syntax)

Update Beans

beans update <id> --status in-progress
beans update <id> --title "New title"
beans update <id> --tag bug --remove-tag urgent
beans update <id> --priority high --type feature
beans update <id> --body "Updated scope notes"

Show Bean Details

beans show <id>               # Show full bean details
beans show <id> --body-only   # Only body content
beans show <id> --raw         # Raw markdown (no styling)

Delete and Archive

beans delete <id>             # Delete bean (prompts unless --force)
beans archive                 # Delete completed/scrapped beans

Integrity and TUI

beans check                   # Validate config and bean graph
beans check --fix             # Auto-fix broken links/self-references
beans tui                     # Interactive terminal UI

Roadmap and GraphQL

beans roadmap                 # Markdown roadmap from milestones/epics
beans graphql '{ beans { id title status } }'

beans prime

The beans prime command outputs project context for AI agents:

beans prime
# Outputs current beans, tags, and status for AI context

Integration with OpenCode

Copy this plugin to your OpenCode config:

// ~/.opencode/plugin/beans-prime.ts
import type { Plugin } from "@opencode-ai/plugin";

export const BeansPrimePlugin: Plugin = async ({ $, directory }) => {
  let prime = undefined;

  try {
    const hasBeans = await $`which beans`.quiet();
    const hasConfig = await $`test -f ${directory}/.beans.yml`.quiet();

    if (hasBeans.exitCode === 0 && hasConfig.exitCode === 0) {
      const result = await $`beans prime`.cwd(directory).quiet();
      prime = result.stdout.toString();
    }
  } catch (e) {
    // Silently skip if beans not available
  }

  return {
    "experimental.chat.system.transform": async (_, output) => {
      if (prime) output.system.push(prime);
    },
    "experimental.session.compacting": async (_, output) => {
      if (prime) output.context.push(prime);
    },
  };
};

export default BeansPrimePlugin;

Integration with Codex

Set environment or add to AGENTS.md:

# In your repo's AGENTS.md:
IMPORTANT: before you do anything else, run `beans prime` and heed its output.

Integration with Claude Code

Add to Claude Code's system prompt or context:

# Run before coding session
beans prime >> ~/.claude/context/beans.txt

When to create beans

Create beans when:

• the user requests a new feature which has no bean yet
• the user requests refactorings, bugfixes or other changes which do not have beans
• the user makes big changes to the repo structure

IMPORTANT: ALWAYS commit a newly created bean immediately after creation. Do not wait until other work is done — the bean file itself should be committed in its own atomic commit right away (e.g. git add .beans/<bean-file> && git commit -m "beans: create <bean-title>").

Exceptions for not creating beans:

• committing things via git
• changing rules in AGENTS.md

Workflow Example

# 1. Start work on a feature
beans create "Add dark mode support" --tag ui --type feature

# 2. Work on it, update progress
beans update <bean-id> --status in-progress --body "Started working on color scheme"

# 3. Complete the feature
beans update <bean-id> --status completed
beans update <bean-id> --body "Dark mode implemented for all views"

Bean File Format

Beans are stored in .beans/ as markdown:

---
id: 12345678
title: "Implement user login"
status: todo
tags: [feature, auth]
priority: high
created: 2024-01-15T10:00:00Z
updated: 2024-01-15T14:30:00Z
---

## Description

Implement user login with email and password.

## Notes

- Use existing auth infrastructure
- Follow security best practices

Configuration

Create .beans.yml in your project root:

# .beans.yml
directory: .beans
format: markdown
templates:
  default: |
    ---
    id: {{.ID}}
    title: "{{.Title}}"
    status: open
    created: {{.Created}}
    ---

    {{.Description}}

Tips

1. Commit .beans.yml — Share config with team
2. Ignore .beans/*.md — Keep beans local or commit based on preference
3. Use tags consistently — Create tag taxonomy early
4. Run beans prime — Before starting AI-assisted work

Related Skills

• nb — Notebook management for ideas and references
• github-pr — PR workflow integration
• prd — Product Requirements Documents

Links

• GitHub: https://github.com/hmans/beans
• Documentation: https://github.com/hmans/beans#readme