Configuration Reference

Configuration lives in a runner_config.exs file — an Elixir script that evaluates to a map. It is loaded by PromptRunner.Config.load/1.

Full Config

%{
  # === Required ===
  project_dir: "/path/to/project",
  prompts_file: "prompts.txt",
  commit_messages_file: "commit-messages.txt",
  progress_file: ".progress",
  log_dir: "logs",
  model: "haiku",

  # === Optional: Multi-repo ===
  target_repos: [
    %{name: "app", path: "/path/to/app", default: true},
    %{name: "lib", path: "/path/to/lib"}
  ],
  repo_groups: %{
    "all" => ["app", "lib"]
  },

  # === Optional: LLM ===
  llm: %{
    provider: "claude",
    model: "haiku",
    permission_mode: :accept_edits,
    allowed_tools: ["Read", "Write", "Bash"],
    max_turns: nil,
    system_prompt: nil,
    sdk_opts: [],
    adapter_opts: %{},
    claude_opts: %{},
    codex_opts: %{},
    codex_thread_opts: %{},
    prompt_overrides: %{
      "03" => %{provider: "codex", model: "gpt-5.3-codex"}
    }
  },

  # === Optional: Display ===
  log_mode: :compact,
  log_meta: :none,
  events_mode: :compact,
  tool_output: :summary,
  phase_names: %{1 => "Setup", 2 => "Implementation"}
}

Required Fields

All relative paths are resolved against the directory containing the config file.

LLM Section

The llm map controls provider selection, tool permissions, and per-prompt overrides.

Config Precedence

For each prompt, PromptRunner.Config.llm_for_prompt/2 deep-merges in this order (lowest to highest):

1. Root-level keys (model, allowed_tools, permission_mode, etc.)
2. llm section values
3. prompt_overrides entry for the specific prompt number

The resulting map is passed to PromptRunner.Session.start_stream/2.

Provider Aliases

The provider key accepts multiple aliases. The legacy sdk key is also accepted for backward compatibility.

# All equivalent:
llm: %{provider: "claude"}
llm: %{sdk: "claude_agent_sdk"}
llm: %{provider: "claude_agent"}

prompt_overrides

Override any LLM setting for a specific prompt. Keys can be integers (auto-padded to "02" format) or strings:

llm: %{
  provider: "claude",
  model: "haiku",
  prompt_overrides: %{
    "03" => %{provider: "codex", model: "gpt-5.3-codex"},
    5 => %{model: "sonnet", adapter_opts: %{max_tokens: 16384}}
  }
}

Overrides are deep-merged, so you only need to specify the fields that change.

adapter_opts

Provider-agnostic options passed directly to the AgentSessionManager adapter. This map is merged after provider-specific options (claude_opts, codex_opts, etc.), so it takes precedence:

llm: %{
  provider: "claude",
  adapter_opts: %{max_tokens: 8192}
}

adapter_opts can also appear at the root level of the config. The llm-scoped value takes precedence if both are present.

Multi-Repo Fields

See the Multi-Repository Workflows guide for full details.

Codex CLI Confirmation

When using Codex, the runner can verify that the CLI is actually using the model and reasoning effort you configured. This is controlled by the cli_confirmation setting:

llm: %{
  provider: "codex",
  model: "gpt-5.3-codex",
  cli_confirmation: :warn,
  codex_thread_opts: %{reasoning_effort: :xhigh},
  prompt_overrides: %{
    "03" => %{cli_confirmation: :require}
  }
}

Machine-readable audit lines (LLM_AUDIT, LLM_AUDIT_CONFIRMED, LLM_AUDIT_RESULT) are always written to the session log file for traceability, regardless of the confirmation mode.

CLI flags: --cli-confirmation off|warn|require and --require-cli-confirmation (shortcut for require).

Timeout Configuration

The timeout field accepts:

• Positive integer (milliseconds): timeout: 300_000
• :unbounded or :infinity atoms: no practical limit (capped at 7 days internally)
• String equivalents: "unbounded", "infinity", "infinite", or numeric strings like "300000"
• nil (default): uses the emergency cap (7 days)

Timeout can be set at the top level, in the llm section, or per-prompt via prompt_overrides.

Display Fields

File Formats

prompts.txt

Each line defines one prompt. Lines starting with # or blank lines are skipped.

NUM|PHASE|SP|NAME|FILE[|TARGET_REPOS]

commit-messages.txt

Markers delimit commit messages. Text between markers is the full commit message (can be multi-line).

Single repo:

=== COMMIT 01 ===
feat: setup database schema

Multi-repo (repo-qualified):

=== COMMIT 01:frontend ===
feat(frontend): initial setup

=== COMMIT 01:backend ===
feat(backend): initial setup

The marker regex is: === COMMIT (\d+)(?::(\w+))? ===

For multi-repo prompts, the SDK looks for NN:repo_name first, then falls back to NN.

progress file

Append-only log of prompt execution results. Format:

NUM:STATUS:TIMESTAMP[:COMMIT_INFO]

The SDK reads the last entry per prompt number when determining status.

Logging

Each prompt execution produces two log files in log_dir:

1. Text log (NN-name.log) - Plain text with ANSI codes stripped
2. Events log (NN-name.events.jsonl) - One JSON object per line

The events file detail level is controlled by events_mode:

• :off - No events file
• :compact - Abbreviated field names and short type codes
• :full - All event fields preserved

Validation

PromptRunner.Validator.validate_all/1 (invoked by --validate) checks:

1. Every prompt has a matching commit message (or repo-specific variants)
2. Every prompt markdown file exists
3. Every TARGET_REPOS reference resolves to a configured repo (including @group expansion)

Errors are collected and reported together with pass/fail indicators.