{"id":37552830,"url":"https://github.com/sandover/ergo","last_synced_at":"2026-05-23T01:06:26.575Z","repository":{"id":332202665,"uuid":"1131275293","full_name":"sandover/ergo","owner":"sandover","description":"fast, minimal CLI tool for better coding agent planning","archived":false,"fork":false,"pushed_at":"2026-02-28T17:04:11.000Z","size":11592,"stargazers_count":26,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T19:44:44.200Z","etag":null,"topics":["beads-cli","claude-code","codex","codex-cli","planning"],"latest_commit_sha":null,"homepage":"https://github.com/sandover/ergo","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandover.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-09T18:34:34.000Z","updated_at":"2026-02-28T16:38:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sandover/ergo","commit_stats":null,"previous_names":["sandover/ergo"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/sandover/ergo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandover%2Fergo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandover%2Fergo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandover%2Fergo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandover%2Fergo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandover","download_url":"https://codeload.github.com/sandover/ergo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandover%2Fergo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33378556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-22T21:56:13.512Z","status":"ssl_error","status_checked_at":"2026-05-22T21:56:10.769Z","response_time":265,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beads-cli","claude-code","codex","codex-cli","planning"],"created_at":"2026-01-16T08:57:49.494Z","updated_at":"2026-05-23T01:06:26.569Z","avatar_url":"https://github.com/sandover.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ergo\n\n**A fast, minimal planning CLI tool for Claude Code and Codex.**\n\n[![License](https://img.shields.io/github/license/sandover/ergo)](LICENSE)\n[![CI](https://github.com/sandover/ergo/actions/workflows/ci.yml/badge.svg)](https://github.com/sandover/ergo/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/sandover/ergo)](https://goreportcard.com/report/github.com/sandover/ergo)\n[![Go Reference](https://pkg.go.dev/badge/github.com/sandover/ergo.svg)](https://pkg.go.dev/github.com/sandover/ergo)\n\n`ergo` gives your AI agents a better way to plan -- by storing task graphs in your repo, in a compact, git-friendly format.\n\nPlans 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).\n\n## Why?\nIn 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.\n\nCoding 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.\n\n`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.\n\nThe 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.\n\nInspired by [beads (bd)](https://github.com/steveyegge/beads), but simpler, sounder, and faster.\n\n## Features\n\n- **Simple:** no daemons, no git hooks, few opinions, easy to reason about.\n- **Fast:** 5-15x faster than beads, especially for large projects.\n- **Tasks live in the repo:** state lives in `.ergo/` as append-only JSONL.\n- **Safe for multiple agents:** a plain old file lock serializes writes\n- **Unixy:** JSON arguments, stdin bodies, and machine-readable JSON output.\n\n---\n\n## Quick Start\n\n#### Step 1 (in the terminal)\n```bash\n# Install on Mac -- get homebrew first (https://brew.sh/)\nbrew install sandover/tap/ergo \n```\nOr, on Linux: `go install github.com/sandover/ergo/cmd/ergo@latest`\n\n#### Step 2\nAdd this instruction into your `AGENTS.md` or `CLAUDE.md` file\n\u003e Use 'ergo' for all feature planning, run \"ergo --help\" to learn it\n\n**Optional:** This repo bundles an agent skill at [`skills/ergo-feature-planning/SKILL.md`](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.\n\n#### Step 3\nOnce you have a description of what you want to build (your spec), use a prompt like this:\n\n\u003e Use ergo to plan the implementation of this spec. Each task should have a goal, description, definition of done, and automated validation.\n\n_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!\n\n#### Step 4\nTell your agent to implement the plan.\n\n---\n\n## How humans use ergo\n\nThese three commands are typically the only ones used by humans.\n\n### `ergo list` -- to see the plan your agent wrote\n\n![Example output of ergo list](docs/img/ergo-list-screenshot.jpg)\n\nLegend:\n- `○` ready (todo + all deps satisfied)\n- `◐` in progress (doing)\n- `·` blocked (blocked or todo with unmet deps)\n- `✓` done\n- `✗` canceled\n- `⚠` error\n- `@agent-id` claimed by\n- `⧗ …` blocked by (dependency summary)\n\n### `ergo show` -- to see details of a task\n\n```bash\nergo show GQUJPG\n```\n\n![Example output of ergo show](docs/img/ergo-show-screenshot.jpg)\n\n### `ergo prune` -- to remove completed tasks\n\n```bash\nergo prune\n```\n\nRemoves completed (done or canceled) tasks from the plan.\n\n---\n\n## How coding agents use ergo\n\nRun `ergo --help` for syntax and `ergo quickstart` for the complete reference.\n\n### Planning\n\n```bash\n# Create a feature from a markdown plan file\ncat \u003e tasks.md \u003c\u003c'EOF'\n# Password hashing\nUse bcrypt with cost=12.\n---\n# Session tokens\n1h access, 24h refresh.\nEOF\n\nergo --json plan --file tasks.md '{\"title\":\"User login\"}'\n# =\u003e creates container ABCDEF with children GHIJKL, MNOPQR\n\n# Add ordering explicitly\nergo sequence GHIJKL MNOPQR\n\n# Or incrementally: create a task, then add children\nergo new task '{\"title\":\"User login\"}'\n# =\u003e ABCDEF\n\nprintf '%s\\n' 'Use bcrypt with cost=12.' | ergo new task '{\"title\":\"Password hashing\",\"epic\":\"ABCDEF\"}'\n# =\u003e GHIJKL\n\nprintf '%s\\n' '1h access, 24h refresh.' | ergo new task '{\"title\":\"Session tokens\",\"epic\":\"ABCDEF\"}'\n# =\u003e MNOPQR\n```\n\n### Execution\n\n```bash\n# Find actionable work\nergo --json list --ready\n\n# Claim a task (--agent identifies the caller)\nergo claim GHIJKL --agent sonnet@hostname\n\n# Mark it done\nergo set GHIJKL '{\"state\":\"done\"}'\n```\n\n\u003e **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.\n\n---\n\n## Data Representation\n\nAll state lives in `.ergo/` at your repo root:\n\n```\n.ergo/\n├── plans.jsonl    # append-only event log (source of truth)\n└── lock           # flock(2) lock file for write serialization\n```\n\n(For backwards compatibility, `events.jsonl` is also supported if it already exists.)\n\n**Why append-only JSONL?**\n- **Auditable:** Full history of every state change, who made it, when.\n- **Inspectable:** `cat .ergo/plans.jsonl | jq` — no special tools needed.\n- **Recoverable:** Corrupt state? Replay events. Want to undo? Filter events.\n- **Diffable:** `git diff` shows exactly what changed.\n\n**Concurrency safety:**\n- All writes acquire an exclusive `flock(2)` on `.ergo/lock` before appending.\n- `ergo claim` is atomic: read → find oldest READY → claim → write, all under lock.\n- Multiple agents can safely race to claim work; exactly one wins, others fail fast and should retry.\n\n**State reconstruction:**\nOn 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`\n\n**Why not SQLite?**\nSQLite 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.\n\n## Is it any good?\n\nYes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandover%2Fergo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandover%2Fergo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandover%2Fergo/lists"}