Run AI coding agents in autonomous loops — fresh context each iteration, PRD-tracked progress, automatic quality gates.
Based on Geoffrey Huntley's Ralph Wiggum technique
AI coding agents struggle with long tasks:
- Context rot — agent gets confused after 10+ iterations
- Goal drift — agent forgets the spec and solves the wrong problem
- No quality signal — agent says "done" but tests still fail
- Token waste — you re-explain the same context every time
- Fresh context per iteration — Each cycle reads PRD + progress from disk, zero degradation even after 20+ iterations
- PRD-linked progress tracking — Stories are tracked in
prd.jsonwith pass/fail state, not "I think I'm done" - Quality scoring with keep/discard — Autoresearch-inspired refinement loop measures quality (0-100) and reverts regressions
- Universal stop hook — One Node.js hook works across Claude Code, Codex CLI, and Kiro CLI
npm install -g @graypark/loophaus
loophaus installNote:
npx @graypark/loophaus installmay fail on some npm versions due to a bin resolution cache bug. Use the global install above for reliable setup.
The installer auto-detects your host (Claude Code, Codex CLI, or Kiro CLI) and sets up everything — stop hook, commands, and skills.
Then in your AI coding session:
/loop-plan Add user authentication with JWT, bcrypt, and login UI
That's it. The interview generates a PRD, activates the loop, and starts implementing story by story.
- Every iteration creates a git checkpoint — atomic revert anytime
- Max iterations limit (default 20, configurable)
- Quality threshold = circuit breaker — score < 80 triggers refine or stop
- Cost tracking with policy enforcement (max $5, max 30 min)
loophaus cleanfor data lifecycle management
- Fresh context isolation — no degradation after 20 iterations; each cycle starts from disk, not from a decaying conversation
- PRD-linked progress tracking — structured
prd.jsonwith pass/fail per story, not "I think I'm done" - Quality scoring with keep/discard — autoresearch pattern: measure, keep improvements, revert regressions
An AI agent works on a task in a continuous loop. Each iteration starts with fresh context — reading the PRD and progress files to decide what to do next. The agent implements one story, commits, updates progress, and exits. The stop hook intercepts the exit and re-injects the prompt. Repeat until all stories pass.
┌──────────────────────┐
│ /loop-plan │
│ Describe your task │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ Generate prd.json │
│ + progress.txt │
└──────────┬───────────┘
│
┌────────────────▼────────────────┐
│ /loop │
│ │
│ 1. Read prd.json + progress │
│ 2. Pick next story (passes=false)│
│ 3. Implement + verify │
│ 4. Evaluate (score 0-100) │
│ 5. Refine loop (keep/discard) │
│ 6. Commit + update progress │
│ 7. Exit attempt │
│ │ │
│ Stop Hook intercepts │
│ Re-injects prompt │
│ │ │
│ Back to step 1 ──────────────┘
│ │
│ All stories pass? │
│ → <promise>COMPLETE</promise> │
│ │
│ /loop-pulse → check status │
│ /loop-stop → cancel anytime │
└─────────────────────────────────┘
| Command | Description |
|---|---|
/loop-plan |
Interactive interview — asks targeted questions, generates PRD, activates loop |
/loop |
Start iterative dev loop directly (when you already have a PRD or custom prompt) |
/loop-stop |
Stop the active loop immediately |
/loop-pulse |
Check current loop status, iteration count, and progress |
loophaus v3.4.0 introduces the Quality Loop — inspired by karpathy/autoresearch's experiment-measure-keep/discard pattern.
Instead of simply marking a story as "done" when tests pass, /loop-plan now measures quality (0-100) and iteratively refines until the score meets the threshold.
Phase 4: Implement
↓
Phase 5: Evaluate (score 0-100)
↓ ↑
Phase 6: Refine Loop
score improved? → keep (commit)
score declined? → discard (git reset)
max attempts reached? → move on
↓
Phase 7: Report (with quality scores)
| autoresearch | loophaus |
|---|---|
val_bpb |
quality score (weighted: tests, typecheck, lint, verify, diff, custom) |
results.tsv |
.loophaus/results.tsv |
| keep → advance | score improved → commit |
| discard → revert | score declined → git reset --hard |
| NEVER STOP | max 3 attempts per story (configurable) |
{
"qualityThreshold": 80,
"maxRefineAttempts": 3,
"qualityConfig": {
"weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
}
}| Claude Code | Codex CLI | Kiro CLI | |
|---|---|---|---|
| Stop Hook | Node.js | Node.js | Node.js |
| Install target | Plugin cache | hooks.json |
agents/ + steering/ |
| Commands | /reload-plugins |
native | steering manual mode |
| Multi-agent | Agent tool | subprocesses | steering agents |
All three platforms share the same core engine (core/engine.ts) and state store (store/state-store.ts). Platform-specific adapters handle the differences.
Native Windows is supported for install, upgrade, and /loop initialization via PowerShell or CMD. Git Bash and WSL are optional, not required.
npm install -g @graypark/loophaus
loophaus installOn Windows, ensure your global npm bin directory (typically %AppData%\npm) is on PATH.
npx @graypark/loophaus install
npxmay fail on some npm versions due to a bin resolution cache bug. If it does, use the global install above.
loophaus install --host claude-code
loophaus install --host codex-cli
loophaus install --host kiro-cli| Flag | Description |
|---|---|
--force |
Overwrite existing installation |
--dry-run |
Preview changes without writing files |
--local |
Install to project directory instead of global (Codex CLI only) |
loophaus ships a standalone CLI for management tasks:
loophaus install # Install to detected host
loophaus status # Show current loop state and active host
loophaus stats # Iteration history and completion metrics
loophaus quality # Run quality scoring on current stories
loophaus demo # Run interactive demo
loophaus config # Show/edit configuration
loophaus update-check # Check for new versions
loophaus upgrade # Upgrade to latest version
loophaus uninstall # Clean removal from all hostsloophaus/
├── bin/
│ ├── loophaus.ts # CLI entry point
│ ├── install.ts # Cross-platform installer
│ └── uninstall.ts # Clean uninstaller
├── core/
│ ├── types.ts # Shared TypeScript interfaces
│ ├── engine.ts # Core loop engine (shared)
│ ├── event-logger.ts # Iteration event tracking
│ ├── quality-scorer.ts # Quality scoring (score, evaluate, log)
│ ├── refine-loop.ts # Keep/discard refinement logic
│ ├── validate.ts # PRD + state schema validation
│ ├── policy.ts # Loop policy evaluation
│ ├── cost-tracker.ts # Token cost estimation
│ ├── trace-analyzer.ts # Trace analysis + comparison
│ ├── worktree.ts # Git worktree lifecycle
│ ├── merge-strategy.ts # Parallel merge strategies
│ ├── parallel-runner.ts # Multi-worktree orchestration
│ ├── session.ts # Checkpoint / session management
│ └── loop-registry.ts # Multi-loop registry
├── store/
│ └── state-store.ts # Loop state persistence
├── lib/
│ ├── paths.ts # Cross-platform path resolution
│ └── stop-hook-core.ts # Testable hook logic
├── platforms/
│ ├── claude-code/installer.mjs # Plugin cache installer
│ ├── codex-cli/installer.mjs # hooks.json installer
│ └── kiro-cli/installer.mjs # agents/ + steering/ installer
├── hooks/
│ └── stop-hook.mjs # Universal stop hook (Node.js)
├── commands/ # Slash command definitions
├── skills/ # Platform-specific skill definitions
├── .claude-plugin/
│ └── plugin.json # Claude Code marketplace manifest
├── dist/ # Compiled output (tsc)
└── tests/ # 359 test cases (vitest)
loophaus uses a prd.json format:
{
"project": "MyApp",
"branchName": "feature/auth-system",
"description": "JWT authentication with login UI",
"userStories": [
{
"id": "US-001",
"title": "Add users table with password hash",
"description": "As a developer, I need user storage for auth",
"acceptanceCriteria": [
"Users table with email, password_hash columns",
"Migration runs successfully",
"Typecheck passes"
],
"priority": 1,
"passes": false,
"notes": ""
}
]
}Each story is sized to complete in one iteration (one context window). Dependencies are ordered by priority. The loop engine picks the next story where passes is false and works on it until verification succeeds.
loophaus upgradeManual upgrade also works:
npm install -g @graypark/loophaus@latest
loophaus install --forceloophaus uninstall
npm uninstall -g @graypark/loophausgit clone https://github.com/vcz-Gray/loophaus.git
cd loophaus
npm install
npm test # 359 tests
npm run typecheck # TypeScript strict mode
npm run build # Compile to dist/
npx vitest # watch modeMIT
Built for Claude Code, Codex CLI, and Kiro CLI