Cost-as-Code beta

Infracost for LLM agents: the cost delta of every pull request, posted as a comment — and a budget that can fail the build.

The idea

A prompt tweak, an extra tool call, a model swap — agent PRs change your token bill and nobody sees it until the invoice. If your CI already runs an instrumented agent suite (evals, e2e tests, golden traces), you have everything needed to price the change before merge:

1. Base branch run → base.db (cached per commit)
2. PR branch run → head.db
3. stepcost diff → delta table + budget verdict

stepcost diff

stepcost diff base.db head.db                          # totals + budget verdict
stepcost diff base.db head.db --markdown               # PR-comment-ready body
stepcost diff base.db head.db --budget .stepcost.toml  # exit 3 on violation

The markdown output shows total delta, per-feature and per-step tables with direction markers, and the most expensive single trace. Exit codes: 0 within budget, 3 budget exceeded, 2 usage error — script-friendly by design.

Budgets — .stepcost.toml

[budget]
max_total_usd    = 5.00   # absolute ceiling for the head run
max_trace_usd    = 0.25   # ceiling for any single trace
max_increase_pct = 20.0   # head may cost at most base × 1.20

All keys optional; set only the gates you want. Parsed with the standard library — no new dependencies.

GitHub Action

The repo doubles as a composite action that installs stepcost, runs the diff, posts (or updates) the PR comment, and optionally fails the build:

- name: Restore baseline cost DB
  uses: actions/cache/restore@v4
  with: { path: base.db, key: stepcost-base-${{ github.event.pull_request.base.sha }} }

- name: Run instrumented agent suite   # your tests write head.db via a StepCost sink
  run: pytest tests/agent_suite --stepcost-db head.db

- uses: bronette/stepcost@main
  with:
    base-db: base.db
    head-db: head.db
    budget: .stepcost.toml
    fail-on-budget: "true"

Needs permissions: pull-requests: write for the comment. The comment is updated in place on subsequent pushes (no comment spam).

Local HTML report

Same data, shareable file — great for partner demos and cost reviews:

stepcost report ~/.stepcost/my-app.db --html report.html

One self-contained dark-theme page: totals, rollups, waste flags, reconciliation, and collapsible trace trees. No external assets, works offline, safe to attach anywhere (metadata only, as always).