Autonomous coding loops CLI
Orchestrate AI coding agents in iterative, PRD-driven development cycles.
brew install matheus3301/tap/loopforge📦 Other methods (Go install, binary download, build from source): INSTALLATION.md
loopforge init
loopforge prd generate "Build a REST API with user authentication"
loopforge build
AI coding agents like Claude Code, Codex, and OpenCode are powerful, but they work best with focused, single-task prompts. LoopForge orchestrates these agents in structured, iterative loops — one story at a time.
- 📋 PRD-driven — Structured requirements with stories and dependencies
- 🔄 One story per iteration — Clean context, focused execution
- 📝 Granular commits — Easy to review and rollback
- 🛡️ Guardrails — Persistent rules that improve over time
flowchart LR
A[📋 Select Story] --> B[🤖 Execute Agent]
B --> C[✅ Run Quality Gates]
C --> D{Passed?}
D -->|Yes| E[💾 Commit Changes]
D -->|No| F[🔄 Reset & Retry]
E --> G{More Stories?}
F --> A
G -->|Yes| A
G -->|No| H[🎉 Done!]
style A fill:#6366f1,color:#fff
style B fill:#8b5cf6,color:#fff
style C fill:#f59e0b,color:#fff
style E fill:#22c55e,color:#fff
style H fill:#22c55e,color:#fff
Each iteration:
- Selects the next available story (respecting dependencies)
- Executes your configured coding agent with full context
- Validates via quality gates (tests, linting, etc.)
- Commits on success, or resets and logs on failure
- Repeats until all stories are done
A structured JSON file that defines your project:
graph TD
PRD[📄 PRD] --> M[Metadata]
PRD --> S[Stories]
PRD --> G[Quality Gates]
M --> M1[Project Name]
M --> M2[Overview]
M --> M3[Stack]
S --> S1[US-001: Setup]
S --> S2[US-002: Feature A]
S --> S3[US-003: Feature B]
S2 -.->|depends on| S1
S3 -.->|depends on| S1
G --> G1[go build]
G --> G2[go test]
G --> G3[go vet]
style PRD fill:#6366f1,color:#fff
style S fill:#8b5cf6,color:#fff
style G fill:#f59e0b,color:#fff
The unit of work. Each story has:
- ID — Unique identifier (
US-001) - Dependencies — Other stories that must complete first
- Status —
open→in_progress→done
Persistent rules that guide the agent across all iterations:
| Guardrail | Description |
|---|---|
| Read Before Write | Always read a file before modifying it |
| Test Before Commit | Run tests before marking complete |
| One Task Per Iteration | Focus on a single story |
| Handle Errors | Don't ignore errors, handle them |
| Atomic Commits | Keep commits focused and reviewable |
| Command | Description |
|---|---|
loopforge init |
Initialize LoopForge in current directory |
loopforge build [n] |
Run the build loop (optionally n iterations) |
loopforge prd generate |
Generate PRD from description |
loopforge prd show |
Display current PRD status |
loopforge agent list |
List available agents |
loopforge agent set <name> |
Set default agent |
loopforge guardrail list |
List all guardrails |
loopforge watch |
Watch PRD for changes |
graph LR
LF[LoopForge] --> C[Claude Code]
LF --> X[Codex CLI]
LF --> O[OpenCode]
LF --> U[Custom Agent]
style LF fill:#6366f1,color:#fff
style C fill:#8b5cf6,color:#fff
style X fill:#22c55e,color:#fff
style O fill:#f59e0b,color:#fff
style U fill:#64748b,color:#fff
Set your preferred agent:
loopforge agent set claude # Anthropic Claude Code
loopforge agent set codex # OpenAI Codex
loopforge agent set opencode # OpenCodeConfiguration lives in .loopforge/config.yaml:
agent:
name: claude
timeout: 30m
build:
maxIterations: 25
autoCommit: true
guardrails:
enabled: true.loopforge/
├── config.yaml # Configuration
├── prd.json # Your PRD (track in git)
├── progress.md # Build progress log
├── guardrails.md # Custom guardrails
└── templates/ # Custom prompt templates
- Command Reference (coming soon)
- PRD Schema (coming soon)
- Agent Configuration (coming soon)
- Guardrails Guide (coming soon)
Contributions are welcome! See CONTRIBUTING.md for guidelines.
git clone https://github.com/matheus3301/loopforge.git
cd loopforge
go test ./...Inspired by Ralph by @iannuttall.