Agent Runner
Run AI coding agents (Claude, Codex) with structured output for CI integration. Manages agent CLI binaries, resolves API tokens from environment variables or vaults (or uses the CLI's stored login), and returns machine-readable verdicts that CI pipelines can gate on.
Provider-agnostic: each agent backend (Claude Code CLI, OpenAI Codex CLI) is a pluggable provider with its own binary management and CLI flag translation. The common interface is prompt in, structured result out.
Methods
| Method | What it does |
|---|---|
review |
Run a coding agent review against a set of files and return a structured verdict (pass/fail) with findings. Supports an optional diff input for inline diff review mode (faster, no repo exploration). |
run |
Run an arbitrary prompt through a coding agent and return the output. |
Both methods accept optional model and effort arguments (effort is
low, medium, high, xhigh or max, passed as claude --effort or codex
model_reasoning_effort).
Both also accept an optional workingDir (the directory the agent runs in,
such as a git worktree; the CLI stays cached in the swamp repo) and
additionalDirs (--add-dir). With claude, run can continue an earlier
session with resumeSessionId (--resume). run also takes an optional
outputSchema, a JSON Schema the final answer must match, and
persistSession: false, so a claude run leaves no session file behind
(codex keeps none anyway). A run stopped by a usage limit,
rate limit or overloaded API is marked with capacityStop and a
capacityStop tag, so a workflow can retry it later.
Both results carry a usage object with the token counts (and, for
claude, the cost in USD) that the agent CLI reported, per model and in
total, and the CLI's sessionId. Both are absent when the CLI reports
none. Needs Claude Code 1.0.37+ or Codex 0.122.0+.
Runs on Linux, macOS and Windows (x64 and ARM64). On Windows the claude
provider needs Git for Windows. The Codex provider downloads the
@openai/codex platform package from npm and keeps its bundled sandbox
helpers; the Claude binary is verified against the checksum in its release
manifest.
Codex can run through an OpenAI-compatible gateway with a modelProvider
provider config.
Providers
| Provider | CLI | API key env var |
|---|---|---|
claude |
Claude Code | ANTHROPIC_API_KEY |
codex |
OpenAI Codex | CODEX_API_KEY |
Usage
swamp extension pull @swamp/agent-runner
swamp model create @swamp/agent-runner reviewer
swamp model edit reviewer
swamp model method run reviewer review \
--input promptFile=.forgejo/prompts/review.md \
--input 'files:json=["src/main.ts","src/lib.ts"]' \
--jsonResources
updated platforms
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault0/1missing
- files/README.md--Line 47 sets the secret `--global-arg apiKeyEnvVar` to a value written in the docs instead of a vault expression. Keep secrets in a vault: store them with `swamp vault put <vault> <key>`, which prompts for the value, and reference them as `${{ vault.get(<vault>, <key>) }}`.
Fix or accept each secret-unsafe-docs warning: the README, the manifest description and describe strings should store secrets with `swamp vault put <vault> <key>` (it prompts for the value) and pass them as `${{ vault.get(<vault>, <key>) }}`.
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned