Prompt Runner SDK

Convention-driven prompt orchestration for Elixir, Mix, and production applications

Prompt Runner SDK executes ordered prompt workflows against local repositories. This README targets prompt_runner_sdk ~> 0.5.0 and the provider SDK releases published on Hex on 2026-04-08.

It supports two equally valid styles:

• Convention-driven execution from a directory of numbered .prompt.md files.
• Explicit legacy execution from runner_config.exs, prompts.txt, and commit-messages.txt.

The core engine is library-first. The CLI, Mix task, standalone script, and future release binaries all sit on top of the same runtime.

Highlights

• PromptRunner.run/2, plan/2, validate/2, and run_prompt/2 for embedded use.
• mix prompt_runner ... for local workflows.
• Convention mode with optional front matter and heading-based metadata.
• Runtime store defaults that are safe by context: API calls default to memory/noop commit. CLI calls default to .prompt_runner/ state plus git commits.
• Legacy config compatibility without migration pressure.
• Claude, Codex, Gemini, and Amp support through agent_session_manager.
• Studio, compact, and verbose rendering modes.
• Observer callbacks and an optional PubSub bridge.

Installation

def deps do
  [
    {:prompt_runner_sdk, "~> 0.5.0"},

    # Add the provider SDKs you actually use.
    {:claude_agent_sdk, "~> 0.17.0"},
    {:codex_sdk, "~> 0.16.0"},
    {:gemini_cli_sdk, "~> 0.2.0"},
    {:amp_sdk, "~> 0.5.0"}
  ]
end

Prompt Runner keeps the provider SDKs as explicit optional deps instead of relying on transitive pulls from agent_session_manager. That makes Hex resolution predictable and missing-provider failures easier to diagnose.

Quick Start

1. Create a prompt directory

prompts/01_auth.prompt.md

# Reconcile auth ownership

## Mission

Align the auth architecture across code and docs.

## Validation Commands

- `mix test`

2. Run it from Mix

mix prompt_runner run ./prompts --target /path/to/repo --provider claude --model haiku

3. List or inspect the plan

mix prompt_runner list ./prompts --target /path/to/repo
mix prompt_runner plan ./prompts --target /path/to/repo

CLI runs store progress and logs in ./prompts/.prompt_runner/ by default.

Programmatic API

{:ok, plan} =
  PromptRunner.plan("./prompts",
    target: "/path/to/repo",
    provider: :claude,
    model: "haiku"
  )

{:ok, run} =
  PromptRunner.run("./prompts",
    target: "/path/to/repo",
    provider: :claude,
    model: "haiku",
    on_event: fn event -> IO.inspect(event.type) end
  )

Single prompt execution works without any files:

{:ok, run} =
  PromptRunner.run_prompt(
    "Create hello.txt with a greeting.",
    target: "/path/to/repo",
    provider: :claude,
    model: "haiku"
  )

API calls default to:

• MemoryStore for progress/state.
• NoopCommitter for post-run behavior.

That keeps embedded production use free of surprise filesystem writes and git commits unless you explicitly opt into them.

CLI Surfaces

Mix task

mix prompt_runner list ./prompts --target /repo
mix prompt_runner run ./prompts --target /repo
mix prompt_runner validate ./prompts --target /repo
mix prompt_runner scaffold ./prompts --output ./generated --target /repo

Standalone script

The root run_prompts.exs file remains available for legacy config-driven runs:

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

Escript

mix escript.build
./prompt_runner list ./prompts --target /repo

Legacy Config Mode

Existing v0.4 projects continue to work:

mix run run_prompts.exs --config runner_config.exs --list
mix run run_prompts.exs --config runner_config.exs --run 01
mix run run_prompts.exs --config runner_config.exs --run --all

Legacy config is still the right fit when you want:

• hand-authored prompts.txt
• hand-authored commit-messages.txt
• per-prompt provider overrides via prompt_overrides
• fixed checked-in runner files

Documentation Map

• Getting Started
• Convention Mode
• CLI Guide
• API Guide
• Configuration Reference
• Legacy Config Mode
• Provider Guide
• Rendering Modes
• Multi-Repository Workflows
• Architecture
• Migration Notes
• Examples

Examples

• examples/simple/ shows the explicit legacy single-repo workflow.
• examples/multi_repo_dummy/ shows explicit multi-repo commits.

Development

mix test
mix format
mix credo --strict
mix docs

For sibling-repo development against local checkouts of agent_session_manager or the provider SDKs, opt in explicitly:

PROMPT_RUNNER_USE_LOCAL_DEPS=1 mix deps.get
PROMPT_RUNNER_USE_LOCAL_DEPS=1 mix test

Hex remains the default dependency source, and mix hex.build / mix hex.publish ignore that local-deps opt-in so package metadata stays Hex-clean.

License

MIT

Resume-First Recovery

prompt_runner_sdk now treats provider-native session continuation as the first recovery path for recoverable transport/protocol failures.

• prompt runs cache provider-native recovery metadata as the stream progresses
• recoverable protocol/transport failures trigger an exact-session resume attempt with Continue before any prompt replay is considered
• the runner preserves the original/root provider error and attaches any failed recovery attempt as secondary context instead of overwriting it with generic transport noise
• prompt-numbering --continue remains distinct from provider session continuation

This repo now depends on the current agent_session_manager session runtime rather than the older adapter seam so those recovery handles can flow end to end.