AgentCheaper

Make coding agents cheaper without hiding context.

AgentCheaper is a CLI and evaluation toolkit for reducing paid uncached input in coding-agent workflows. It helps you keep repeated agent context stable, audit prompt-cache friendliness, compact deterministic context, and measure cost, latency, and quality with reproducible scorecards.

It does not magically delete every token. It makes repeated context easier for official prompt caches to reuse, and moves deterministic parsing, retrieval, compaction, and validation into the harness when safe.

Why

Long coding-agent sessions repeatedly send large stable prefixes:

• system and developer instructions
• tool definitions and JSON schemas
• project rules such as AGENTS.md
• stable repo context and skill instructions
• session and routing metadata

Prompt caching can make that repeated prefix cheaper, but only if the provider sees the same beginning again. AgentCheaper helps you inspect and improve the parts you can control.

flowchart LR
  A["Baseline agent run"] --> B["Dynamic state appears early"]
  B --> C["Lower cache reuse"]
  C --> D["Higher paid uncached input"]
  E["AgentCheaper run"] --> F["Stable context first"]
  F --> G["Better cache reuse"]
  G --> H["Lower paid uncached input"]
  E --> I["CodeAtlas compact context"]
  I --> H
  E --> J["Eval Center scorecard"]

Loading

Quick Start

Run once with npm/npx from GitHub:

npx github:Harzva/make-agents-cheaper --help

Install globally with npm from GitHub:

npm i -g github:Harzva/make-agents-cheaper
agentcheaper --help

Install with Cargo:

cargo install --git https://github.com/Harzva/make-agents-cheaper
agentcheaper --help

Run from source:

git clone https://github.com/Harzva/make-agents-cheaper.git
cd make-agents-cheaper
cargo run --quiet -- --help
npm run scorecard

Install

npm / npx

GitHub install is supported first:

npm i -g github:Harzva/make-agents-cheaper

Then:

agentcheaper audit --config ~/.codex/config.toml
agentcheaper --print-ws-config
agentcheaper compact-template

One-shot:

npx github:Harzva/make-agents-cheaper audit --config ~/.codex/config.toml

The npm package is a small Node wrapper around the Rust CLI. It tries to build the release binary during install. If no prebuilt binary exists, it falls back to cargo run. Install Rust from rustup.rs when using the GitHub npm route.

Cargo

cargo install --git https://github.com/Harzva/make-agents-cheaper

Agent Prompt

Paste this into Codex, Claude Code, Cursor, or another coding agent:

Install AgentCheaper from https://github.com/Harzva/make-agents-cheaper.

Prefer this order:
1. If npm is available, run: npm i -g github:Harzva/make-agents-cheaper
2. Verify: agentcheaper --help
3. If npm install fails but Rust/Cargo is available, run: cargo install --git https://github.com/Harzva/make-agents-cheaper
4. Run a safe audit only. Do not edit private config unless I explicitly ask.
5. Report:
   - install method used
   - agentcheaper version/help output
   - whether my Codex or Claude Code setup looks prompt-cache friendly
   - any recommended config changes as a dry-run

Never print API keys, .env values, access files, cookies, raw chat logs, or private provider traces.

More copy-paste prompts live in docs/agent-install-prompts.md.

What You Can Do

Audit a Codex config

agentcheaper audit --config ~/.codex/config.toml

The audit checks provider stability, Responses API usage, WebSocket readiness, model setting drift, and prompt-cache friendly defaults. To verify a private router endpoint without committing it:

AGENTCHEAPER_EXPECTED_BASE_URL="https://your-router.example/v1" \
  agentcheaper audit --config ~/.codex/config.toml

The legacy variable MAKE_AGENTS_CHEAPER_EXPECTED_BASE_URL is still accepted.

Print cache-friendly templates

agentcheaper --print-ws-config
agentcheaper --print-http-config
agentcheaper compact-template

Compare baseline vs optimized runs

agentcheaper eval \
  --baseline examples/baseline.jsonl \
  --candidate examples/cache-friendly.jsonl

agentcheaper task-report \
  --baseline examples/baseline.jsonl \
  --candidate examples/cache-friendly.jsonl

Fingerprint prompt layers and tool schemas

agentcheaper fingerprint --input layers.json --previous previous-layers.json
agentcheaper tool-schema --input tools.json --previous previous-tools.json
agentcheaper breakpoints --input request.json

Use CodeAtlas as the code context engine

CodeAtlas is included as AgentCheaper's code context and retrieval engine:

python3 -m pip install -e integrations/codeatlas
python3 -m codeatlas map .
python3 -m codeatlas search "where is config audited?" . --top-k 5 --json

Product direction:

agentcheaper codeatlas index .
agentcheaper codeatlas search "where is auth handled?"

The direct agentcheaper codeatlas subcommands are planned. The integrated Python CodeAtlas path is available now for researchers and advanced users.

Evidence

AgentCheaper keeps its evaluation logic in the same product repository so users can inspect the scoring method.

References:

• Anthropic prompt caching documents the cumulative order tools -> system -> messages and content-block cache breakpoints: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Claude Code CLI documents --exclude-dynamic-system-prompt-sections as moving dynamic system-prompt sections into the first user message: https://code.claude.com/docs/en/cli-usage

Prefix-Cache Evidence Snapshot

The fixed V2 dynamic-drift diagnostic supports the narrow prefix-cache claim: moving dynamic harness state later reduced paid uncached input while preserving task success.

Summary:

• Cache hit rate improved from 91.66% to 97.67%.
• Paid uncached input fell from 30,082 to 7,817 tokens (0.260x).
• Observed cost fell from $0.366976 to $0.258237 (0.704x).
• Validation and task success stayed at 3/3 vs 3/3.
• Output tokens increased slightly, from 2,054 to 2,224, so tool-output optimization remains a separate future layer.

The earlier V2 mixed/negative pilot is retained as a regression case. Diagnosis found a behavioral outlier plus fixture Git-isolation leakage; after fixing absolute prompt paths and fixture-local Git state, the bounded 3-repeat diagnostic returned to the expected direction. This is an incremental prefix optimization: it reduces repeated paid input, but it does not guarantee that tool calls, output verbosity, or agent trajectory will become cheaper.

See docs/v2-prefix-fixed-diagnostic.md, docs/v2-regression-diagnosis.md, and docs/data/v2-prefix-fixed-diagnostic-summary.csv for the derived, commit-safe data. Raw run logs stay ignored under runs/.

Current public scorecard:

Line	Score	Status	Evidence
Prefix Cache	85.36	supported narrowly	fixed diagnostic with observable cache accounting
CodeAtlas Retrieval	60.16	boundary	retrieval quality signal, cost/latency claims still bounded
Code Repair	88.00	supported narrowly	4/4 DeepSeek-routed Claude Code live repair cells passed
CheapDoc	78.00	supported narrowly	compact document representation smoke
Agentic Cost	72.00	boundary	MVP combines live prefix-cache accounting and local proxies
Overall	77.15	boundary	scorecard JSON

The V2 direct-json pilot did not support a broad savings claim; it is kept as negative evidence so regressions and failed slices stay visible.

Run scorer self-tests:

python3 benchmarks/eval-center/scorers/selftest.py

Rebuild the scorecard:

npm run scorecard

Live repair evidence uses a Ponytail-style matrix:

task x arm x model x repeat

The first supported narrow slice is:

2 code-repair tasks x 2 arms x deepseek-chat x 1 repeat

It records provider-billed cost, latency, test pass, diff LOC, and unrelated-change guards. Raw provider traces stay private; public artifacts are sanitized metrics, hashes, summaries, and claim boundaries.

Repository Map

Path	Role
src/	Rust CLI core, upgraded from the earlier make-agents-cheaper research tool
npm/	Node wrapper for npm i, global install, and npx github:Harzva/make-agents-cheaper
integrations/codeatlas/	CodeAtlas code context and retrieval engine
benchmarks/eval-center/	Scorers, schemas, tasks, and public sanitized eval runs
docs/evidence/	Scorecards, release evidence, and provider-route notes
examples/	Small JSONL examples for baseline vs cache-friendly comparisons

Repository Name

This repository is still hosted as Harzva/make-agents-cheaper for continuity. The product, CLI, and npm binary are now named AgentCheaper:

AgentCheaper = product CLI + CodeAtlas context engine + eval center + public scorecard

CodeAtlas remains a named module inside AgentCheaper. DeepSeek CLI and provider API tools are external provider integrations, not vendored secrets or credentials. A future repository rename to Harzva/agentcheaper can happen later; current install commands intentionally use Harzva/make-agents-cheaper.

Safety

Do not commit:

• API keys, cookies, .env values, or access files
• raw Claude Code, Codex, or provider traces
• private memory stores or raw chat logs
• machine-specific absolute paths
• .claude/settings.* with credentials

Public evidence should contain only sanitized metrics, hashes, summaries, fixtures, and scorer code.

Roadmap

• agentcheaper codex audit
• agentcheaper claude audit
• agentcheaper optimize --target codex --dry-run
• agentcheaper optimize --target claude-code --dry-run
• agentcheaper codeatlas index/search
• npm registry release after GitHub install stabilizes
• prebuilt binaries for npm installs without requiring local Rust

License

MIT. See LICENSE.