Relentless

The AI Agent Orchestrator That Never Stops

🆕 Smart Auto Mode: Save 50-75% on AI costs by routing tasks to the right model

Quick Start · Auto Mode · Why Relentless? · Supported Agents · Documentation

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:

1. Update the package:

   bun install -g @arvorco/relentless
   # or: npm install -g @arvorco/relentless

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

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

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

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

Writing Good Specs

Right-Sized Stories

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

Acceptance Criteria

Make criteria verifiable:

Good: "Button shows confirmation dialog before deleting"

Bad: "Works correctly", "Good UX"

Always Include

• 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 <name> | | PRD not found | relentless convert <file> --feature <name> | | 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 |

Auto Mode FAQ

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

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.

Built with 🔥 by Arvor

We don't stop. Ever.