Skip to main content

Agent Runner

@swamp/agent-runnerv2026.11.11.1· AGPL-3.0-or-later· 10d agoBEHAVIORS
01README

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"]' \
  --json
02Behaviors1
@swamp/agent-runnerv2026.11.11.1agent_runner.ts
fn review()
Run a coding agent review against a set of files and return a structured verdict
fn run()
Run an arbitrary prompt through a coding agent and return the output

Resources

reviewProfile(infinite)— A review profile — prompt template path, default model, tool permissions
reviewResult(infinite)— Structured output from a review run — verdict, findings, and formatted body
runResult(infinite)— Output from an arbitrary agent prompt execution
03Previous Versions10
2026.11.04.1AGPL-3.0-or-later
2026.10.29.1AGPL-3.0-or-later
2026.10.23.1AGPL-3.0-or-later
2026.10.22.1AGPL-3.0-or-later
2026.10.17.3AGPL-3.0-or-later

updated platforms

2026.10.17.1AGPL-3.0-or-later(was none)
2026.10.13.1
2026.09.28.1
2026.08.23.1
2026.08.05.1
04Stats
A
93 / 100
Downloads
3,335
Archive size
57.4 KB
Verified by Swamp
  • 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
05Platforms
06Labels