> ## Documentation Index
> Fetch the complete documentation index at: https://wiggum.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Set up AI providers, coding agents, environment variables, and loop behavior.

## AI providers

Wiggum requires an API key from one of these providers:

<Tabs>
  <Tab title="Anthropic">
    Set your Anthropic API key:

    ```bash theme={null}
    export ANTHROPIC_API_KEY=sk-ant-...
    ```

    Or use the config command:

    ```bash theme={null}
    wiggum config set anthropic <your-api-key>
    ```

    Anthropic is the default provider. Models: `opus`, `sonnet`.
  </Tab>

  <Tab title="OpenAI">
    Set your OpenAI API key:

    ```bash theme={null}
    export OPENAI_API_KEY=sk-...
    ```

    Or use the config command:

    ```bash theme={null}
    wiggum config set openai <your-api-key>
    ```

    Models: `gpt-4o`, `gpt-5.3-codex`, and others.
  </Tab>

  <Tab title="OpenRouter">
    Set your OpenRouter API key:

    ```bash theme={null}
    export OPENROUTER_API_KEY=sk-or-...
    ```

    Or use the config command:

    ```bash theme={null}
    wiggum config set openrouter <your-api-key>
    ```

    OpenRouter gives you access to models from multiple providers through a single API.
  </Tab>
</Tabs>

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://tavily.com)         | `wiggum config set tavily <key>`     | Web search for current best practices during init |
| [Context7](https://context7.com)     | `wiggum config set context7 <key>`   | Up-to-date documentation lookup during interviews |
| [Braintrust](https://braintrust.dev) | `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:

```bash theme={null}
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:

```bash theme={null}
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:

```js theme={null}
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](/commands/agent).

## Full config example

```js theme={null}
// 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',
  },
};
```