bon

Bon

Lightweight work tracker for Claude-human collaboration using GTD vocabulary.

Bon organizes work as Outcomes (desired results) and Actions (concrete next steps). No sprints, no story points — just ordering and a clear answer to "what can I work on now?"

Status

Robustness: Stable — used daily Works with: Any agent, standalone CLI Install: uv tool install . Requires: Python 3.11+

Install

git clone https://github.com/spm1001/bon.git
cd bon
uv tool install .

This installs bon globally — available from any directory. To develop bon itself, also run uv sync for the dev dependencies (pytest, ruff).

Updating

uv tool install copies the package — edits to source aren't reflected until you re-install:

bon update          # re-installs from source

Or manually: uv tool install ~/Repos/bon.

Note: uv tool install doesn't support editable mode (-e) yet. When uv adds this, the update step goes away.

Quick Start

# Initialize in your project
bon init

# Create an outcome (desired result) — pipe JSON to stdin
cat <<'EOF' | bon new -q
{
  "title": "Users can export data",
  "brief": {
    "why": "Users requesting CSV exports",
    "what": "1. Export button in toolbar 2. CSV generation 3. Download endpoint",
    "done": "Can export any table to CSV"
  }
}
EOF

# Add an action under that outcome
cat <<'EOF' | bon new -q
{
  "title": "Add export button to toolbar",
  "parent": "bon-abcdef",
  "brief": {
    "why": "Entry point for export flow",
    "what": "Button in toolbar, opens format picker",
    "done": "Button visible, click opens modal"
  }
}
EOF

# File a standalone action (field report, one-off fix)
cat <<'EOF' | bon new -q
{
  "type": "action",
  "title": "Field Report: CSV encoding broken on non-ASCII",
  "brief": {
    "why": "Japanese characters produce mojibake in exports",
    "what": "Diagnose encoding, fix or file under outcome",
    "done": "Non-ASCII exports render correctly"
  }
}
EOF

# See what's ready
bon list --ready

# Mark done when complete
bon done bon-ghijkl

Flags work too for quick stubs: bon new "Fix typo" --why w --what x --done d -q

Commands

Command	Description
init [--prefix P] [--backend {jsonl|dolt}]	Initialize .bon/ directory
new [TITLE] [--outcome PARENT] --why W --what X --done D	Create outcome or action (JSON stdin or flags)
list [--ready|--waiting|--all] [--limit N]	Show items hierarchically
show ID [--current]	View item details and brief
done ID	Mark item complete
doctor	Check items.jsonl for health issues
wait ID REASON	Mark as waiting for something
unwait ID	Clear waiting status
edit ID --flag VALUE	Edit item fields (title, brief, parent, order)
work ID [STEPS...] [--status|--clear|--force]	Manage tactical steps for an action
step	Complete current step, advance to next
convert ID [--outcome P] [--force]	Convert outcome↔action
move ID --to REPO	Move item to another repo's board (new ID there, source closed with cross-reference)
archive [IDs...] [--all]	Move done items to archive.jsonl
log [-n N]	Show recent activity (creations, completions, archives)
reopen ID	Reopen a completed or archived item
migrate --to {jsonl|dolt}	Switch storage backend
update	Re-install bon from source
status	Show counts overview
help [CMD]	Show help

Output Flags

• --json — Structured JSON (for list, show)
• --jsonl — Flat JSONL, one item per line (for list)
• --quiet / -q — Minimal output, just the ID (for new)

JSON shapes differ by command:

Command	Shape	Example jq
bon list --json	{"outcomes": [...], "standalone": [...]}	.outcomes[0].title
bon show ID --json	Single object (action or outcome)	.title, .brief.why
bon show OUTCOME --json	Object with nested "actions" array	.actions[0].title

bon show returns an object, not an array. Use .field not .[0].field.

List Filters

bon list              # Open outcomes + their actions (default)
bon list --ready      # Only items ready to work on
bon list --waiting    # Only items that are waiting
bon list --all        # Include done items
bon list --limit 5    # First 5 top-level items (children come along)

--limit N truncates to the first N top-level items — outcomes first, then standalones. Children of kept outcomes always come along, so output never cuts mid-item. Combine with any filter (e.g. --ready --limit 3).

What --ready shows:

• All open outcomes (always visible for context)
• Actions where status=open AND waiting_for is empty
• If some actions are hidden, shows "+N waiting" count