How it works

At its core, erg is a state machine engine paired with AI coding. Each issue becomes a work item that advances through a configurable flowchart of states — from AI-generated code to a merged PR. You define exactly how much automation applies: require human review, auto-merge after CI, loop back for fixes, or notify external systems at any step.

1. Tag or label an issue

   Mark a task in GitHub, Asana, or Linear with the configured trigger label (e.g. plan or queued).

2. Daemon picks it up

   erg starts a containerized Claude session. With planning enabled, no branch is created yet — Claude reads the codebase in read-only mode.

3. Claude analyzes and posts a plan

   The ai.plan session explores the codebase and posts a structured implementation plan as an issue comment — no code written yet.

4. You review and approve

   Reply with approval (e.g. "LGTM") to proceed, or leave feedback. Claude revises the plan and loops back until you approve.

5. Claude writes the code

   Once approved, ai.code creates a branch, implements the changes, runs tests, and commits.

6. State machine advances

   The workflow engine opens a PR, waits for CI, handles review feedback, and merges — automatically, according to your rules.

Installation

Or build from source: go build -o erg .

Quick start

Run erg configure inside your repo. It will walk you through choosing an issue provider (GitHub, Asana, or Linear), configuring credentials, and scaffolding a workflow — then start the daemon.

File layout

Erg stores configuration, session data, and logs under ~/.erg/ by default. If ~/.erg/ does not exist, Erg respects the XDG Base Directory Specification: