Configuration Management

Manage iteration workflow configuration for models and parallel agents.

Config File Locations

•Global: ~/.claude/iterate-config.json
•Project: .claude/iterate-config.local.json

Project config overrides global config, which overrides defaults.

Default Configuration

json

{
  "version": 1,
  "blockOnSeverity": "low",
  "phases": {
    "1": { "model": "inherit", "parallel": true, "parallelModel": "inherit" },
    "2": { "model": "inherit", "parallel": true, "parallelModel": "inherit" },
    "3": { "tool": "mcp__codex-high__codex" },
    "4": {
      "model": "inherit",
      "parallel": false,
      "implementer": "claude",
      "bugFixer": "codex-high"
    },
    "5": { "model": "inherit", "parallel": false, "bugFixer": "codex-high" },
    "6": { "model": null },
    "7": { "model": "inherit", "parallel": false, "bugFixer": "codex-high" },
    "8": { "tool": "mcp__codex-high__codex", "bugFixer": "codex-high" },
    "9": { "tool": "mcp__codex-xhigh__codex" }
  }
}

Reading Configuration

•Start with default config (above)
•Read global config from ~/.claude/iterate-config.json if exists
•Deep merge global over defaults (per-phase override)
•Read project config from .claude/iterate-config.local.json if exists
•Deep merge project over global (per-phase override)
•Return merged config

Merge Logic (Per-Phase Deep Merge)

Each phase's config is merged individually:

code

Default:  { "phases": { "1": { "model": "inherit", "parallel": true } } }
Global:   { "phases": { "1": { "model": "sonnet" } } }
Project:  { "phases": { "1": { "parallel": false } } }
Result:   { "phases": { "1": { "model": "sonnet", "parallel": false } } }

To "unset" a value back to default: delete the key from config file.

Writing Configuration

•Determine target file (global or project)
•If target directory doesn't exist, create with mkdir -p
•If file exists, create backup with .backup suffix
•Write JSON with 2-space indentation
•Report success with backup location if created

Validation Rules

Setting	Valid Values
blockOnSeverity	`high`, `medium`, `low` (blocks on specified level and above)

Phase	Key	Valid Values
1,2,4,5,7	model	`inherit`, or any valid model name (see Model Names below)
1,2	parallel	`true`, `false`
3,8	tool	`mcp__codex-high__codex`, `mcp__codex-xhigh__codex`, `claude-review`
4	implementer	`claude`, `codex-high`, `codex-xhigh` (who writes initial code)
4,5,7,8	bugFixer	`claude`, `codex-high`, `codex-xhigh` (who fixes review issues)
6	model	`null` only (bash phase, not configurable)
9	tool	`mcp__codex-xhigh__codex` only (not configurable)

Model Names

The model field accepts several formats:

Short Names (latest version)

•sonnet - Claude Sonnet (latest)
•opus - Claude Opus (latest)
•haiku - Claude Haiku (latest)

Versioned Names (specific version)

•opus-4.5 - Claude Opus 4.5
•opus-4 - Claude Opus 4
•sonnet-4 - Claude Sonnet 4
•sonnet-3.5 - Claude Sonnet 3.5
•haiku-3.5 - Claude Haiku 3.5

Full Model IDs

For maximum control, use the full model identifier:

•claude-opus-4-5-20251101
•claude-sonnet-4-20250514
•claude-sonnet-3-5-20241022

Special Value

•inherit - Use the current session's model (recommended default)

Error Handling

•Invalid JSON: warn user, use defaults for that file
•Unknown phase key: ignore and warn
•Invalid model/tool value: warn user, use default for that phase
•Unreadable file: warn user, continue with available config

Platform Compatibility

Use $HOME environment variable for home directory path. Works on Linux, macOS, and Windows with Git Bash.