ergo

A shared task list for you and your coding agents.

The ergo CLI is a way for coding agents to keep implementation plans, progress, and results inside your project -- outside the agent harness. This way, your backlog is independent of any one agent, model, session, or machine. A backlog should be interruptible, resumable, storable, parallelizable, and legible, and with ergo, that's how it is.

Have your agent write out its plans using ergo instead of Markdown files or an internal plan tool. You can opt to track the backlog in git or keep it local.

• Tasks have a state, such as draft, todo, doing, or done.
• Tasks can depend on one another, so the “Build the signup endpoint” task can wait for the “Create the database tables” task.
• Tasks can be grouped into epics.

Your agent writes the backlog, but it's easy for you to read and review it. Run ergo list:

Install

macOS with Homebrew:

brew install sandover/tap/ergo

On Windows, download the Windows ZIP for your architecture from the latest GitHub release, extract ergo.exe, and add its directory to your user PATH. Open a new terminal after changing PATH.

macOS, Linux, or Windows with Go 1.24 or later:

go install github.com/sandover/ergo/v6/cmd/ergo@latest

Prebuilt archives for macOS, Linux, and Windows are also available from the latest GitHub release.

Try it

In your project's directory, run:

ergo init

Add this to your AGENTS.md:

Use Ergo to manage the implementation backlog. Run ergo --help and ergo quickstart to learn it.

Then ask your agent:

Plan the password-reset feature in Ergo.

Review the plan with ergo list and use ergo show <id> to read a task's details. When you're ready, tell the agent:

Implement the plan

In any new session, just tell your agent to read the Ergo backlog and continue the work.

View in VS Code

Install the Ergo Backlog extension alongside the Ergo CLI, then open .ergo/backlog.jsonl to browse tasks and their details. Search by title or ID, filter for ready work, and click a task ID to read its details. The extension is read-only; agents change the backlog through the CLI.

You can also run Ergo: Backlog from the Command Palette to find a task.

For remote, WSL, SSH, or development-container windows, install Ergo in that environment. See the extension guide for setup.

Your backlog stays with your code

Ergo is a small command-line tool with no database or background service to manage. It stores the backlog in .ergo/backlog.jsonl and work history, including notes and results, in .ergo/journal.jsonl. Track these plain-text files in Git, or add them to .gitignore for local use.

Learn more

The manual lives in the CLI: ergo --help gives the overview, ergo quickstart gives the complete guide, and ergo <command> --help explains each command. You can also read the overview and guide here before installing.

The optional backlog-planning skill helps agents write well-structured tasks.

ergo is inspired by Beads, but has a focus on simplicity and speed.