backend-dev

Loop Harness

A deterministic loop engine and visual graph monitor for Claude Code. It runs 100% on your machine, uses your own Claude plan through the claude CLI, and installs zero Python packages.

Try it without wiring a real repo: python app/harness.py demo animates a whole loop on a throwaway project with mocked data.

The problem

Running autonomous coding agents through the API gets expensive fast. Running them with claude -p in a bash loop uses your subscription instead, but it leaves you blind in a sea of Markdown files, and nothing stops an agent from editing files outside its scope.

The answer

Loop Harness separates the brain (skills and prompts, the plugin/) from the runtime (a deterministic Python engine plus a web UI, the app/). It turns Claude Code into a visual state machine:

• Graph execution. Features are nodes with dependency edges. Each turn the engine picks a wave of features whose paths do not overlap and whose dependencies are done, fans them out to parallel Sonnet subagents, and fans them back in at verify and commit.
• Hard scope locks. A PreToolUse hook (guard.py) blocks, with exit 2, every edit outside a feature's paths, pushes to protected branches, production writes and your own project rules. Each rule ships with tests that run against the real hook. You watch the blocks live in the panel.
• Human in the loop. You approve the roadmap with a click. The loop stops when it needs you, you answer from the panel (or with --answer), and you can send an instruction to the next turn at any time.
• Deterministic state. The LLM does not own the state. Python validates every transition, chooses the next wave, snapshots each turn so you can --rewind, and refuses an unapproved roadmap. The model writes specs and code; the engine decides what may happen next.
• Local and lean. Python standard library only (zero pip install), ES modules served as-is (no npm, no build step), listening on 127.0.0.1 only. Nothing to break in your environment and no hosted service.
• Your own plan. Every turn is a claude -p call through the CLI you are already signed in to. There is no API key to manage and no per-token API bill.

Two honest notes:

• Headless runs count toward your plan's usage limits. Each turn is a claude -p call, the same as any other Claude Code use. When the account hits a limit, the loop waits and retries (--limit-wait, --limit-retries) and then stops with a notice. If your CLI is signed in with an API key instead of a plan, that key is billed.
• The CLI's JSON contract is covered by tests. The engine reads claude -p --output-format json through one tolerant parser. app/backend/tests/engine/test_cli_contract.py replays recorded output shapes on every test run: errors, budget stops, arrays, stream-json, warning lines, missing or renamed fields, garbage. An opt-in live test (LOOP_LIVE_CLI_TEST=1) runs one tiny real prompt against your installed CLI. Output the parser cannot read stops the loop with an unrecognized_output error; it is never counted as a turn. harness.py doctor shows your claude --version next to the version the contract was last tested with.

flowchart LR
    subgraph Plugin["plugin/ (the brain)"]
        S["/orchestrator skill<br/>agents, guard hook"]
    end
    subgraph App["app/ (the runtime + panel)"]
        E["engine<br/>run_loop, state, delivery"]
        P["control panel<br/>graph, turns, agents, specs"]
    end
    S -- "claude -p per turn" --> E
    E -- ".specs/ state" --> P
    P -- "check, start, answer, instruct" --> E

Why a panel

A loop that runs for hours writes dozens of files: ROADMAP.md, FLOWS.md, STATE.md, VALIDATE.md, ANSWERS.md, LOOP.json, a spec per feature, turn logs, snapshots and the transcript of every subagent. Reading them one .md at a time does not show you what is happening.

The panel puts them in one view, and turns the engine commands into buttons that ask for confirmation. The commands are --check, --answer, --option, --rewind, the state checks and the final delivery. There is less to type and nothing to paste wrong.

• Graph engineering. The roadmap is a graph: features grouped by stage, with dependency edges and status colours. The state machine shows how many features are in each node. Click a node to open that feature, turn or agent and act on that point: read its spec, inspect its log, chat about it, send an instruction, or answer its question.
• Loop engineering. Watch the current turn by lane, the history of every agent with tokens and duration, the limits (cost, turns without progress), and the quarantine. The panel also lists the decisions the loop took for you to validate later.
• Any starting point. Create a project from scratch (folder, git, .specs/), open an existing repo (map it, then plan the roadmap in the planning chat), or open a project whose loop stopped midway: the panel shows where it is and the next action.
• The roadmap gate stays yours. A new project opens in planning mode: a live chat (/orchestrator plan) asks you questions and writes PROJECT.md, ROADMAP.md and FLOWS.md (the flow that proves each feature) while you watch them in a preview. Approve roadmap unlocks only when the checklist is green: prerequisites, a goal, valid features, no open question and a flow per feature. The loop does not start without an approved roadmap.

Layout

Install

Requires Python 3.10+, Git and Claude Code signed in with your subscription. gh is needed only for the final PR.

1. Clone the repo and run the setup:

   git clone https://github.com/iagopadilha/loop-engineering-harness
   cd loop-engineering-harness
   python install.py
   

   install.py does these steps, printing one PASS, WARN or FAIL line per step:

   • checks Python, git, claude (and that claude --version answers) and the optional gh;
   • creates ~/.loop-harness/ and copies app/.env.example to ~/.loop-harness/.env, only if that file is missing;
   • registers the app so the skill can find it (harness.py install);
   • runs harness.py doctor, which checks the skill, the guard, the claude CLI and its version, and your notification channels.

   It exits non-zero on a hard failure, and --yes skips its one prompt. It installs nothing system-wide and never asks for a token.

2. Install the plugin in Claude Code (install.py prints these too):

   /plugin marketplace add iagopadilha/loop-engineering-harness
   /plugin install loop-engineering-harness@loop-engineering-harness
   

To do the same by hand, run python app/harness.py install and then python app/harness.py doctor.

Use

Open the panel (back end + front end, opens your browser):

python app/harness.py serve                      # hub: your projects, create or open a folder
python app/harness.py serve --project <repo>     # straight to one project
python app/harness.py demo                       # a fake project with moving loop data; no claude, nothing of yours touched

demo creates a throwaway project (acme-checkout) in a temporary folder and animates a whole loop in about 2 minutes: waves of features, agent log