ergo

A fast, minimal planning CLI tool for Claude Code and Codex.

ergo gives your AI agents a better way to plan -- by storing task graphs in your repo, in a compact, git-friendly format.

Plans are persistent across agent sessions, they are easy for humans to read and reason about, and they can be shared by different agents (from different model providers).

Why?

In software projects, even with AI, it really helps to clearly separate WHAT you want to build from HOW the implementation happens. Traditionally, this was the difference between a spec document and a work backlog.

Coding agents' own planning modes tend to result in a mess of markdown files that blur the distinction between the spec and the backlog and become hard to manage.

ergo is a tool your AI agent uses to write out a backlog of tasks. Then during implementation, your agent claims tasks, works on them, and marks them done. Tasks can be sequenced (A must happen before B), and they can be grouped into containers.

The task collection is stored in the repo as JSONL file, not inside the agent or its harness. You can keep the plan in git. The plan is agnostic about which agent you use to work on it. You could even use more than one agent at the same time -- ergo is built for concurrency.

Inspired by beads (bd), but simpler, sounder, and faster.

Features

• Simple: no daemons, no git hooks, few opinions, easy to reason about.
• Fast: 5-15x faster than beads, especially for large projects.
• Tasks live in the repo: state lives in .ergo/ as append-only JSONL.
• Safe for multiple agents: a plain old file lock serializes writes
• Unixy: JSON arguments, stdin bodies, and machine-readable JSON output.

---

Quick Start

Step 1 (in the terminal)

# Install on Mac -- get homebrew first (https://brew.sh/)
brew install sandover/tap/ergo 

Or, on Linux: go install github.com/sandover/ergo/cmd/ergo@latest

Step 2

Add this instruction into your AGENTS.md or CLAUDE.md file

Use 'ergo' for all feature planning, run "ergo --help" to learn it

Optional: This repo bundles an agent skill at skills/ergo-feature-planning/SKILL.md. Install or reference it from your agent setup when you want deeper guidance on writing well-structured plans: task sizing, acceptance criteria, validation gates, and dependency ordering.

Step 3

Once you have a description of what you want to build (your spec), use a prompt like this:

Use ergo to plan the implementation of this spec. Each task should have a goal, description, definition of done, and automated validation.

Pro tip: after that, tell the agent to review and improve upon its own plan. This leads to improvements every time. Measure twice, cut once!

Step 4

Tell your agent to implement the plan.

---

How humans use ergo

These three commands are typically the only ones used by humans.

ergo list -- to see the plan your agent wrote

Legend:

• ○ ready (todo + all deps satisfied)
• ◐ in progress (doing)
• · blocked (blocked or todo with unmet deps)
• ✓ done
• ✗ canceled
• ⚠ error
• @agent-id claimed by
• ⧗ … blocked by (dependency summary)

ergo show -- to see details of a task

ergo show GQUJPG

ergo prune -- to remove completed tasks

ergo prune

Removes completed (done or canceled) tasks from the plan.

---

How coding agents use ergo

Run ergo --help for syntax and ergo quickstart for the complete reference.

Planning

# Create a feature from a markdown plan file
cat > tasks.md <<'EOF'
# Password hashing
Use bcrypt with cost=12.
---
# Session tokens
1h access, 24h refresh.
EOF

ergo --json plan --file tasks.md '{"title":"User login"}'
# => creates container ABCDEF with children GHIJKL, MNOPQR

# Add ordering explicitly
ergo sequence GHIJKL MNOPQR

# Or incrementally: create a task, then add children
ergo new task '{"title":"User login"}'
# => ABCDEF

printf '%s\n' 'Use bcrypt with cost=12.' | ergo new task '{"title":"Password hashing","epic":"ABCDEF"}'
# => GHIJKL

printf '%s\n' '1h access, 24h refresh.' | ergo new task '{"title":"Session tokens","epic":"ABCDEF"}'
# => MNOPQR

Execution

# Find actionable work
ergo --json list --ready

# Claim a task (--agent identifies the caller)
ergo claim GHIJKL --agent sonnet@hostname

# Mark it done
ergo set GHIJKL '{"state":"done"}'

Tip: Put metadata in the JSON argument and pipe markdown bodies on stdin. Use plan --file when you want to seed a container from a markdown task list.

---

Data Representation

All state lives in .ergo/ at your repo root:

.ergo/
├── plans.jsonl    # append-only event log (source of truth)
└── lock           # flock(2) lock file for write serialization

(For backwards compatibility, events.jsonl is also supported if it already exists.)

Why append-only JSONL?

• Auditable: Full history of every state change, who made it, when.
• Inspectable: cat .ergo/plans.jsonl | jq — no special tools needed.
• Recoverable: Corrupt state? Replay events. Want to undo? Filter events.
• Diffable: git diff shows exactly what changed.

Concurrency safety:

• All writes acquire an exclusive flock(2) on .ergo/lock before appending.
• ergo claim is atomic: read → find oldest READY → claim → write, all under lock.
• Multiple agents can safely race to claim work; exactly one wins, others fail fast and should retry.

State reconstruction: On each command, ergo replays plans.jsonl to build current state in memory quickly (100 tasks: ~3ms, 1000 tasks: ~15ms) and guarantees consistency. Run ergo compact to collapse history if the log grows large. To verify: go test -bench=. -benchmem

Why not SQLite? SQLite is great, but binary files don't diff well in git. JSONL is trivially inspectable (cat | jq), merges via git, and append-only writes with flock are simple. For a few thousand tasks, replay is instant.

Is it any good?

Yes.