iterate-harness

English · 简体中文

iterate is an open-source project that gives AI coding assistants the ability to repeatedly review and fix code in multi-round autonomous loops. It targets a concrete pain point:

AI assistants tend to "talk a lot but do little": a single conversation only touches a few lines, stops caring about the rest of the repo after glancing at one file, and rarely double-checks what they broke. iterate automates these closing chores — itemized review, per-dimension triage, fix, validate, and iterate again — so AI actually finishes changes and gets them right.

Within that ecosystem, iterate-harness is a dedicated agent harness for the iterate review/fix loop: repeated multi-dimension code review until findings converge, deterministic aggregation, atomic fixes validated every round, and an append-only decision log that makes every iteration auditable. It is one of three interchangeable components that share the same iterate.config.yaml and dimension system:

It is a standalone agent harness built around the iterate review/fix loop: the kernel agent loop, React TUI, tool/skill/plugin systems and permission layer are iterate-native, with the iterate semantic layer (ported from the iterate skill's TypeScript implementation) plus the engine-level convergence policy at its core.

⭐ If this project helps you, please consider giving it a GitHub star — it means a lot to open-source maintenance!

🐳 OrcaRouter — built-in gateway with free models

OrcaRouter is a built-in OpenAI-compatible gateway provider with free models — e.g. deepseek/deepseek-v4-flash-free or the orcarouter/free router — billed at $0, no token cost. All you need is an API key.

No key yet? Just press Enter at the key prompt and the signup page opens in your browser (register through the link above, supporting the project):

ih setup orcarouter     # paste an existing key, or press Enter to open the signup page

Already have a key? Activate the built-in profile — only one environment variable is required (ORCA_KEY); the base URL (https://api.orcarouter.ai/v1) and default model (orcarouter/auto) are baked in:

ih provider use orcarouter
export ORCA_KEY=sk-orca-...

Free-tier note: free models still require an API key; long-context prompts can exceed the free-tier prompt cap (HTTP 429 without Retry-After), so they suit CI / lightweight reviews best.

🚀 Quick Start

# install (npm wrapper; needs Node + Python >= 3.10)
npm install -g iterate-harness
# ...or no-Node one-liner (macOS / Linux / WSL, Python only)
# curl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash

# launch the TUI
ih

# inside the REPL
/iterate review        # dry-run: read-only multi-round review until convergence
/iterate personalize   # directional-key 9-category wizard (interactive select + question modals)

CLI-first instead:

ih iterate onboard       # MODEL-DRIVEN project scan -> ITERATE.md knowledge base + config + fingerprints
ih iterate onboard --no-ai # detection-only fallback (no model call, channel=cli)
ih iterate status        # config + onboarding state + drift check
ih iterate refresh       # re-fingerprint manifests, report drift, refresh metadata
ih iterate reonboard     # backup, full model re-scan, preserve your user-owned region
ih iterate personalize   # 9-category wizard: constraints -> config + ITERATE.md user region
ih iterate init          # detect the project, generate iterate.config.yaml (config only)
ih iterate review        # headless dry-run (stream-json output available)
ih iterate review --changed # quick review: only files changed vs --ref (default HEAD)
ih iterate run           # headless autonomous fix loop
ih iterate resume        # resume the last session
ih iterate log           # tail the decision log
ih iterate log --trend   # cross-run finding trend (new/fixed/regressed/stubborn)
ih iterate log --replay  # replay the whole run chronologically (relative timestamps)
ih iterate report        # render the final report (CI mode, see below)
ih iterate report --pr    # post/update the report as a PR comment (gh CLI, idempotent)
ih iterate report --html # single-file HTML report (convergence curve, diffs, shareable)
ih iterate batch a/ b/   # review multiple repos sequentially, rank worst-first
ih iterate schedule add "0 9 * * 1-5" # daily changed-only quick review (cron, UTC)
ih iterate hook install  # managed pre-commit hook: 1-round changed-only gate
ih iterate doctor        # skill↔harness dimension-system consistency check

Onboarding note: ih iterate onboard first gates on a configured model credential (ih auth login), then lets the model explore the project with its read tools (manifests, 2-3 level directory tree, specs/tests/CI, README — never .env/keys) and write ITERATE.md with byte-exact AI-maintained / user-owned region markers. The harness itself validates the markers, captures SHA-256 manifest fingerprints and writes iterate.config.yaml — untrusted model output never touches trusted config structure. Both files are byte-compatible with the skill's onboarding (same markers, same onboarding.fingerprints schema), so projects onboarded by either ecosystem interoperate. Every later loop kickoff injects the ITERATE.md knowledge base into the system prompt, and a drifted manifest (dependency bump, stack change) triggers a non-blocking warning before reviews.

Set your API key first: export ANTHROPIC_API_KEY=your_key (OpenAI-compatible providers are also supported — see ih --help).

✨ Iterate Features

🔧 The six iterate tools

• iterate_config — effective config (defaults + iterate.config.yaml overrides)
• iterate_validate — run a preconfigured validation command (EXACT match only)
• iterate_review — deterministic engine: plan / aggregate / meta-review
• iterate_decision_log — append-only decision log
• iterate_context — SKILL.md / ITERATE.md / personalization context
• iterate_triage — interactive y/n/a findings triage with known_intentional persistence

Slash command /iterate (status / review / run / log / config / validate) and the bundled iterate skill provide the same loops through different entries.

🧭 Architecture

src/iterate_harness/
├── iterate/            # semantic layer (Python port of the TS skill)
│   ├── review.py       # dedupe / known_intentional filter / severity sort / convergence
│   ├── meta_review.py  # 6-check report consistency audit
│   ├── config_loader.py# Master + Overrides merge
│   ├── validate.py     # EXACT-match validation runner
│   ├── decision_log.py # append-only JSONL
│   ├── loop_policy.py  # engine-level convergence enforcement + cost meter
│   ├── personalization.py # 9-category per-project store
│   ├── worktree_flow.py# git isolation: enter/commit/exit + rollback
│   └── prompts.py      # canonical dry-run/normal loop templates
├── engine/             # kernel agent loop (upstream + iterate control block)
├── permissions/        # checker + iterate auto-assembly (protected_paths …)
├── tools/iterate_tools.py  # the six iterate_* tools
└── ui/                 # React TUI backend host + review_progress protocol

📦 Install

• npm (easiest): npm install -g iterate-harness — a thin wrapper that pip-installs the release tarball into a managed venv (~/.iterate-harness-npm) on first run and keeps the version in lockstep with the npm package
• macOS / Linux / WSL: bash scripts/install.sh (clone + venv + editable install, links ih and iterate-harness into ~/.local/bin)
• Windows (PowerShell): scripts/install.ps1
• From a checkout: bash scripts/install_dev.sh
• Requires Python ≥ 3.10; Node.js ≥ 18 enables the React TUI (skipped otherwise — the plain fallback UI still works)

🧪 Tests

python -m pytest tests/test_iterate -q   # semantic layer + kernel integration
python -m pytest -q                      # full suite

📄 License & Attribution

MIT. iterate-harness is maintained at jingzhao-l/iterate-harness. The iterate semantic layer originates from the iterate-skill project.

⚠️ Disclaimer

This project is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.

Automated code review and fixing carries inherent risk. All changes produced in normal mode are generated by AI models and may introduce bugs, regressions, or unintended behavior. Before merging, you should:

• Review every diff before applying it to your main branch or pushing.
• Make sure your project is under git control and can be rolled back (git restore, revert, or restore from backup).
• Run your project's own test suite and build checks after each round of fixes.
• Never run this on secrets, credentials, .env, or files that must not be modified — configure protected_paths accordingly.

Users are solely responsible for the code that is generated, modified, or committed as a result of using this project. By using it, you acknowledge that neither the maintainers nor contributors are liable for any loss, damage, or legal consequences arising from its use.

Troubleshooting / 常见失败自愈指南

TLS / SSL Certificate Errors

Symptom: SSL: CERTIFICATE_VERIFY_FAILED or certificate verify failed during API calls.

Causes & fixes:

1. System CA bundle outdated — Run pip install --upgrade certifi or update your OS certificates.
2. Corporate proxy / MITM — Set the REQUESTS_CA_BUNDLE or SSL_CERT_FILE env var to your enterprise CA cert.
3. Self-signed local endpoint — If using a local model server (ollama, lmstudio), set auth_source: local in the provider profile (which disables cert verification for localhost).

Authentication / API Key Errors

Symptom: 401 Unauthorized or 403 Forbidden during model API calls.

Causes & fixes:

1. Missing or expired key — Run ih provider use <profile> and follow the interactive prompt to re-enter the key.
2. Wrong auth source — Verify the provider profile's auth_source matches your credential slot. Use ih provider list to check, then ih provider edit <name> to correct.
3. Rate limited — See "Rate Limiting / Quota" below.

Rate Limiting / Quota Exceeded

Symptom: 429 Too Many Requests or quota exhaustion errors.

Causes & fixes:

1. Too many requests per minute — Set max_turns_per_minute in the harness settings or iterate.config.yaml to throttle the loop.
2. Token budget exceeded — Set token_budget or budget_usd in iterate.config.yaml to cap per-run spend.
3. Provider account quota — Check your provider's usage dashboard and upgrade the plan if needed.

Checkpoint / Resume Failures

Symptom: Resume cannot find the last checkpoint, or the checkpoint is stale.

Causes & fixes:

1. Checkpoint cleared — A checkpoint is cleared after a successful run. Only incomplete/interrupted runs have valid checkpoints.
2. Stale worktree — If worktree_isolation: true, a previous abnormal exit may leave stale worktrees. Run git worktree prune to clean them up.
3. Manual intervention — If you modified files inside the worktree, the checkpoint may be invalid. Start a fresh run instead.

Provider / Model Not Found

Symptom: model not found or unknown provider errors.

Causes & fixes:

1. Typo in model name — Run ih provider list to see available providers and their default models.
2. Custom provider misconfigured — Run ih provider edit <name> to verify the base_url, api_format, and default_model fields.
3. Local endpoint not running — For local/ollama providers, verify the server is running: curl http://localhost:11434/api/tags.