agent-cost

Local preflight estimates for coding-agent runs. agent-cost prices the current OpenRouter text-model catalog, optionally buys up to five bounded planning probes, compares API cost with subscription quota pressure, and learns from outcomes you record locally.

Requirements

• Node.js 22.12 or newer
• Git
• An OpenRouter API key with a spending limit appropriate for paid probes

Install

Install the CLI from npm:

npm install --global @devinat1/agent-cost

Install the agent-cost skill for Codex or Claude Code with the standard skill installer:

npx skills add devinat1/agent-cost --skill agent-cost

Then invoke /agent-cost in a Git-backed coding workspace. The skill infers the task from the conversation, installs the CLI when missing, runs first-time profile setup, and returns the balanced model's predicted cost range and confidence.

First-time setup

agent-cost profile

If OPENROUTER_API_KEY is not already exported, setup prompts for it without echoing and stores it in the platform user config directory with owner-only permissions where supported. An exported environment variable always takes precedence.

Workflow

Select the models and access paths you use:

agent-cost profile

Estimate a task. The CLI previews every file region it will transmit and asks before spending money:

agent-cost preflight \
  --repo /path/to/repository \
  --task "Refactor the billing domain without changing its public API"

Defaults are an 80% prediction interval and a combined $0.50 cap for candidate probes plus the fixed evaluator. Useful flags:

agent-cost preflight --repo . --task @TASK.md --probe-budget 0.25
agent-cost preflight --repo . --task "..." --no-probe --json
agent-cost preflight --repo . --task "..." --yes

After the real run, record its outcome. One coding run can contain several OpenRouter generations:

agent-cost record <estimate-id> \
  --generation-id gen-first \
  --generation-id gen-second \
  --duration 42 \
  --completion yes

For subscription runs, select the estimated access path interactively and provide observed quota before/after:

agent-cost record <estimate-id> \
  --model anthropic/claude-sonnet-5 \
  --access claude \
  --tier "Max 5x" \
  --duration 55 \
  --quota-before 80 \
  --quota-after 68 \
  --completion yes

Check calibration:

agent-cost history
agent-cost history --json

The v1 target is roughly eight actual results inside their configured 80% ranges over ten representative repository refactors. Ten observations are an early signal, not statistical proof.

What the estimates mean

• OpenRouter paths show predicted dollar ranges using the live catalog prices.
• Codex subscriptions use the shipped, sourced five-hour model/tier ranges.
• Cursor uses guaranteed included API-equivalent monthly usage and excludes unspecified bonuses.
• Claude Code uses historical official prompt ranges because current limits are dynamic; these estimates are always labeled experimental.
• Unprobed catalog models remain visible in JSON with very-low confidence.
• Quality differences are evaluator-score differences, not success probabilities.

Subscription rules live in rules/subscriptions.json. Each release records the source and check date. Rules older than 45 days warn; rules older than 180 days force very-low confidence.

Privacy and spending

• Only Git-tracked text files are considered.
• Conventional credential files, generated/vendor directories, binaries, and files larger than 2 MiB are excluded.
• Common key patterns are redacted, but the filter is not a guarantee. Review the displayed file list before confirming.
• Probe calls use OpenRouter provider routing with data collection denied and a maximum advertised provider price.
• Calls run sequentially without automatic retries. Seventy percent of the cap is reserved for candidates and thirty percent for evaluation.
• Profiles, estimates, tasks, plans, and observations stay in the platform config/data directories. API keys come from OPENROUTER_API_KEY or the owner-only user config .env; repository .env files are never used.

Development

npm test
npm run typecheck
npm run build

Automated tests mock OpenRouter and never make paid calls.

Explicit non-goals

No model hosting, agent execution, hosted calibration, cross-user data, automatic subscription detection, organization-specific plans, repository modification, or non-coding tasks.