Configuration

AI providers

Wiggum requires an API key from one of these providers:

Anthropic
OpenAI
OpenRouter

Set your Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-...

Or use the config command:

wiggum config set anthropic <your-api-key>

Anthropic is the default provider. Models: opus, sonnet.

Set your OpenAI API key:

export OPENAI_API_KEY=sk-...

Or use the config command:

wiggum config set openai <your-api-key>

Models: gpt-4o, gpt-5.3-codex, and others.

Set your OpenRouter API key:

export OPENROUTER_API_KEY=sk-or-...

Or use the config command:

wiggum config set openrouter <your-api-key>

OpenRouter gives you access to models from multiple providers through a single API.

API keys are stored in .ralph/.env.local and never leave your machine.

Coding agent configuration

Wiggum supports multiple coding agents for the Ralph loop. Configure which agent runs each phase:

Setting the default agent

wiggum config set cli claude        # Claude Code for implementation
wiggum config set cli codex         # Codex CLI for implementation
wiggum config set review-cli claude # Claude Code for review/merge phase
wiggum config set review-cli codex  # Codex CLI for review/merge phase

You can mix agents — e.g. Codex for implementation and Claude Code for review:

wiggum config set cli codex
wiggum config set review-cli claude

Per-run overrides

Override the agent for a single run without changing the config:

wiggum run my-feature --cli codex --review-cli claude

Optional services

These services enhance wiggum’s analysis during the scan and interview phases:

Service	Config command	Purpose
Tavily	`wiggum config set tavily <key>`	Web search for current best practices during init
Context7	`wiggum config set context7 <key>`	Up-to-date documentation lookup during interviews
Braintrust	`wiggum config set braintrust <key>`	Tracing and observability for agent execution

Generated files

Running wiggum init creates a .ralph/ directory:

.ralph/
├── ralph.config.cjs               # Stack detection + loop config
├── .env.local                     # API keys (gitignored)
├── .context.json                  # Codebase analysis results
├── prompts/
│   ├── PROMPT.md.tmpl             # Implementation phase prompt
│   ├── PROMPT_feature.md.tmpl     # Planning phase prompt
│   ├── PROMPT_e2e.md.tmpl         # E2E testing prompt
│   ├── PROMPT_verify.md.tmpl      # Verification prompt
│   ├── PROMPT_review_manual.md.tmpl  # Manual review prompt
│   ├── PROMPT_review_auto.md.tmpl    # Auto review prompt
│   └── PROMPT_review_merge.md.tmpl   # Auto-merge review prompt
├── guides/
│   ├── AGENTS.md                  # Agent instructions
│   └── ...                        # Project-specific guides
├── scripts/
│   ├── feature-loop.sh            # The Ralph loop engine
│   └── ralph-monitor.sh           # Monitoring script
├── specs/
│   └── _example.md                # Example spec template
└── LEARNINGS.md                   # Accumulated project learnings

Loop configuration

The ralph.config.cjs file controls all loop behavior:

Iteration limits

Option	Default	Description
`loop.maxIterations`	`10`	Max implementation iterations per run
`loop.maxE2eAttempts`	`5`	Max E2E test retries

Override per-run:

wiggum run my-feature --max-iterations 20 --max-e2e-attempts 10

Models

Option	Default	Description
`loop.defaultModel`	`sonnet`	Model for implementation and E2E phases
`loop.planningModel`	`opus`	Model for planning and verification phases
`loop.codexModel`	`gpt-5.3-codex`	Model when using Codex CLI

Override per-run:

wiggum run my-feature --model opus

Agent selection

Option	Default	Description
`loop.codingCli`	`claude`	Agent for implementation: `claude` or `codex`
`loop.reviewCli`	`claude`	Agent for review phase: `claude` or `codex`
`loop.reviewMode`	`manual`	Default review mode: `manual`, `auto`, or `merge`

Claude Code settings

Option	Description
`loop.claudePermissionMode`	Controls Claude Code’s autonomy during loop execution

Permission modes:

Mode	Behavior
`default`	Asks for approval on each action
`acceptEdits`	Approves file edits automatically, prompts for other actions
`plan`	Plan-only mode — shows what it would do without executing
`auto`	Most actions approved automatically
`bypassPermissions`	Fully autonomous, no prompts

Codex CLI settings

Option	Description
`loop.codexModel`	Codex model to use (e.g. `gpt-5.3-codex`)
`loop.codexSandbox`	Sandbox level for Codex execution
`loop.codexApprovalPolicy`	When Codex prompts for approval

Sandbox levels:

Level	Behavior
`read-only`	Codex can only read files
`workspace-write`	Codex can read/write files in the project directory (recommended)
`danger-full-access`	Full filesystem access

Approval policies:

Policy	Behavior
`untrusted`	Prompt on every action
`on-failure`	Prompt only when something fails (recommended)
`on-request`	Prompt only when Codex explicitly asks
`never`	Fully autonomous

Other options

Option	Default	Description
`loop.disableMcpInAutomatedRuns`	`false`	Disable MCP servers during automated loop execution

Agent configuration

The agent section in ralph.config.cjs controls agent mode behavior:

agent: {
  defaultProvider: 'anthropic',   // AI provider for the orchestrator
  defaultModel: 'opus',           // Model for the orchestrator
}

Agent-specific flags (--labels, --issues, --max-items, etc.) are passed at runtime. See the agent command reference.

Full config example

// ralph.config.cjs
module.exports = {
  name: 'my-project',
  stack: {
    framework: { name: 'next', version: '16', variant: 'app-router' },
    packageManager: 'npm',
    testing: { unit: 'vitest', e2e: 'playwright' },
    styling: 'tailwind',
  },
  commands: {
    dev: 'npm run dev',
    build: 'npm run build',
    test: 'npm test',
    lint: 'npm run lint',
    typecheck: 'npx tsc --noEmit',
  },
  paths: {
    root: '.ralph',
    prompts: '.ralph/prompts',
    guides: '.ralph/guides',
    specs: '.ralph/specs',
    scripts: '.ralph/scripts',
    learnings: '.ralph/LEARNINGS.md',
    agents: '.ralph/AGENTS.md',
  },
  loop: {
    maxIterations: 10,
    maxE2eAttempts: 5,
    defaultModel: 'sonnet',
    planningModel: 'opus',
    codingCli: 'claude',
    reviewCli: 'claude',
    reviewMode: 'auto',
    claudePermissionMode: 'acceptEdits',
  },
  agent: {
    defaultProvider: 'anthropic',
    defaultModel: 'opus',
  },
};

Getting started

Using wiggum

Commands

AI providers

Coding agent configuration

Setting the default agent

Per-run overrides

Optional services

Generated files

Loop configuration

Iteration limits

Models

Agent selection

Claude Code settings

Codex CLI settings

Other options

Agent configuration

Full config example

​AI providers

​Coding agent configuration

​Setting the default agent

​Per-run overrides

​Optional services

​Generated files

​Loop configuration

​Iteration limits

​Models

​Agent selection

​Claude Code settings

​Codex CLI settings

​Other options

​Agent configuration

​Full config example

AI providers

Coding agent configuration

Setting the default agent

Per-run overrides

Optional services

Generated files

Loop configuration

Iteration limits

Models

Agent selection

Claude Code settings

Codex CLI settings

Other options

Agent configuration

Full config example