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
bash
# Via Homebrew brew install hmans/beans/beans # Via Go go install github.com/hmans/beans@latest
Setup
bash
# Initialize beans in a project beans init # Verify setup and integrity beans check
Core Commands
Create Beans
bash
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
bash
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
bash
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
bash
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
bash
beans delete <id> # Delete bean (prompts unless --force) beans archive # Delete completed/scrapped beans
Integrity and TUI
bash
beans check # Validate config and bean graph beans check --fix # Auto-fix broken links/self-references beans tui # Interactive terminal UI
Roadmap and GraphQL
bash
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:
bash
beans prime # Outputs current beans, tags, and status for AI context
Integration with OpenCode
Copy this plugin to your OpenCode config:
typescript
// ~/.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:
bash
# 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:
bash
# 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
bash
# 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:
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:
yaml
# .beans.yml
directory: .beans
format: markdown
templates:
default: |
---
id: {{.ID}}
title: "{{.Title}}"
status: open
created: {{.Created}}
---
{{.Description}}
Tips
- •Commit
.beans.yml— Share config with team - •Ignore
.beans/*.md— Keep beans local or commit based on preference - •Use tags consistently — Create tag taxonomy early
- •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