Coding agents produce dramatically better results when they plan before they code, and when their output is reviewed by a second agent — ideally from a different model provider. The catch: manually running that cycle (design → review → revise → approve → plan → review → revise → implement → review → revise → commit) across multiple agents is extremely time-consuming.

millstone automates that end to end. It wraps any combination of coding CLIs (Claude Code, Codex, Gemini, OpenCode) in a deterministic build-review loop: one agent authors, a second reviews, feedback cycles until the reviewer approves, then the change is committed. The same loop governs designs, plans, and code — with optional autonomous outer loops that discover opportunities, generate designs, and break them into tasks without human prompting.

Documentation | Getting Started | Meta Invoke | Contributing | Changelog

Quick Start

Before installing millstone, install and authenticate at least one supported coding agent CLI. See Supported Agents.

# 1) Install
pipx install millstone

# 2) Move into the repo you want to run on
cd /path/to/your/project

# 3) Recommended: give your coding agent an operator prompt
# @docs/prompts/execute.md  (run a tasklist)
# @docs/prompts/design.md   (design + plan a new feature)

Common pattern: hand millstone a short list of features and let it design, plan, and implement each one. Write them as a roadmap:

<!-- docs/roadmap.md -->
- [ ] Add a logout button to the header
- [ ] Show toast notifications on form errors
- [ ] Rate-limit the /api/search endpoint

Then run:

# Local roadmap file
millstone --cycle --roadmap docs/roadmap.md

For each goal, millstone designs a solution, breaks it into atomic tasks, implements them through a build-review loop, and commits. The local roadmap path reads goals directly from the file; the remote path runs analysis to discover and select from provider-backed opportunities. Approval gates pause between stages for human review; add --no-approve for fully autonomous operation. When a run hits a high-risk task, eval regression, or critical remote effect, millstone now saves a decision gate in .millstone/state.json and resumes only through an explicit follow-up command instead of waiting on stdin.

Other starting points:

# One task now (no setup required)
millstone --task "add retry logic to API client"

# Design, plan, and execute one objective end-to-end
millstone --deliver "Add retry logic to API client"

# Full autonomous loop — analyze codebase for improvements, then implement
millstone --cycle

# Existing local backlog file -> migrate once, then execute
millstone --migrate-tasklist backlog.md && millstone

# New app / fresh repo
millstone --init
millstone --deliver "Build a CLI app for release note generation"

millstone reads from .millstone/tasklist.md by default.

Highlights

• Deterministic inner loop: Builder -> Sanity -> Reviewer -> Sanity -> Fix -> Commit.
• Autonomous outer loops: analyze, design, plan, cycle — every authoring step is write/review gated.
• --max-cycles governs both inner build-review iterations and outer-loop authoring loops.
• --required-approvals N runs N independent reviewer rounds per task, each with up to --max-cycles fix loops.
• Parallel execution via git worktree — run multiple tasks concurrently with isolated checkouts and a serialized merge queue.
• Primary operating mode is coding-agent-invoked execution (docs/prompts/execute.md).
• Built-in evaluation flow with result capture and regression comparison.
• Multi-provider CLI routing per role (claude, codex, gemini, opencode).
• Stateful runs with logs, evals, and recovery under .millstone/.

Usage Patterns

How It Works

Inner loop (delivery):

Builder -> Sanity Check -> Reviewer -> Sanity Check -> Fix Loop -> Commit

Outer loop (self-direction) — a composable pipeline of typed stages:

Analyze -> Design -> Plan -> [Inner Loop] -> Eval -> (repeat)

Each stage transforms one artifact type into another (Opportunity → Design → Worklist). --through controls where the pipeline stops: --analyze --through plan runs analysis, design, and planning but skips execution. --cycle resolves which pipeline to build based on pending tasks, roadmap goals, or analysis results.

Every authoring step (analyze, design, plan) is write/review gated: a reviewer agent checks the output and requests revisions until it approves or --max-cycles is exhausted.

Installation Options

# PyPI (recommended when release is available)
pipx install millstone

# GitHub latest
pipx install git+https://github.com/wittekin/millstone.git

# Contributor install
pip install -e .[dev]

Optional extras:

pip install -e .[test]      # pytest + coverage
pip install -e .[quality]   # ruff + mypy
pip install -e .[security]  # pip-audit
pip install -e .[release]   # build + twine
pip install -e .[docs]      # mkdocs
pip install -e .[dev]       # contributor setup: tests, quality, docs, build, pre-commit

Local CI Before Push

Install the repo hooks once:

pre-commit install --hook-type pre-commit --hook-type pre-push

The pre-push hook runs a local CI subset that mirrors the most failure-prone required checks: lint, format, type check, dead-code scan, unit tests, coverage, package build, docs build, and an isolated wheel smoke test.

You can run the same gate manually:

python -m millstone.devtools.local_ci

It does not try to reproduce GitHub-only checks such as CodeQL, dependency review, or the macOS runner itself, but it catches most avoidable CI failures before you push.

Minimal Tasklist Format

# Tasklist

- [ ] First task to implement
- [ ] Second task
- [x] Already completed task

millstone executes the first unchecked - [ ] task.

Configuration Snapshot

Create .millstone/config.toml in the target repo:

max_cycles = 3
required_approvals = 1
max_tasks = 5
tasklist = ".millstone/tasklist.md"
roadmap = "docs/roadmap.md" # optional: used by `--cycle` when tasklist is empty

cli = "claude"
cli_builder = "codex"
cli_reviewer = "claude"

eval_on_commit = false
approve_opportunities = true
approve_designs = true
approve_plans = true

Multi-maintainer setup

By default, artifact files (tasklist, designs, opportunities) are written under .millstone/ and are gitignored — suitable for single-maintainer or local-only workflows.

To commit artifacts to the repo and share them with teammates, opt in per artifact type:

commit_tasklist = true       # stores at docs/tasklist.md
commit_designs = true        # stores at designs/
commit_opportunities = true  # stores at opportunities.md

For full multi-maintainer collaboration, use an external artifact provider (Jira, Linear, GitHub Issues, or beads) instead of file-backed defaults.

Tasklist filter contract

All tasklist providers (Jira, Linear, GitHub Issues) respect a provider-agnostic [tasklist_filter] section in .millstone/config.toml:

[tasklist_filter]
labels    = ["sprint-1"]        # AND – task must carry ALL listed labels
assignees = ["alice", "bob"]    # OR  – task assigned to ANY of these users
statuses  = ["Todo", "In Progress"]  # OR  – task in ANY of these statuses

Omit any key (or leave the list empty) to skip filtering on that dimension. The filter is applied when the outer loop fetches the next task from the remote provider. An explicit filter key inside [tasklist_provider_options] takes precedence over this section.

Scoping remote backlogs

When using a remote tasklist provider (Jira, Linear, or GitHub Issues), the default scope is the full open-issue set for the configured project/team/repo. Use [millstone.tasklist_filter] to restrict millstone to a specific subset without modifying provider options.

When to use local tasklist vs remote filters

Quick examples by backend

Jira — current sprint label:

[tasklist_provider_options]
type = "jira"
project = "PROJ"

[millstone.tasklist_filter]
label = "sprint-1"
assignee = "john.doe"

Linear — active cycle for a team:

[tasklist_provider_options]
type = "linear"
team_id = "<uuid>"

[millstone.tasklist_filter]
cycles = ["Cycle 5"]
label  = "millstone"

GitHub Issues — label + milestone:

[tasklist_provider_options]
type  = "github"
owner = "myorg"
repo  = "myrepo"

[millstone.tasklist_filter]
label     = "sprint-1"
milestone = "v1.2"

See full filter option reference in the per-backend docs under docs/providers/.

See full config and CLI options with:

millstone --help

Project Signals

• Canonical loop ontology: docs/architecture/ontology.md
• Scope and safety boundaries: docs/architecture/scope.md
• Parallel execution with worktrees: docs/worktrees.md
• CLI providers: docs/cli-providers/
• Artifact providers: docs/providers/
• Release checklist: docs/maintainer/release_checklist.md

Build and Release Workflows

This repository ships with CI, quality, docs, release, security, CodeQL, dependency review, and weekly maintenance workflows in .github/workflows/.

Tag release flow:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Star History

Planned after initial public release and first community adoption.

Working Directory

Creates .millstone/ in your repo containing:

• runs/ - Timestamped logs of each run
• evals/ - JSON eval results for comparison
• cycles/ - Logs of autonomous cycle decisions
• state.json - Saved state for --continue, including inner-loop halts, outer-loop stage checkpoints, and explicit decision gates
• config.toml - Per-repo configuration
• STOP.md - Created by sanity check to halt

This directory is auto-added to .gitignore.

Safety Checks

Mechanical:

• No changes detected -> Warn (proceeds to review)
• Too many lines changed -> Halt for human review
• Sensitive files (.env, credentials) -> Halt for human review
• New test failures (with --eval-on-commit) -> Halt with explicit eval-regression policy
• High-risk tasks / critical remote effects -> Halt with explicit decision gate unless approved or --no-approve

Judgment (via LLM):

• Builder output is gibberish -> Create STOP.md -> Halt
• Reviewer feedback is nonsensical -> Create STOP.md -> Halt

Exit Codes

• 0 - Success
• 1 - Halted (needs human intervention)
• 2 - Decision gate saved; resume with --continue plus the required explicit approval/policy flag

Expected Runtime

Depending on cycles, tasks, and your agent provider / model, millstone can run for minutes or hours.

Requirements

• Python 3.10+
• claude CLI installed and authenticated (default), or
• codex CLI installed and authenticated (if using --cli codex), or
• gemini CLI installed and authenticated (if using --cli gemini), or
• opencode CLI installed and authenticated (if using --cli opencode)

Open Source Project Files

• License: LICENSE
• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md