CLI Reference

agentcost analyze — what an agent will cost, and where it will misbehave, before it has spent anything.

The dashboard reports what your agent already spent. This command asks the same questions about a version that has not run in production yet: what one run will cost, which step dominates it, and where it loops.

It runs entirely on your machine. It reads your prompt and skill files and it never transmits them — no network call is made, and no file content outlives the token count taken from it.

Install

The CLI ships with the SDK. Installing the package registers the agentcost command.

bash

pip install agentcost
agentcost --version

Analysing your files

Point it at the directory holding your system prompt and skill files. It token-counts each one and prices what they cost on every single call — the fixed toll your agent pays before it does any work.

bash

agentcost analyze ./agent --model gpt-4o

By default it reads *.md *.txt *.prompt *.tmpl *.j2 *.jinja *.jinja2 and skips vendored directories such as node_modules, .git and .venv. Override with --pattern:

bash

agentcost analyze ./agent --pattern "*.md" --pattern "*.yaml"

Analysing a test run

For a cost-per-run figure, record one representative run in local mode. Local mode opens no socket and needs no API key, so this works before you have an account.

python

import json
from agentcost import track_costs

track_costs.init(local_mode=True)

with track_costs.workflow("support-triage"):
    with track_costs.step("classify"):
        ...
    with track_costs.tool("search_docs"):
        ...

track_costs.flush()
json.dump(track_costs.get_local_events(), open("run.json", "w"))

Then hand the recording to the analyser, with the volume you expect in production:

bash

agentcost analyze ./agent --events run.json --runs-per-day 2000

Instrumenting with workflow() and step() is optional. An uninstrumented recording still yields a cost per run — it just cannot break that cost down per step, and the report says so.

Reading the report

text

AgentCost pre-deployment analysis
==================================

Prompt and skill files  (gpt-4o)
  3 file(s), 8,163 tokens, $0.020407 per call just to send them
       7,201 tok   5.6% ctx  system.md
         481 tok   0.4% ctx  skills/escalate.md
         481 tok   0.4% ctx  skills/refund.md

Test run
  3 run(s), 4.0 calls per run, $0.044000 per run (worst $0.044000)
    $  0.022000  50.0%   2.0 calls  search_docs
    $  0.020000  45.5%   1.0 calls  draft_reply
    $  0.002000   4.5%   1.0 calls  classify

Projected at 2,000 runs/day: $2,640.00 per month

Findings (3)
  [  high] Step 'search_docs' ran 2.0 times per run; a loop or retry will
           multiply this in production
  [  high] 3 of 3 run(s) made the same call more than once (worst: 2x)
  [medium] 2 files have identical content; sending both pays twice

Nothing in this report was transmitted anywhere.

The percentage beside each step is its share of one run, so the step to optimise is the one at the top rather than the one that looks slowest.

Every finding it can raise

Code	Severity	What it means
step_loops	high	A step ran two or more times per run. In production this multiplies with volume.
repeated_call	high	The same input was sent more than once inside a single run. Everything after the first is avoidable.
oversized_file	high	One file occupies 25% or more of the model's context window, leaving little room for conversation and retrieval.
context_overflow	high	The files together exceed the context window outright.
duplicate_content	medium	Two or more files are byte-identical once whitespace is normalised. Sending both pays twice.
failed_calls	medium	Calls failed during the recorded run.
deep_nesting	medium	Calls nested four or more levels deep, which is where runaway recursion usually begins.
not_instrumented	low	The recorded run had no workflow(), so every call was treated as one run. Per-step figures are unavailable.

Findings are ordered most severe first, and each carries a detail object in the JSON output with the specific paths, counts and trace ids behind it.

All flags

Flag	Value	Purpose
--model	string	Model to price against. Default gpt-4o. Also selects the context window used to judge oversized files.
--events	path	Events from a local-mode run — a JSON array or JSONL. Enables the cost-per-run half of the report.
--runs-per-day	int	Expected production volume. Adds a projected monthly cost.
--pattern	glob	File pattern to include; repeatable. Replaces the defaults below.
--json	path	Also write the full report as JSON, for diffing between builds.
--fail-on	high \| medium \| low	Exit 1 if any finding is at or above this severity. Use in CI.

At least one of a path or --events is required.

Using it in CI

--fail-on turns the report into a gate. Exit codes: 0 clean, 1 a finding met the threshold, 2 the events file could not be read.

yaml

- name: Agent cost check
  run: |
    pip install agentcost
    python tests/record_agent_run.py        # writes run.json in local mode
    agentcost analyze ./agent \
      --events run.json \
      --runs-per-day 2000 \
      --json cost-report.json \
      --fail-on high

Keep cost-report.json as a build artifact and diff it between branches to see cost move before it reaches production.

What it reads, and what it sends

The analyser reads your prompt and skill files. That is more than the SDK ever touches, which is why it runs where the files already are and sends nothing.

No network call is made — there is no endpoint to disable.
No API key or account is needed.
File content is token-counted and hashed for duplicate detection, then goes out of scope. Only counts and paths reach the report.
The JSON report is written where you ask and nowhere else.

The full data model is on the Data & Privacy Architecture page.

SDK Documentation API Reference Privacy Architecture