Prompt Runner SDK

Run ordered prompt sequences with streaming output, automatic git commits, and multi-provider LLM support

What It Does

Prompt Runner SDK executes a sequence of LLM prompts against your codebase. Each prompt is sent to an LLM provider, the response is streamed in real time, and the resulting changes are committed to git automatically.

Streaming output - See responses as they're generated (compact or verbose mode)
Automatic git commits - Each prompt gets its own commit with a predefined message
Multi-provider support - Claude, Codex, and Amp through AgentSessionManager
Progress tracking - Resume interrupted runs with --continue
Multi-repository - Orchestrate prompts across multiple repos with per-repo commits
Per-prompt overrides - Switch providers, models, or tool permissions for individual prompts
Validation - Check config, prompt files, commit messages, and repo references before running

Installation

def deps do
  [{:prompt_runner_sdk, "~> 0.4.0"}]
end

The SDK starts an OTP supervision tree automatically (PromptRunner.Application) with supervisors for task execution and adapter lifecycle.

Quick Example

# runner_config.exs
%{
  project_dir: File.cwd!(),
  prompts_file: "prompts.txt",
  commit_messages_file: "commit-messages.txt",
  progress_file: ".progress",
  log_dir: "logs",
  model: "haiku",
  llm: %{provider: "claude"}
}

# prompts.txt — format: NUM|PHASE|SP|NAME|FILE
01|1|1|Setup database|001-setup.md
02|1|3|Add API layer|002-api.md

# commit-messages.txt
=== COMMIT 01 ===
feat: setup database schema

=== COMMIT 02 ===
feat: add API layer

mix run run_prompts.exs -c runner_config.exs --run 01

CLI

# Info
mix run run_prompts.exs -c config.exs --list              # List prompts + status
mix run run_prompts.exs -c config.exs --validate           # Validate config, files, repos
mix run run_prompts.exs -c config.exs --dry-run 01         # Preview without executing

# Run
mix run run_prompts.exs -c config.exs --run 01             # Run one prompt
mix run run_prompts.exs -c config.exs --run --all          # Run all prompts
mix run run_prompts.exs -c config.exs --run --continue     # Resume from last completed
mix run run_prompts.exs -c config.exs --run --phase 2      # Run all prompts in phase 2

# Options
--no-commit                  # Skip git commits
--project-dir DIR            # Override project_dir
--repo-override name:path    # Override a repo path (repeatable)
--log-mode compact|verbose|studio  # Output mode (default: compact)
--log-meta none|full         # Error detail mode; full prints provider stderr on failures
--events-mode compact|full|off  # JSONL event logging (default: compact)
--tool-output summary|preview|full  # Studio tool verbosity (default: summary)
--cli-confirmation off|warn|require  # Codex CLI model confirmation policy

Rendering Modes

PromptRunner supports three render modes: :compact, :verbose, and :studio. For interactive terminal runs, use :studio (recommended) for readable tool summaries and status symbols, with configurable tool verbosity.

%{
  log_mode: :studio,
  tool_output: :summary # :summary | :preview | :full
}

Error Diagnostics

PromptRunner preserves structured provider failures from AgentSessionManager (provider_error) instead of flattening everything to a generic string. Keep log_meta: :none for concise output, or set log_meta: :full to print redacted/truncated provider stderr details when available.

Codex CLI Confirmation

When using Codex, PromptRunner can verify that the CLI is actually running the model and reasoning effort you configured:

llm: %{
  provider: "codex",
  model: "gpt-5.3-codex",
  cli_confirmation: :warn,  # :off | :warn | :require
  codex_thread_opts: %{reasoning_effort: :xhigh}
}

With :warn (default), mismatches print a warning. With :require, the run fails if the CLI does not confirm the configured settings. Audit lines are written to session logs for traceability.

Multi-Provider Support

Switch between Claude, Codex, and Amp. Override per-prompt:

%{
  llm: %{
    provider: "claude",
    model: "haiku",
    allowed_tools: ["Read", "Write", "Bash"],
    permission_mode: :accept_edits,
    prompt_overrides: %{
      "03" => %{provider: "codex", model: "gpt-5.3-codex"},
      "05" => %{provider: "amp"}
    }
  }
}

Normalized options that work across all providers:

llm: %{
  provider: "claude",
  permission_mode: :dangerously_skip_permissions,
  max_turns: 10,
  system_prompt: "Be concise.",
  sdk_opts: [verbose: true],       # arbitrary provider-specific SDK options
  adapter_opts: %{max_tokens: 16384}  # passed to adapter directly
}

Multi-Repository Support

Target prompts at specific repos. Define repo groups with @ references:

%{
  target_repos: [
    %{name: "frontend", path: "/path/to/frontend", default: true},
    %{name: "backend", path: "/path/to/backend"}
  ],
  repo_groups: %{
    "all" => ["frontend", "backend"]
  }
}

# prompts.txt — 6th field is TARGET_REPOS
01|1|5|Setup both|001-setup.md|@all
02|1|8|Frontend only|002-frontend.md|frontend

# commit-messages.txt — repo-qualified markers
=== COMMIT 01:frontend ===
feat(frontend): initial setup

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

Architecture

run_prompts.exs
       |
  PromptRunner.CLI           -- parse args, route commands
       |
  PromptRunner.Config        -- load, normalize, validate config
       |
  PromptRunner.Runner        -- orchestrate prompt sequence
       |
  PromptRunner.LLMFacade     -- thin delegator (LLM behaviour)
       |
  PromptRunner.Session       -- AgentSessionManager bridge
       |                        starts store + adapter per prompt,
       |                        normalizes events to common format
  AgentSessionManager
   +-- ClaudeAdapter
   +-- CodexAdapter
   +-- AmpAdapter

Supporting modules: Prompts (parse prompts.txt), CommitMessages (parse commit messages), Progress (track completion), Git (commit changes), Validator (pre-run checks), RepoTargets (expand @group references). Rendering is handled by AgentSessionManager.Rendering.

Examples

Example	Description
`examples/simple/`	Single repo, provider override (Claude default, Codex for prompt 02)
`examples/multi_repo_dummy/`	Two repos (alpha, beta), per-repo commits, provider switching

# Try the multi-repo example
bash examples/multi_repo_dummy/setup.sh
mix run run_prompts.exs -c examples/multi_repo_dummy/runner_config.exs --list
mix run run_prompts.exs -c examples/multi_repo_dummy/runner_config.exs --run 01

Guides

Getting Started - Installation, prerequisites, first run
Configuration Reference - All config keys and file formats
Rendering Modes - Compact, verbose, and studio output modes
Multi-Provider Setup - Claude, Codex, Amp configuration
Multi-Repository Workflows - Cross-repo orchestration and repo groups

Development

mix test           # Run tests
mix credo --strict # Lint
mix dialyzer       # Type check
mix docs           # Generate docs

License

MIT - see LICENSE

Next Page → Getting Started