cih-agent 0.1.1

A hierarchical multi-agent harness that autonomously audits a codebase, finds high-value improvements, and applies them in TDD-gated iterations.

Continuous Improvement Harness (CIH)

A multi-agent system that audits any codebase, finds high-value improvements, and ships them in TDD-gated iterations — autonomously, and unable to push or bulk-stage by construction.

A change only merges if a non-LLM verifier proves — by checking out the commits and running the tests itself — that a new test failed before the fix and passes after, with the full suite still green. Every team works in a disposable git worktree; git push and git add -A are blocked at the wrapper level. Runs as a headless CLI or an interactive Claude Code skill.

How it works

flowchart TB
    ORCH["orchestrator · pure control flow"] --> HP["high-planner<br/>audit → ledger → charters"]
    subgraph teams["parallel teams · one worktree each"]
        T1["planner → plan-reviewer →<br/>executor → tdd_verifier (pytest) →<br/>execution-reviewer"]
        T2["team-NN …"]
    end
    HP --> T1 & T2
    T1 & T2 --> MQ["merge queue<br/>rebase → re-verify → fast-forward"]
    MQ --> DEC{"ledger dry / N reached?"}
    DEC -->|no| ORCH
    DEC -->|yes| DONE["stop · report.html"]

A high-planner scores improvement opportunities and splits them into non-overlapping charters. Each charter runs a five-agent pipeline in its own worktree, gated by a mechanical pytest verifier and a skeptical reviewer. Passing teams merge one at a time through a queue that re-runs the full suite before fast-forwarding. An opportunity ledger remembers what's been tried, cools down failures, and drives the run to convergence.

Quick start

Requires Python 3.11+ and the Claude Code CLI (claude) on your PATH — CIH drives it for the agent pipeline.

pip install cih-agent

# exactly 3 iterations, focused on tests + performance
cih --mode fixed-N --iterations 3 \
  --target-repo /abs/path/to/target --state-dir /abs/path/to/state \
  --focus tests --focus performance

# or run until converged (bounded by --max-iterations)
cih --mode until-converged \
  --target-repo /abs/path/to/target --state-dir /abs/path/to/state

pip install cih-agent installs the cih console command (the import name stays cih); cih … is equivalent to python -m cih.runner ….

target-repo and state-dir must be absolute, distinct, and non-nested. Add --report to write a self-contained report.html after every iteration.

Use it in another repo

Headless — no setup beyond the install. From anywhere, point --target-repo at the repo you want to improve and keep --state-dir outside it:

pip install cih-agent
cih --mode fixed-N --iterations 3 \
  --target-repo /abs/path/to/your-repo \
  --state-dir   /abs/path/to/your-repo-cih-state   # outside the target repo

Interactive (/cih skill). The skill and its agents aren't auto-installed by pip (Claude Code loads them from .claude/, not from site-packages). Install them once, then invoke /cih inside a Claude Code session:

cih install-skill                       # installs into ~/.claude (available in every repo)
cih install-skill --dest /path/to/your-repo/.claude   # or scope to one repo

The interactive skill runs a short scoping interview, then runs autonomously.

Why it's safe to leave running

• Improvements are proven, not asserted — the TDD verifier independently confirms red→green with the full suite passing; it hard-blocks skip markers and flags weak assertions.
• Can't push or bulk-stage — git push, git remote, and git add -A/--all/. are structurally unreachable; forbidden paths (secrets/, *.pem, *.key) are rejected.
• Never touches your tree — all work happens in disposable worktrees; state lives outside the target repo and every git command is logged.

Tests

python -m pytest -q

Full config lives in RunConfig (cih/config.py); role prompts in .claude/agents/.