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.

``bash
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

$3

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.

$3

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 |

$3

> "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

$3

`bash
npm install -g @arvorco/relentless


or


bun install -g @arvorco/relentless
`

$3

`bash
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).

$3

If you have Relentless installed from before v0.4.0:

1. Update the package:
`bash
bun install -g @arvorco/relentless
# or: npm install -g @arvorco/relentless
`

2. Important: Re-run the constitution command to get updated templates:
`bash
/relentless.constitution
`

This will detect changes and offer upgrade options for your
constitution.md and prompt.md files.

$3

With Claude Code, Amp, or OpenCode (recommended):
`bash


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):
`bash
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
`

$3

`bash


Auto mode is now the default (use --agent 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

$3

`bash
relentless run --feature [options]
`

Options:
- --agent : Force a specific harness (auto, claude, amp, opencode, codex, droid, gemini).
- --mode : Auto mode cost tier (free, cheap, good, genius).
- --fallback-order : Comma-separated harness order for auto fallback.
- --max-iterations : Limit loop iterations (default: 20).
- --skip-review: Skip final review phase.
- --review-mode : Review quality tier (free, cheap, good, genius).
- --dry-run: Show routing and planning without executing agents.
- --tui: Run the interactive terminal UI.
- --dir : Working directory for the run.

$3

`bash
relentless estimate --feature [--mode ] [--compare]
`

Options:
- --mode : Cost tier for estimation (free, cheap, good, genius).
- --compare: Compare all modes side by side.

$3

`bash
relentless init
relentless convert --feature
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.

$3

- relentless run uses auto routing unless you pass --agent
- 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)

$3

| 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.

$3

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% |

$3

`bash


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
`

$3

1. Classification: Each task is analyzed for complexity (simple, medium, complex, expert)
2. Routing: Task is assigned to the optimal model for its complexity and selected mode
3. Execution: Agent attempts the task with the assigned model
4. Escalation: If the task fails, automatically escalate to a more capable model
5. Reporting: Final cost report shows actual vs estimated costs

$3

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.

$3

`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

$3

Run Claude, Amp, OpenCode, Codex, Droid, or Gemini. Switch automatically when rate limits hit. Fall back gracefully. Recover when limits reset.

$3

No more vague PRDs. Interactive /relentless.specify creates comprehensive specs with acceptance criteria, dependencies, and success metrics. Inspired by GitHub SpecKit.

$3

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.

$3

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.

$3

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.

$3

Stories can depend on other stories. Relentless validates, detects circular dependencies, and executes in the correct order.

$3

/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.

$3

- 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.

`bash


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

$3

`bash
relentless init # Initialize project; -f if upgrading to force overwrite
relentless run --feature --tui # Run orchestration
relentless status --feature # Show progress
relentless reset --feature # Re-run a story

Auto Mode options


relentless run --feature --mode
relentless run --feature --fallback-order claude,opencode,amp
relentless run --feature --skip-review
relentless run --feature --review-mode
`

$3

`bash
relentless features create # Create feature
relentless features create --auto-number # 001-name, 002-name...
relentless features list # List all features
relentless convert --feature # Convert to JSON
`

$3

`bash
relentless analyze --feature # Cross-artifact consistency
relentless issues --feature # Generate GitHub issues
relentless issues --feature --dry-run # Preview issues
`

$3

`bash
relentless agents list # Show installed agents
relentless agents doctor # Health check
`

$3

`bash
/relentless.constitution # Create project rules + prompt.md
/relentless.specify # 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:

`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
}
}
`

$3

| 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

$3

1. Fresh Context — Each iteration spawns new agent with clean context
2. Load Constitution — Agent reads project rules (MUST/SHOULD)
3. Load Checklist — Quality gates included in agent prompt
4. Find Next Story — Pick story with passes: false and dependencies met
5. Implement — Agent codes, tests, commits
6. Update PRD — Mark story passes: true
7. Update Progress — Append learnings to progress.txt
8. Repeat — Until all stories pass or max iterations reached
9. Complete — Agent outputs COMPLETE

$3

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 - Feature specification and task definition files
- checklist.md — Quality validation (now included in prompts!)

---

Writing Good Specs

$3

Each story should be completable in one context window (15-60 minutes).

Good: Add login endpoint, Create user form, Add email validation

Too big: Build authentication system, Refactor the API

$3

Make criteria verifiable:

Good: "Button shows confirmation dialog before deleting"

Bad: "Works correctly", "Good UX"

$3

- Typecheck passes in every story
- Tests pass in every story
- Verify in browser for UI stories

ALWAYS REVIEW YOUR SPECS, PLANS AND PRD FILES!

---

Troubleshooting

| Error | Solution |
|-------|----------|
| Feature not found | relentless features create |
| PRD not found | relentless convert --feature |
| Max iterations reached | Increase --max-iterations or split stories |
| Skills not found | relentless init --force to reinstall |
| High escalation rate | Tasks may be underclassified; try --mode good |
| All harnesses rate limited | Wait for reset or add API keys for more harnesses |
| Cost higher than expected | Check escalation history in prd.json |
| Free mode failing | Some tasks require paid models; try --mode cheap |

$3

Q: Why did my task use Opus when I set --mode cheap?
A: Cheap mode assigns initial models, but escalation can upgrade to more capable models if the task fails repeatedly. Check prd.json for escalation history.

Q: How accurate are cost estimates?
A: Estimates include a 12% buffer for potential escalation. Actual costs may be lower if tasks succeed on first try.

Q: Can I disable escalation?
A: Yes, set autoMode.escalation.enabled: false in config. Tasks will fail instead of escalating.

Q: Which mode should I use?
A: Start with good (default). Use cheap for well-defined tasks. Use genius for complex architecture. Use free only for experimentation and simple tasks, like translation, documentation, change variable names etc.

---

Development

`bash
git clone https://github.com/ArvorCo/Relentless.git
cd Relentless
bun install
bun run bin/relentless.ts --help
bun run typecheck
bun run lint
``

---

References

- Ralph Wiggum Pattern — Original concept by Geoffrey Huntley
- Geoffrey's Video — Watch the pattern in action
- GitHub SpecKit — Inspiration for the specification system
- Ralph by Snarktank — Reference implementation

---

License

MIT License — see LICENSE for details.

---