The Ralph Wiggum bash script ecosystem

Search GitHub for “Ralph Wiggum” and you’ll find dozens of bash scripts that wrap Claude Code, Codex, or another coding agent in a loop. The pattern looks something like this:

while true; do
  claude-code "implement the feature described in spec.md"
  if [ $? -eq 0 ]; then
    break
  fi
  sleep 5
done

These scripts are inspired by Geoffrey Huntley’s Ralph loop technique — a method for running autonomous coding loops with checkpoints. The scripts are simple, clever, and they work… sometimes.

The problem is that they solve the execution half of autonomous coding while ignoring the specification half. And the specification half is where most failures originate.

The specification gap

When an autonomous coding loop produces bad code, the instinct is to blame the agent. “Claude got confused.” “The model hallucinated.” “It went off the rails.” But look closer and you’ll usually find the real culprit: a vague or incomplete specification.

Consider these two prompts:

Vague: “Add user authentication to the app”

Specific: “Add email/password authentication using bcrypt for hashing and JWT for sessions. Store users in the existing PostgreSQL database using the User model in src/models/user.ts. Add POST /api/auth/register and POST /api/auth/login endpoints. Return 401 for invalid credentials. Add auth middleware that protects all /api/ routes except /api/auth/*. Use the existing error handling pattern in src/middleware/errors.ts.”

Both prompts can be fed to a bash-script loop. The second one will produce dramatically better results — not because the agent is smarter, but because it has enough context to make correct decisions.

Wiggum CLI exists to bridge this gap.

How Wiggum approaches specification

Wiggum’s wiggum new command doesn’t just take your description and pass it to an agent. It runs an AI-powered interview that uses your codebase context to ask the right questions:

“I see you’re using Express with TypeScript. Should I add auth middleware to the existing chain in src/middleware/index.ts?”
“Your database uses Prisma. Want me to add the User model to schema.prisma or create a separate auth schema?”
“I found existing JWT usage in src/utils/token.ts. Should I extend that or create new auth-specific utilities?”

The interview produces a structured, implementation-ready spec — not a vague paragraph, but a detailed document that references your actual files, patterns, and conventions.

This spec is what gets fed to the Ralph loop. And because the spec is detailed and codebase-aware, the autonomous execution is dramatically more reliable.

Feature-by-feature comparison

Feature	Bash Scripts	Wiggum CLI
Codebase awareness	None — agent sees only what you paste into the prompt	Full scanning via `wiggum init` — maps tech stack, structure, conventions
Specification quality	Manual — depends entirely on how much context you provide	AI-powered interview generates specs using your codebase context
Execution structure	Single-phase loop — everything in one pass	Multi-phase Ralph loop: plan, implement, test, verify, PR
Progress visibility	Terminal output scrolling by	Real-time TUI with phase tracking and status monitoring
Error handling	Retries from scratch on failure	Phase-level checkpoints — retries implementation without re-planning
Agent support	Typically hardcoded to one agent	Agent-agnostic specs for Claude Code, Codex, or any CLI-based agent

Bottom line: Bash scripts work for simple, well-understood tasks. Wiggum is for multi-file features where specification quality determines success or failure.

When bash scripts are enough

Bash scripts work fine for small, well-understood tasks where you can write a detailed prompt yourself:

Fixing a specific bug with a clear reproduction
Adding a single function with known inputs and outputs
Mechanical refactoring (rename this, move that)

For these cases, wrapping an agent in a loop is perfectly reasonable. You don’t need a spec generation step because the task is the spec.

When you need Wiggum

Wiggum shines when the task is complex enough that specification matters:

Multi-file features that touch models, routes, UI, and tests
Features in unfamiliar codebases where you don’t know all the conventions
Team workflows where specs need to be reviewed before execution
Repeated autonomous runs where consistency matters

The time you spend in the wiggum new interview saves multiples in debugging bad autonomous output.

Getting started

$ npm install -g wiggum-cli

wiggum init    # scan your codebase
wiggum new     # AI interview → spec
wiggum run     # Ralph loop execution

The CLI is free and open source. Bring your own API keys. Pro plans add managed keys, a web dashboard, and push notifications.

See the full feature list, check the GitHub repository for documentation, or read What Is Wiggum CLI? for a deeper look.

Wiggum CLI vs Ralph Wiggum Bash Scripts: Why Specs Matter