loophaus

English | 한국어

<p align="center"> <img src="https://raw.githubusercontent.com/vcz-Gray/loophaus/main/assets/loophaus-banner.svg" alt="loophaus" width="600" /> </p> <p align="center"> <a href="https://www.npmjs.com/package/@graypark/loophaus"><img src="https://img.shields.io/npm/v/@graypark/loophaus.svg?style=flat-square&color=blue" alt="npm version" /></a> <a href="https://www.npmjs.com/package/@graypark/loophaus"><img src="https://img.shields.io/npm/dm/@graypark/loophaus.svg?style=flat-square&color=green" alt="npm downloads" /></a> <a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a> <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" /> <img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" /> <img src="https://img.shields.io/badge/tests-367%20passing-brightgreen.svg?style=flat-square" alt="tests" /> </p> <h3 align="center">Run AI coding agents in autonomous loops — fresh context each iteration, PRD-tracked progress, automatic quality gates.</h3> <p align="center"> _{Based on <a href="https://ghuntley.com/ralph/">Geoffrey Huntley's Ralph Wiggum technique</a>} </p> <p align="center"> <img src="https://raw.githubusercontent.com/vcz-Gray/loophaus/main/assets/demo-video/demo.gif" alt="loophaus demo" width="700" /> </p>

---

The Problem

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

The Solution

• 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.json with 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

Quick Start

npm install -g @graypark/loophaus
loophaus install

Note: npx @graypark/loophaus install may 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.

Safety

• 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 clean for data lifecycle management

Why not just script this?

1. Fresh context isolation — no degradation after 20 iterations; each cycle starts from disk, not from a decaying conversation
2. PRD-linked progress tracking — structured prd.json with pass/fail per story, not "I think I'm done"
3. Quality scoring with keep/discard — autoresearch pattern: measure, keep improvements, revert regressions

How it works

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.