Relentless
What's in a Name?
According to Matt Pocock, if you're trying to sneak Ralph into the enterprise, just pretend it's an acronym:
Relentless Agentic Looping Programming Helper
So naturally, RELENTLESS is the recursive acronym:
RALPH Endlessly Loops, Executing, Navigating Tasks, Learning, Evolving, Solving, Scaling
It's recursive. We loop. That's kind of our thing.
The Problem
You have an AI coding agent. It's brilliant — for about 15 minutes. Then it loses context, forgets what it was doing, or hits a rate limit. You babysit it, re-prompt it, copy-paste context back in. Rinse and repeat.
What if it just... kept going?
The Solution
Relentless runs your AI agent in a loop until all tasks are complete. Each iteration spawns a fresh agent with clean context. Memory persists through git commits and progress files. When one agent hits a rate limit, another takes over.
npm install -g @arvorco/relentless
cd your-project
relentless init
relentless run --feature my-feature --tui
That's it. Go grab a coffee. Or lunch. Or sleep. Relentless will keep working.
From Ralph to Relentless
The Origin
Geoffrey Huntley created the Ralph Wiggum Pattern — a brilliantly simple idea: run an AI coding agent in a loop until all tasks are done. Watch his original video to understand the concept.
The pattern works. But we found it could work better.
The Evolution
Ralph loops. Relentless loops smarter.
| Challenge |
Ralph |
Relentless |
| Specs |
Manual PRDs, often vague |
Structured specs inspired by GitHub SpecKit with interactive clarification and dependency ordering |
| Agents |
Single agent (usually Claude) |
Universal: Claude, Amp, OpenCode, Codex, Droid, Gemini — with automatic fallback on rate limits |
| Cost |
Same model for everything |
Route simple tasks to cheaper models, complex ones to capable models |
| Tasks |
Can be too big or vague |
4-phase breakdown (Setup → Foundation → Stories → Polish) with 15-60 min task sizing |
| Quality |
Hope it works |
TDD enforced, E2E tests required, domain-specific checklists, cross-artifact analysis, constitution rules |
The Philosophy
"Garbage in, garbage out — if your specs are vague, your agent will spin its wheels. And at $0.50 per iteration, those wheels get expensive fast."
Relentless ensures you know exactly what "done" means before the first line of code is written.
Quick Start
1. Install
npm install -g @arvorco/relentless
# or
bun install -g @arvorco/relentless
2. Initialize
cd your-project
relentless init
After upgrading Relentless, rerun /relentless.constitution to refresh relentless/prompt.md with the latest instructions (including spec/plan/tasks awareness).
Upgrading from Previous Versions
If you have Relentless installed from before v0.4.0:
Update the package:
bun install -g @arvorco/relentless
# or: npm install -g @arvorco/relentless
Important: Re-run the constitution command to get updated templates:
/relentless.constitution
This will detect changes and offer upgrade options for your
constitution.md and prompt.md files.
3. Create a Feature
With Claude Code, Amp, or OpenCode (recommended):
# Create constitution + personalized prompt (do this once per project)
/relentless.constitution
# Create feature (tasks now auto-generates prd.json!)
/relentless.specify Add user authentication with OAuth2
/relentless.plan I'm using React, TypeScript, PostgreSQL
/relentless.tasks # Auto-converts to prd.json
/relentless.analyze # Validate consistency
With Codex, Droid, or Gemini (manual workflow):
relentless features create user-auth
# Then prompt your agent to create spec.md, plan.md, tasks.md
# Or reference .claude/skills/*/SKILL.md for format
relentless convert relentless/features/001-user-auth/tasks.md --feature 001-user-auth
4. Run
# Auto mode is now the default (use --agent <harness> to opt out)
relentless run --feature 001-user-auth --tui
Watch the beautiful TUI as your agent works through each task, commits code, and marks stories complete.
CLI Reference
Run Command
relentless run --feature <name> [options]
Options:
--agent <harness>: Force a specific harness (auto, claude, amp, opencode, codex, droid, gemini).--mode <mode>: Auto mode cost tier (free, cheap, good, genius).--fallback-order <list>: Comma-separated harness order for auto fallback.--max-iterations <n>: Limit loop iterations (default: 20).--skip-review: Skip final review phase.--review-mode <mode>: Review quality tier (free, cheap, good, genius).--dry-run: Show routing and planning without executing agents.--tui: Run the interactive terminal UI.--dir <path>: Working directory for the run.
Estimate Command
relentless estimate --feature <name> [--mode <mode>] [--compare]
Options:
--mode <mode>: Cost tier for estimation (free, cheap, good, genius).--compare: Compare all modes side by side.
Other Useful Commands
relentless init
relentless convert <tasks.md> --feature <name>
relentless agents list
relentless agents doctor
Auto Mode
Smart routing saves 50-75% on AI costs by matching task complexity to the right model.
Auto mode is now enabled by default and becomes the default agent. If you want to force a specific harness, pass --agent explicitly.
Auto Mode is designed to keep you productive: simple tasks run fast on cheaper models, while hard problems automatically route to stronger models (or escalate when needed). That means fewer reruns, lower spend, and faster end-to-end throughput on real features.
Default Behavior
relentless run uses auto routing unless you pass --agent <harness>- Auto mode uses your
relentless/config.json defaults for defaultMode, fallback order, and model overrides
- You can still lock a harness per run (e.g.,
--agent codex)
Four Cost Modes
| Mode |
Model Selection |
Best For |
| free |
OpenCode free models |
Maximum savings, simple tasks |
| cheap |
Haiku 4.5, Gemini Flash, GPT-5.2 (reasoning-effort low) |
Good balance, most tasks |
| good |
Sonnet 4.5 (default) |
Quality-focused development |
| genius |
Opus 4.5, GPT-5.2 (reasoning-effort xhigh) |
Complex architecture, critical tasks |
Notes:
- Droid has no free-tier models, so it only appears in paid modes.
Cost Savings Example
Running a 10-story feature with mixed complexity:
| Mode |
Estimated Cost |
Savings |
| genius |
$2.50 |
— |
| good |
$1.20 |
52% |
| cheap |
$0.60 |
76% |
| free |
$0.00 |
100% |
Usage
# Run with specific mode (auto routing)
relentless run --feature my-feature --mode cheap
# Force a specific harness (disables auto routing)
relentless run --feature my-feature --agent claude
# Override fallback order (auto mode only)
relentless run --feature my-feature --fallback-order opencode,droid,claude
# Skip final review (not recommended)
relentless run --feature my-feature --skip-review
# Custom review mode
relentless run --feature my-feature --review-mode genius
# Tune idle timeout (milliseconds) for stuck/quiet harnesses
RELENTLESS_EXECUTION_TIMEOUT_MS=120000 relentless run --feature my-feature
How It Works
- Classification: Each task is analyzed for complexity (simple, medium, complex, expert)
- Routing: Task is assigned to the optimal model for its complexity and selected mode
- Execution: Agent attempts the task with the assigned model
- Escalation: If the task fails, automatically escalate to a more capable model
- Reporting: Final cost report shows actual vs estimated costs
Escalation Path
When a smaller model fails, Relentless automatically escalates:
haiku-4.5 → sonnet-4.5 → opus-4.5
glm-4.7 → haiku-4.5 → sonnet-4.5
gpt-5.2-low → gpt-5.2-medium → gpt-5.2-high → gpt-5.2-xhigh (maps to `--model gpt-5.2 -c reasoning_effort="low|medium|high|xhigh"` in Codex CLI)
The system tracks costs across all attempts and reports total spend.
Configuration (relentless/config.json)
{
"defaultAgent": "auto",
"autoMode": {
"enabled": true,
"defaultMode": "good",
"fallbackOrder": ["claude", "codex", "droid", "opencode", "amp", "gemini"],
"modeModels": {
"simple": "haiku-4.5",
"medium": "sonnet-4.5",
"complex": "opus-4.5",
"expert": "opus-4.5"
}
}
}
Notes:
defaultAgent: "auto" makes auto routing the default; set to claude, codex, etc. to opt out.autoMode.enabled only affects auto routing; it does not force auto unless defaultAgent is auto.
Key Features
🔄 Universal Agent Orchestration
Run Claude, Amp, OpenCode, Codex, Droid, or Gemini. Switch automatically when rate limits hit. Fall back gracefully. Recover when limits reset.
📋 Structured Specification System
No more vague PRDs. Interactive /relentless.specify creates comprehensive specs with acceptance criteria, dependencies, and success metrics. Inspired by GitHub SpecKit.
🧪 Quality Enforcement
TDD is not optional. E2E tests are not optional. Every story must pass typecheck. Constitution rules (MUST/SHOULD) are enforced. Checklists are loaded into agent prompts.
💰 Smart Auto Mode — Save 50-75%
Why use GPT-5-Pro or Opus 4.5 to rename a variable? Four cost modes (free, cheap, good, genius) route tasks by complexity. Automatic escalation when smaller models fail. Save money. Ship faster.
📊 Beautiful TUI
Real-time progress bars, dynamic story grid that adapts to terminal size, priority badges, phase indicators, research markers. Auto mode now shows the current routing decision and idle time per story.
🔀 Dependency Management
Stories can depend on other stories. Relentless validates, detects circular dependencies, and executes in the correct order.
📝 Constitution + Prompt Generation
/relentless.constitution now creates both constitution.md (project rules) AND prompt.md (personalized agent instructions) by analyzing your project structure.
Supported Agents
| Agent |
Skills |
Commands |
Status |
| Claude Code |
.claude/skills/ |
/relentless.* |
✅ Full support |
| Amp |
.amp/skills/ |
/relentless.* |
✅ Full support |
| OpenCode |
.opencode/skill/ |
/relentless.* |
✅ Full support |
| Codex |
.codex/skills/ |
Manual |
✅ Skills installed |
| Gemini |
.gemini/GEMINI.md |
Manual |
✅ Instructions provided |
| Droid |
Reference .claude/skills/ |
Manual |
✅ Works with prompting |
All agents get skills/instructions installed automatically via relentless init.
Harness Tips
- OpenCode: we enable
--print-logs by default to keep output flowing.
- Codex: GPT-5.2 reasoning tiers map to
--model gpt-5.2 -c reasoning_effort="low|medium|high|xhigh".
- Droid: supports
--reasoning-effort and --auto autonomy levels; use --agent droid to force it.
- Gemini: non-interactive runs use
--prompt; set GEMINI_API_KEY (or Vertex/GCA flags) for auth.
# Check what's installed
relentless agents list
# Health check
relentless agents doctor
Project Structure
After relentless init:
your-project/
├── relentless/
│ ├── config.json # Configuration
│ ├── constitution.md # Project rules (MUST/SHOULD)
│ ├── prompt.md # Personalized agent instructions
│ └── features/
│ └── 001-user-auth/
│ ├── spec.md # Feature specification
│ ├── plan.md # Technical plan
│ ├── tasks.md # User stories
│ ├── checklist.md # Quality checklist
│ ├── prd.json # Orchestration state
│ └── progress.txt # Learnings & context
├── .claude/
│ ├── skills/ # 11 skills for Claude/Amp/OpenCode
│ └── commands/ # /relentless.* command wrappers
├── .amp/skills/ # Copied for Amp
├── .opencode/skill/ # Copied for OpenCode (singular!)
├── .codex/skills/ # Copied for Codex
└── .gemini/GEMINI.md # Instructions for Gemini
The Workflow
Relentless uses a simplified 5-step SpecKit workflow:
| Step |
Command |
Output |
| 1. Specify |
/relentless.specify |
spec.md |
| 2. Plan |
/relentless.plan |
plan.md |
| 3. Tasks |
/relentless.tasks |
tasks.md + prd.json (auto) |
| 4. Analyze |
/relentless.analyze |
Validation report |
| 5. Implement |
relentless run --tui |
Working code |
Optional: /relentless.checklist (between tasks and analyze)
- Generates validation checklist with quality gates
- Recommended for complex features
Note: The tasks command now auto-runs convert.
Manual relentless convert is only needed if you edit tasks.md by hand.
┌─────────────────────────────────────────────────────────────┐
│ │
│ /relentless.constitution → Project rules + prompt.md │
│ ↓ │
│ /relentless.specify → Structured spec │
│ ↓ │
│ /relentless.plan → Technical architecture │
│ ↓ │
│ /relentless.tasks → Stories + prd.json (auto) │
│ ↓ │
│ /relentless.analyze → Validate consistency │
│ ↓ │
│ relentless run --tui → Agent loops until complete │
│ ↓ │
│ ✅ Ship it │
│ │
└─────────────────────────────────────────────────────────────┘
CLI Reference
Core Commands
relentless init # Initialize project; -f if upgrading to force overwrite
relentless run --feature <name> --tui # Run orchestration
relentless status --feature <name> # Show progress
relentless reset <story-id> --feature <name> # Re-run a story
# Auto Mode options
relentless run --feature <name> --mode <free|cheap|good|genius>
relentless run --feature <name> --fallback-order claude,opencode,amp
relentless run --feature <name> --skip-review
relentless run --feature <name> --review-mode <free|cheap|good|genius>
Feature Management
relentless features create <name> # Create feature
relentless features create <name> --auto-number # 001-name, 002-name...
relentless features list # List all features
relentless convert <file> --feature <name> # Convert to JSON
Analysis & Integration
relentless analyze --feature <name> # Cross-artifact consistency
relentless issues --feature <name> # Generate GitHub issues
relentless issues --feature <name> --dry-run # Preview issues
Agent Management
relentless agents list # Show installed agents
relentless agents doctor # Health check
Slash Commands (Claude/Amp/OpenCode/Codex/Droid)
/relentless.constitution # Create project rules + prompt.md
/relentless.specify <desc> # Create feature spec
/relentless.plan [context] # Generate technical plan
/relentless.tasks # Generate user stories
/relentless.checklist # Generate quality checklist
/relentless.clarify # Resolve ambiguities
/relentless.analyze # Cross-artifact analysis
/relentless.implement # Execute implementation
/relentless.taskstoissues # Convert to GitHub issues
Configuration
relentless/config.json:
{
"defaultAgent": "claude",
"agents": {
"claude": {
"model": "sonnet",
"dangerouslyAllowAll": true
}
},
"autoMode": {
"enabled": true,
"defaultMode": "good",
"fallbackOrder": ["claude", "codex", "droid", "opencode", "amp", "gemini"],
"modeModels": {
"simple": "haiku-4.5",
"medium": "sonnet-4.5",
"complex": "opus-4.5",
"expert": "opus-4.5"
},
"review": {
"promptUser": true,
"defaultMode": "good",
"microTasks": ["typecheck", "lint", "test", "security", "quality", "docs"],
"maxRetries": 3
},
"escalation": {
"enabled": true,
"maxAttempts": 3,
"escalationPath": {
"haiku-4.5": "sonnet-4.5",
"sonnet-4.5": "opus-4.5",
"gpt-5.2-low": "gpt-5.2-medium",
"gpt-5.2-medium": "gpt-5.2-high",
"gpt-5.2-high": "gpt-5.2-xhigh"
}
}
},
"fallback": {
"enabled": true,
"priority": ["claude", "amp", "opencode", "codex", "gemini"],
"autoRecovery": true
},
"execution": {
"maxIterations": 20,
"iterationDelay": 2000
},
"quality": {
"requireTypecheck": true,
"requireTests": true,
"enforceConstitution": true
}
}
Auto Mode Settings
| Setting |
Description |
Default |
autoMode.enabled |
Enable smart routing |
true |
autoMode.defaultMode |
Default cost mode |
"good" |
autoMode.fallbackOrder |
Harness priority order |
["claude", "codex", ...] |
autoMode.modeModels |
Model per complexity |
See above |
autoMode.escalation.enabled |
Enable auto-escalation |
true |
autoMode.escalation.maxAttempts |
Max escalation attempts |
3 |
autoMode.review.microTasks |
Review checks to run |
["typecheck", "lint", ...] |
How It Works
The Loop
- Fresh Context — Each iteration spawns new agent with clean context
- Load Constitution — Agent reads project rules (MUST/SHOULD)
- Load Checklist — Quality gates included in agent prompt
- Find Next Story — Pick story with
passes: false and dependencies met
- Implement — Agent codes, tests, commits
- Update PRD — Mark story
passes: true
- Update Progress — Append learnings to
progress.txt
- Repeat — Until all stories pass or max iterations reached
- Complete — Agent outputs
<promise>COMPLETE</promise>
Memory Persistence
Each iteration has access to:
- Git history — All commits from previous iterations
- progress.txt — YAML metadata + learnings
- prd.json — Task completion status
- constitution.md — Project rules
- spec.md, plan.md and tasks.md - F
CLI-оркестратор, который запускает ваш ИИ-агент для кодинга по кругу, пока не будут выполнены все задачи — каждая итерация стартует агента заново с чистым контекстом, а память сохраняется через git-коммиты и файлы прогресса.