@postqode/headless-agent

A no-UI agent runner built on the PostQode SDK. It's the entrypoint you call from a CLI, a queue worker, or — its primary target — a GitHub Actions workflow that runs the agent in CI.

It's a thin, opinionated layer over the SDK:

• Provider via @postqode/ai (buildApiHandler)
• Tools + prompt via @postqode/coding-agent (createCodingAgent)
• Loop via @postqode/agent (Agent / LoopAgent)

…plus the four things the raw SDK leaves to the embedder:

| Concern | What this package adds | |---|---| | Cost budget | A metered ApiHandler wrapper that aborts the run when accumulated USD crosses maxCostUsd — no SDK change required. | | Sessions | Append-only JSONL conversation log; resume by passing the same --session file. | | Resilience | One retry on transient (429/5xx/timeout) errors, but only before any tool has run, so side effects never duplicate. | | CI context | First-class GitHub Actions helpers: read the event, derive a prompt, write GITHUB_OUTPUT + step summary. |

Programmatic use

import { loadConfig, runHeadless } from "@postqode/headless-agent"

const config = loadConfig({ provider: "anthropic", maxCostUsd: 0.5 })
const result = await runHeadless({
  config,
  prompt: "Fix the failing test in src/foo.ts",
  onEvent: (e) => { if (e.type === "text_delta") process.stdout.write(e.delta) },
})

console.log(result.stopReason)  // "completed" | "max_turns" | "max_cost" | "aborted" | "error"
console.log(result.usage.costUsd)

CLI

postqode-headless "Summarize the changes on this branch"
echo "review this diff" | postqode-headless --json
postqode-headless --provider openrouter --model anthropic/claude-sonnet-4.5 --max-cost 0.50

Prompt precedence: positional arg / --prompt → piped stdin → the triggering GitHub event. Exit codes: 0 completed, 2 stopped on a budget cap (max_turns / max_cost), 1 error.

Config precedence (low → high): built-in defaults → agent.config.json in cwd → env vars (POSTQODE_PROVIDER, POSTQODE_MODEL, POSTQODE_API_KEY, …) → CLI flags. API keys also fall back to the provider's conventional env var (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY).

Project context (.postqode/)

By default the runner folds the project's .postqode/rules/ (every file, recursive — plus a legacy .clinerules) and an index of .postqode/skills/ (name + description per SKILL.md) into the system prompt — parity with the VS Code extension. Skill bodies aren't inlined; the agent can read_file one when it needs the detail. Disable with loadProjectContext: false (or compose your own via the exported postqodeProjectLoader() InstructionLoader).

GitHub Actions

The agent runs in CI and reports back via outputs + the run's step summary. See examples/github-action.yml for a workflow that triggers on an issue comment, runs the agent against the checked-out repo, and exposes steps.agent.outputs.text / .stop_reason / .cost_usd to later steps.

In CI the runner auto-defaults cwd to GITHUB_WORKSPACE and, when no prompt is passed, derives one from the event (issue/PR title+body, or a comment body).