Skip to main content

​
AI providers

Wiggum requires an API key from one of these providers:
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.
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:
ServiceConfig commandPurpose
Tavilywiggum config set tavily <key>Web search for current best practices during init
Context7wiggum config set context7 <key>Up-to-date documentation lookup during interviews
Braintrustwiggum 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

OptionDefaultDescription
loop.maxIterations10Max implementation iterations per run
loop.maxE2eAttempts5Max E2E test retries
Override per-run: 
wiggum run my-feature --max-iterations 20 --max-e2e-attempts 10

​
Models

OptionDefaultDescription
loop.defaultModelsonnetModel for implementation and E2E phases
loop.planningModelopusModel for planning and verification phases
loop.codexModelgpt-5.3-codexModel when using Codex CLI
Override per-run: 
wiggum run my-feature --model opus

​
Agent selection

OptionDefaultDescription
loop.codingCliclaudeAgent for implementation: claude or codex
loop.reviewCliclaudeAgent for review phase: claude or codex
loop.reviewModemanualDefault review mode: manual, auto, or merge

​
Claude Code settings

OptionDescription
loop.claudePermissionModeControls Claude Code’s autonomy during loop execution
Permission modes:
ModeBehavior
defaultAsks for approval on each action
acceptEditsApproves file edits automatically, prompts for other actions
planPlan-only mode — shows what it would do without executing
autoMost actions approved automatically
bypassPermissionsFully autonomous, no prompts

​
Codex CLI settings

OptionDescription
loop.codexModelCodex model to use (e.g. gpt-5.3-codex)
loop.codexSandboxSandbox level for Codex execution
loop.codexApprovalPolicyWhen Codex prompts for approval
Sandbox levels:
LevelBehavior
read-onlyCodex can only read files
workspace-writeCodex can read/write files in the project directory (recommended)
danger-full-accessFull filesystem access
Approval policies:
PolicyBehavior
untrustedPrompt on every action
on-failurePrompt only when something fails (recommended)
on-requestPrompt only when Codex explicitly asks
neverFully autonomous

​
Other options

OptionDefaultDescription
loop.disableMcpInAutomatedRunsfalseDisable 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',
  },
};