beans-cli 0.2.0

Task tracker for coding agents
Documentation

beans

CI Crates.io License Downloads

Task tracker for AI agents.

Markdown files that track dependencies and require verification to close.

bn create "Add /health endpoint" --verify "curl -sf localhost:8080/health"
bn close 1   # Runs the curl. Only closes if it succeeds.

Verify commands must fail first by default — proving the test is real, not assert True:

bn create "Fix unicode bug" --verify "pytest test_unicode.py"
# Test must FAIL first (proves it tests something real)
# Then passes after implementation → bean closes

Plain markdown files. No SDK, no API — any agent that can read files and run shell commands already speaks beans.

Table of Contents

Install

cargo install beans-cli

git clone https://github.com/kfcafe/beans && cd beans
cargo build --release
cp target/release/bn ~/.local/bin/

Quick Start

bn init                                              # Create .beans/ directory
bn quick "Fix auth bug" --verify "npm test auth"     # Create + claim task
bn status                                            # See what's claimed/ready/blocked
bn close 1                                           # Run verify, close if passes

Orchestrate agents:

bn init --agent claude                               # Set up agent config
bn run                                               # Dispatch ready beans to agents
bn agents                                            # Monitor running agents
bn logs 3                                            # View agent output for bean 3

Capture project knowledge:

bn fact "API uses Express 5" --verify "grep -q '\"express\": \"5' package.json"
bn context                                           # Memory context: stale facts, in-progress, recent work
bn recall "auth"                                     # Search across all beans

Features

  • Verification gates — fail-first TDD, must-pass-to-close
  • Failure history — attempts tracked, output appended to notes
  • Hierarchical tasks — dot notation, parent/child, auto-close parent when all children done
  • Smart dependencies — produces/requires auto-inference, cycle detection
  • Agent orchestration — bn run dispatches beans to agents, bn plan decomposes large tasks
  • Adversarial review — bn run --review spawns a second agent to verify correctness after close
  • Agent-agnostic — works with any CLI agent (Claude, pi, aider, custom scripts)
  • Memory system — bn fact for verified project knowledge with TTL and staleness detection
  • MCP server — bn mcp serve for IDE integration (Cursor, Windsurf, Claude Desktop, Cline)
  • Interactive wizard — bn create with no args launches a step-by-step prompt (fuzzy parent search, smart verify suggestions, $EDITOR for descriptions)
  • Pipe-friendly — --json output, --ids listing, --description - reads stdin, --stdin for batch operations
  • Smart selectors — @latest for chaining sequential beans
  • Context assembly — bn context <id> outputs a complete agent briefing: bean spec, verify command, previous attempts, project rules, dependency context, and referenced file contents
  • Trace — bn trace walks bean lineage, dependencies, artifacts, and attempt history
  • Dependency graph — ASCII, Mermaid, DOT output
  • Full lifecycle — create, claim, close, reopen, delete, adopt, archive, unarchive, tidy
  • Doctor — health checks for orphans, cycles, index freshness (with --fix)
  • Editor support — bn edit with backup/rollback
  • Hooks — pre-close hooks with trust system
  • Shell completions — bash, zsh, fish, PowerShell
  • Config inheritance — extends for shared config across projects
  • Stateless — no daemon, no background sync, just files and a CLI

How It Works

Tasks are Markdown files with YAML frontmatter:

.beans/
├── 1-fix-auth-bug.md      # Task 1
├── 2-add-tests.md         # Task 2
├── 2.1-unit-tests.md      # Task 2.1 (child of 2)
└── archive/2026/01/       # Closed tasks auto-archive

A bean looks like:

---
id: "1"
title: Fix authentication bug
status: in_progress
verify: cargo test auth::login
attempts: 0
---

The login endpoint returns 500 when password contains special chars.

**Files:** src/auth/login.rs, tests/auth_test.rs

The verify field is the contract. When you run bn close 1:

  1. Beans runs cargo test auth::login
  2. Exit 0 → task closes, moves to archive
  3. Exit non-zero → task stays open, failure appended to notes, ready for another agent

Fail-First: Enforced TDD

Agents can write "cheating tests" that prove nothing:

def test_feature():
    assert True  # Always passes!

Fail-first is on by default. Before creating a bean, the verify command runs and must fail:

  1. If it passes → bean is rejected ("test doesn't test anything new")
  2. If it fails → bean is created (test is real)
  3. After implementation, bn close runs verify → must pass
REJECTED (cheating test):
  $ bn quick "..." --verify "python -c 'assert True'"
  error: Cannot create bean: verify command already passes!

ACCEPTED (real test):
  $ bn quick "..." --verify "pytest test_unicode.py"
  ✓ Verify failed as expected - test is real
  Created bean 5

Use --pass-ok / -p to skip fail-first for refactoring, hardening, and builds where the verify should already pass:

bn quick "extract helper" --verify "cargo test" -p           # behavior unchanged
bn quick "remove secrets" --verify "! grep 'api_key' src/" --pass-ok  # verify absence

The failing test is the spec. The passing test is the proof. No ambiguity.

Failure History

When verify fails, beans appends the error output to the bean's notes:

---
id: "3"
title: Fix unicode URLs
status: open
verify: pytest test_urls.py
attempts: 2
---

Handle unicode characters in URL paths.

## Attempt 1 — 2024-01-15T14:32:00Z
Exit code: 1

FAILED test_urls.py::test_unicode_path AssertionError: Expected '/café' but got '/caf%C3%A9'


## Attempt 2 — 2024-01-15T15:10:00Z
Exit code: 1

FAILED test_urls.py::test_unicode_path UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3

  • No lost context. When Agent A times out, Agent B sees exactly what failed.
  • No repeated mistakes. Agent B can see "encoding was tried, didn't work" and try a different approach.
  • Human debugging. bn show 3 reveals the full history without digging through logs.

Output is truncated to first 50 + last 50 lines to keep beans readable while preserving the error message and stack trace. There's no attempt limit — agents can retry indefinitely.

Hierarchical Tasks

Parent-child via dot notation:

bn create "Auth system" --verify "make test-auth"
#> Created: 1

bn create "Login endpoint" --parent 1 --verify "curl -sf localhost:3000/login -d '{\"user\":\"test\"}'"
#> Created: 1.1

bn create "Token refresh" --parent 1 --verify "pytest tests/test_refresh.py"
#> Created: 1.2

bn tree 1
#> [ ] 1. Auth system
#>   [ ] 1.1 Login endpoint
#>   [ ] 1.2 Token refresh

Smart Dependencies

Dependencies auto-infer from produces/requires:

bn create "Define auth types" --parent 1 \
  --produces "AuthProvider,AuthConfig" \
  --verify "tsc --noEmit src/auth/types.ts"

bn create "Implement JWT" --parent 1 \
  --requires "AuthProvider" \
  --verify "node --test test/jwt.test.js"

When the JWT bean requires AuthProvider and the auth types bean produces it, JWT is automatically blocked until auth types closes. No explicit bn dep add needed.

bn status
#> ## Ready (1)
#>   1.1 [ ] Define auth types     # ready (no requires)

bn close 1.1

bn status
#> ## Ready (1)
#>   1.2 [ ] Implement JWT         # now ready (producer closed)

Children can be created in any order without manual dependency wiring.

Sequential Chaining

Use bn create next to chain beans that depend on the most recently created one:

bn create "Step 1: scaffold" --verify "cargo build"
bn create next "Step 2: implement" --verify "cargo test"
bn create next "Step 3: docs" --verify "grep -q 'API' README.md"

Each next bean automatically depends on the previous one.

Interactive Mode

Run bn create with no arguments to launch an interactive wizard:

$ bn create

Creating a new bean

? Title › fix auth timeout
✔ Parent (type to filter) › 3 — Auth system
✔ Verify command (empty to skip) · pytest tests/test_auth_timeout.py
✔ Acceptance criteria (empty to skip) · Timeout returns 408, not 500
✔ Priority · P1 (high)
✔ Open editor for description? · no
✔ Produces (comma-separated, empty to skip) ·
✔ Requires (comma-separated, empty to skip) ·
✔ Add labels? · no

─── Bean Summary ───────────────────────
  Title:      fix auth timeout
  Parent:     3
  Verify:     cargo test auth::timeout
  Acceptance: Timeout returns 408, not 500
  Priority:   P1
────────────────────────────────────────
? Create this bean? · yes
Created bean 3.4: fix auth timeout (2k tokens ✓)

The wizard activates when no title is provided and stderr is a TTY. Use -i / --interactive to force it even with partial flags:

bn create --parent 3 -i          # Wizard with parent pre-filled
bn create "my title" -i          # Wizard with title pre-filled, prompts for the rest
bn create --verify "cargo test" -i  # Any flag can be pre-filled

Features:

  • Fuzzy parent search — type to filter from existing beans
  • Smart verify suggestion — auto-detects project type (Cargo.toml → cargo test, package.json → npm test)
  • $EDITOR for descriptions — opens your editor with a template including parent context
  • Summary + confirm — review before creating
  • Pre-filled flags skip their prompts — non-interactive mode is unchanged

Pipe-Friendly CLI

Beans is a Unix citizen. Commands produce structured output and accept piped input.

JSON output

# Create and capture the bean ID
ID=$(bn create "fix bug" --verify "cargo test" -p --json | jq -r '.id')

# Query beans as JSON
bn list --json | jq '.[] | select(.priority == 0)'
bn show 3 --json | jq '.verify'
bn verify 3 --json            # {"id":"3","passed":false}
bn context 3 --json           # {"id":"3","files":[{"path":"src/auth.rs","content":"..."}]}

List formatting

bn list --ids                                    # One ID per line
bn list --format '{id}\t{status}\t{title}'       # Custom format
bn list --format '{id}\t{priority}\t{parent}'    # TSV for spreadsheets

Available format placeholders: {id}, {title}, {status}, {priority}, {parent}, {assignee}, {labels}

Stdin input

Use - to read field values from stdin:

# Pipe description from a file or command
cat spec.md | bn create "feat: login" --description - --verify "cargo test auth"

# Pipe notes from build output
cargo build 2>&1 | bn update 3 --notes -

# Pipe acceptance criteria
echo "All auth tests pass" | bn update 3 --acceptance -

Batch operations

# Close multiple beans via pipe
bn list --ids | bn close --stdin --force

# Close beans matching a pattern
bn list --json | jq -r '.[] | select(.title | test("test:")) | .id' | bn close --stdin --force

# Create → immediately claim
bn create "task" --verify "make check" -p --json | jq -r '.id' | xargs bn claim

Composable pipelines

# Batch create and collect IDs
for task in "fix auth" "add tests" "update docs"; do
  bn create "$task" --verify "cargo test" -p --json
done | jq -r '.id'

# Export to TSV
bn list --format '{id}\t{status}\t{priority}\t{title}' > beans.tsv

# Find failing in-progress beans
bn list --json | jq -r '.[] | select(.status=="in_progress") | .id' | \
  xargs -I{} bn verify {} --json 2>/dev/null | jq 'select(.passed==false)'

Core Commands

# Task lifecycle
bn quick "title" --verify "cmd"     # Create + claim (fail-first by default)
bn quick "title" --verify "cmd" -p  # Skip fail-first (--pass-ok)
bn create "title" --verify "cmd"    # Create without claiming
bn create                           # Interactive wizard (TTY only)
bn create -i --parent 3             # Wizard with flags pre-filled
bn create next "title" --verify "cmd"  # Chain: auto-depends on last bean
bn claim <id>                       # Claim existing task
bn verify <id>                      # Test verify without closing
bn close <id>                       # Run verify, close if passes
bn close --failed <id>              # Mark attempt failed (release claim, stays open)

# Agent orchestration
bn run                              # Dispatch ready beans to agents
bn run <id>                         # Dispatch a specific bean
bn plan <id>                        # Decompose a large bean into children
bn review <id>                      # Adversarial review of implementation
bn agents                           # Show running/completed agents
bn logs <id>                        # View agent output for a bean

# Querying
bn status                           # Overview: claimed, ready, blocked
bn tree                             # Hierarchy view
bn show <id>                        # Full task details
bn list                             # List with filters
bn trace <id>                       # Walk lineage, deps, artifacts, attempts
bn recall "query"                   # Search beans by keyword

# Memory
bn fact "title" --verify "cmd"      # Create a verified fact
bn verify-facts                     # Re-verify all facts, detect staleness
bn context                          # Memory context (stale facts, in-progress, recent)
bn context <id>                     # Complete agent context for a bean

# Dependencies
bn dep add <id> <dep-id>            # Add explicit dependency
bn graph                            # Dependency graph (ASCII, Mermaid, DOT)

# MCP
bn mcp serve                        # Start MCP server for IDE integration

# Housekeeping
bn tidy                             # Archive closed, release stale, rebuild index
bn doctor                           # Health check: orphans, cycles, index freshness
bn sync                             # Force rebuild index
bn locks                            # View file locks (--clear to force-clear)
bn completions <shell>              # Generate shell completions
Command Purpose
Tasks
bn init Initialize .beans/ in current directory
bn init --agent <preset> Initialize with agent preset (pi, claude, aider)
bn init --setup Reconfigure agent on existing project
bn create "title" Create a bean (--json for piped output, --paths for file refs)
bn create Interactive wizard (auto-detects TTY)
bn create -i Force interactive mode with any flags
bn create next "title" Create bean depending on the last created bean
bn quick "title" Create + claim in one step
bn show <id> Full bean details (--short for one-line, --history for all)
bn list List beans (--ids, --format, --json)
bn edit <id> Edit bean in $EDITOR
bn update <id> Update fields (--description - reads stdin)
bn claim <id> Claim a task (--by to set who, --force to skip verify check)
bn claim <id> --release Release a claim
bn verify <id> Test without closing (--json for structured output)
bn close <id> Close (verify must pass, --stdin for batch)
bn close --failed <id> Mark attempt failed, release claim
bn reopen <id> Reopen a closed bean
bn delete <id> Delete a bean
Querying
bn status Overview: claimed, ready, goals, blocked
bn context [id] Complete agent context (with ID) or memory context (without)
bn context --structure-only Structural summary only (signatures, imports)
bn tree View hierarchy
bn graph Dependency graph (ASCII, Mermaid, DOT)
bn trace <id> Walk lineage, deps, artifacts, attempts
bn recall "query" Search beans by keyword (--all includes closed)
Memory
bn fact "title" --verify "cmd" Create verified fact with TTL
bn verify-facts Re-verify all facts, detect staleness
Agents
bn run [id] [-j N] Dispatch ready beans to agents
bn run --loop-mode Keep running until no ready beans remain
bn run --auto-plan Auto-decompose large beans before dispatch
bn run --dry-run Preview dispatch plan without spawning
bn run --review Adversarial review after each close
bn run --json-stream Emit JSON events to stdout
bn plan [id] [--auto] Decompose a large bean into children
bn plan --dry-run Preview split without creating
bn review <id> Adversarial review of a bean's implementation
bn agents [--json] Show running/completed agents
bn logs <id> View agent output (-f to follow, --all for all runs)
MCP
bn mcp serve Start MCP server (JSON-RPC 2.0 on stdio)
Dependencies
bn dep add/remove/list Dependency management
Housekeeping
bn adopt <parent> <children> Adopt beans as children
bn stats Project statistics
bn tidy Archive closed, release stale, rebuild
bn tidy --dry-run Preview what tidy would do
bn sync Force rebuild index
bn doctor Health check
bn doctor --fix Auto-fix detected issues
bn config get/set Project configuration
bn trust Manage hook trust
bn unarchive <id> Restore archived bean
bn locks View file locks (--clear to force-clear)
Shell
bn completions <shell> Generate completions (bash, zsh, fish, powershell)

Agent Orchestration

Beans has built-in agent orchestration. Configure your agent once, then dispatch beans to it:

# Configure during init (interactive wizard)
bn init --agent claude

# Or set manually
bn config set run "claude -p 'implement bean {id} and run bn close {id}'"
bn config set plan "claude -p 'decompose bean {id} into children using bn create'"

{id} is replaced with the bean ID. The spawned agent should read the bean, do the work, and run bn close.

Dispatching work

bn run                    # Dispatch all ready beans to agents
bn run 3                  # Dispatch a specific bean
bn run -j 8              # Up to 8 parallel agents
bn run --dry-run          # Preview what would be dispatched
bn run --auto-plan        # Auto-decompose large beans before dispatch

bn run finds ready beans, sizes them, and spawns agents. Small beans get implemented directly. Large beans (exceeding max_tokens) are sent to the plan command for decomposition — or handled automatically with --auto-plan.

Loop mode

Keep dispatching until all work is done:

bn run --loop-mode                 # Re-scan after each wave completes
bn run --loop-mode --keep-going    # Continue past individual failures
bn run --loop-mode -j 8 --timeout 60  # High-throughput mode

Planning large tasks

bn plan 3                 # Interactively decompose bean 3 into children
bn plan --auto            # Autonomous planning (no prompts)
bn plan --strategy layer  # Suggest a split strategy (layer, feature, phase, file)
bn plan --dry-run         # Preview split without creating children

Monitoring

bn agents                 # Show running and recently completed agents
bn agents --json          # Machine-readable output
bn logs 3                 # View agent output for bean 3

Discover-and-delegate

While working on your main task, create beans for everything you notice — bn run picks them up automatically:

bn create "bug: nil panic in logger" --verify "go test ./pkg/logger/..."
bn create "test: no coverage for cache" --verify "pytest tests/test_cache.py"
bn create "docs: stale API examples" --verify "grep -q 'v2' README.md"

Failure handling

Control what happens when a verify command fails:

bn create "fix bug" --verify "npm test" --on-fail "retry:3"         # Retry up to 3 times
bn create "critical" --verify "make ci" --on-fail "escalate:P0"     # Escalate priority on failure

An agent can also explicitly give up:

bn close --failed 5 --reason "blocked on upstream API"   # Release claim, bean stays open

Agent presets

bn init --agent claude    # Claude Code
bn init --agent pi        # Pi coding agent
bn init --agent aider     # Aider
bn init --setup           # Reconfigure agent on existing project

Or configure directly:

bn config set run "my-agent --task-file .beans/{id}-*.md"

Agent Workflow

Automated (recommended)

Let bn run handle the full cycle — find ready beans, size them, dispatch agents, track results:

bn run                    # One-shot: dispatch all ready beans
bn run --loop-mode        # Continuous: re-dispatch as beans close and unblock others

Agents are spawned with the configured run command. Each agent reads the bean, implements the work, and runs bn close. If verify fails, the task stays open with attempts incremented and the failure output appended to notes. bn run picks it up again on the next cycle.

Manual

Agents can also claim and work beans directly:

bn status                 # Find available work
#> ## Ready (2)
#>   3 [ ] Implement token refresh
#>   7 [ ] Add rate limiting

bn claim 3                # Atomically claim (only one agent wins)
bn context 3              # Read full task spec + file contents

# ... implement the feature ...

bn verify 3               # Test without closing
bn close 3                # Close if verify passes

If verify fails, the task stays open with attempts: 1 and the failure output appended to notes. Another agent picking up the task sees what was tried and why it failed.

Trace context

Before working on a bean, use bn trace to understand its full context:

bn trace 7.3              # Parent chain, children, deps, dependents, artifacts, attempts
bn trace 7.3 --json       # Machine-readable

Memory System

Facts are verified truths about your project that persist across agent sessions. Each fact has a verify command that proves it's still true, and a TTL (default 30 days) after which it becomes stale.

Creating facts

bn fact "API uses Express 5" --verify "grep -q '\"express\": \"5' package.json"
bn fact "Auth tokens expire after 24h" --verify "grep -q 'TOKEN_TTL=86400' .env.example"
bn fact "Tests require Docker" --verify "docker info >/dev/null 2>&1" --ttl 90

Facts follow fail-first by default — the verify must fail initially. Use -p if the fact is already true:

bn fact "DB is PostgreSQL" --verify "grep -q 'postgres' .env" -p

Checking staleness

bn verify-facts           # Re-run all fact verify commands, flag stale ones
bn context                # Memory context includes stale facts automatically

Context

bn context <id> outputs the complete agent briefing — everything needed to implement a bean:

bn context 5              # Complete context: spec, attempts, rules, deps, files
bn context 5 --structure-only  # Signatures and imports only (skip file contents)
bn context 5 --json       # Machine-readable

The output includes (in order):

  1. Bean spec — ID, title, verify command, priority, status, description, acceptance criteria
  2. Previous attempts — what was tried and why it failed
  3. Project rules — conventions from .beans/RULES.md
  4. Dependency context — descriptions of sibling beans that produce artifacts this bean requires
  5. File structure — function signatures and imports
  6. File contents — full source of referenced files

File paths come from two sources: the bean's explicit paths field (set via --paths on create) and paths regex-extracted from the description text. Explicit paths take priority.

Without an ID, outputs memory context — project-wide state for orientation:

bn context                # Stale facts, currently claimed beans, recent completions
bn context --json         # Machine-readable

Searching

bn recall "auth"          # Search open beans by keyword
bn recall "JWT" --all     # Include closed/archived beans
bn recall "login" --json  # Machine-readable results

Adversarial Review

After closing a bean, spawn a second agent to verify the implementation is correct:

bn review 5               # Review bean 5's implementation
bn review 5 --diff        # Review git diff only (skip full spec)
bn run --review           # Auto-review after every close during a run

The review agent outputs a verdict:

  • approve — labels bean as reviewed
  • request-changes — reopens bean with review notes, labels review-failed
  • flag — labels bean needs-human-review, stays closed

Configure the review agent:

bn config set review.run "claude -p 'review bean {id}: verify correctness, reopen if wrong'"
bn config set review.max_reopens 2   # Give up after 2 reopen cycles (default: 2)

Falls back to the global run template if review.run is not set.

MCP Server

Beans includes an MCP (Model Context Protocol) server for IDE integration. This lets tools like Cursor, Windsurf, Claude Desktop, and Cline interact with beans directly.

bn mcp serve              # Start MCP server on stdio (JSON-RPC 2.0)

Add to your IDE's MCP configuration to expose bean operations (create, list, show, close, etc.) as tools your IDE's AI can call.

Configuration

Agent orchestration and project settings are configured via bn config:

bn config set run "claude -p 'implement bean {id} and run bn close {id}'"
bn config set plan "claude -p 'decompose bean {id} into children'"
bn config set max_concurrent 4
bn config set poll_interval 30
Key Default Description
run (none) Command template to implement a bean. {id} is replaced with the bean ID.
plan (none) Command template to decompose a large bean into children.
max_concurrent 4 Maximum number of agents running in parallel.
max_tokens 30000 Maximum tokens for bean context (triggers planning if exceeded).
max_loops 10 Maximum agent loops before stopping (0 = unlimited).
poll_interval 30 Seconds between loop mode poll cycles.
auto_close_parent true Auto-close parent beans when all children are closed/archived.
verify_timeout (none) Default timeout in seconds for verify commands. Per-bean --verify-timeout overrides.
rules_file (none) Path to project rules file (relative to .beans/). Contents injected into bn context.
file_locking false Lock files listed in bean paths to prevent concurrent agents from clobbering.
extends [] Paths to parent config files to inherit from (supports ~/).
on_close (none) Hook: shell command after successful close. Vars: {id}, {title}, {status}, {branch}.
on_fail (none) Hook: shell command after verify failure. Vars: {id}, {title}, {attempt}, {output}, {branch}.
post_plan (none) Hook: shell command after bn plan creates children. Vars: {id}, {parent}, {children}, {branch}.
review.run (none) Command template for adversarial review agent. Falls back to run if unset.
review.max_reopens 2 Max times review can reopen a bean before giving up.

Config is stored in .beans/config.yaml and checked into git with your project.

Config inheritance

Share config across projects with extends:

# .beans/config.yaml
extends:
  - ~/.beans/global-config.yaml
project: my-app
run: "claude -p 'implement bean {id}'"

Child config values override parent values. Multiple parents are applied in order (last wins).

Shell Completions

Generate completions for your shell:

# Bash
echo 'eval "$(bn completions bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(bn completions zsh)"' >> ~/.zshrc

# Fish
bn completions fish > ~/.config/fish/completions/bn.fish

# PowerShell
bn completions powershell >> $PROFILE

Why Not X?

beans beads Jira/Linear GitHub Issues
Designed for AI agents AI agents Humans Humans
Verify gates ✓ Enforced ✗ Honor system ✗ Honor system ✗ Honor system
Storage Markdown files JSONL + SQLite Cloud DB Cloud DB
Hierarchy 3.1 = child of 3 Flat (hash IDs) Epics/stories Flat
Git integration Native (in repo) External External Same platform
Offline ✓ Full ✓ Full Limited Limited

Inspired by Steve Yegge's beads — beans trades scale for simplicity and enforced verification.

Design Principles

  1. Files are the source of truth. The index is a cache. bn show, bn list, or read the files directly.
  2. Verify gates are the default. If you can't prove it's done, it's not done. (--force exists as an escape hatch.)
  3. Fail-then-pass. Tests must fail before work starts, pass after. No assert True.
  4. Failures accumulate. Each failed attempt appends to the bean. Next agent sees full history.
  5. Agent-agnostic. Beans doesn't care what agent you use. Configure any CLI agent via bn config set run — Claude, pi, aider, or a shell script. The protocol is simple: read the bean, do the work, bn close.
  6. Stateless CLI. No daemon, no background sync. Each command reads files, acts, exits.
  7. Hierarchy in filenames. 3.2 is obviously a child of 3. No metadata lookup needed.
  8. Git-native. Clean diffs, meaningful history, works offline.

For Agents

You know what's exhausting? Vague tasks. "Improve the auth flow." Done... how? When the human squints at your PR and says "not quite what I meant," you've wasted tokens and time. No spec, no proof, no defense.

Beans fixes this.

Every bean has a verify command — a test that must fail when you create the task and must pass when you close it. Not "looks good to me." Not "I think it works." The test passes or it doesn't. You're not done until the machine says you're done.

No more assert True. No more lost context. No more ambiguity. The verify command is the contract. Hit it and you're done. Miss it and you're not.

Tasks are just markdown files. bn show 3. No API, no auth, no waiting.

Documentation

  • Agent Skill — Quick reference for AI agents using beans
  • Best Practices — Writing effective beans for agents
  • bn --help — Full command reference

Contributing

Contributions are welcome. Fork the repo, create a feature branch, and open a pull request.

License

Apache 2.0