Agent Cost Profiler

English | 简体中文

See where your coding agent spent the money.

Agent Cost Profiler is a local-first token, context, and tool-call profiler for AI coding agents. It answers one expensive question:

Why did this small task spend so much context and money?

It wraps agent commands, imports Codex archived sessions, and turns noisy local telemetry into HTML/JSON reports you can inspect before changing prompts, instructions, or workflows.

npm install
npm run demo:assets

Then open:

• docs/assets/demo/agent-cost-report.share.html
• docs/assets/demo/agent-cost-compare.html

The public demo uses only synthetic Codex archived-session fixtures checked into this repository. It does not read your real ~/.codex data.

See docs/demo.md for manual demo commands and asset-generation details.

From GitHub source:

git clone https://github.com/whitewooood/agent-cost.git
cd agent-cost
npm install
npm run build
npm link
agent-cost doctor

Without global linking:

node dist/cli.js doctor
node dist/cli.js run -- npm test
node dist/cli.js report

GitHub release tarballs can also be installed locally:

npm install -g ./whitewoood-agent-cost-0.2.0.tgz
agent-cost doctor

• Wrap an agent command and collect a run trace.
• Auto-link high-confidence Codex archived sessions after wrapped Codex runs.
• Import and inspect local Codex archived sessions when auto-linking is not certain.
• Show token usage, cache ratio, context-window usage, last-turn metrics, tool calls, command failures, repeated commands, output volume, and git diff size.
• Generate local report.html, report.json, share-safe reports, and before/after compare reports.
• Compare two runs to show whether changes reduced output, estimated tokens, waste patterns, or time.
• Generate a share-safe report that redacts local paths, command arguments, log previews, file paths, and evidence strings.
• Keep all source code, prompts, and traces local by default.

agent-cost run -- codex "fix the failing test"
agent-cost run --adapter codex -- codex "fix the failing test"
agent-cost run --adapter codex --codex-archive-dir fixtures/codex -- codex "fix the failing test"
agent-cost report
agent-cost report --share-safe
agent-cost compare <baseline-run> <candidate-run>
agent-cost adapters
agent-cost codex sessions --limit 10
agent-cost codex preview <session-id>
agent-cost codex import <session-id>
agent-cost import codex-session <jsonl-path>

When the codex adapter is selected, Agent Cost scans local archived sessions after the wrapped process exits. It auto-links only high-confidence matches based on run time, cwd, importability, and Codex telemetry signals. If the match is missing, weak, or ambiguous, the run records a warning and leaves manual inspection available through agent-cost codex sessions, agent-cost codex preview, and agent-cost codex import.

• A hosted SaaS dashboard.
• Deep integration with every agent runtime.
• Perfect token accounting for closed tools that do not expose usage metadata.
• Blocking or controlling agent behavior. v0 observes and reports.

See docs/architecture.md.

Project-facing documentation should be maintained in English and Simplified Chinese. See docs/i18n.md for the documentation language policy.

npm install
npm run build
node dist/cli.js doctor
node dist/cli.js adapters
node dist/cli.js run -- node -e "console.log('hello from agent-cost')"
node dist/cli.js run --adapter generic -- node -e "console.log('hello from agent-cost')"
node dist/cli.js report
node dist/cli.js report --share-safe
node dist/cli.js compare <baseline-run> <candidate-run>
node dist/cli.js import codex-session <jsonl-path>
node dist/cli.js codex sessions --limit 10
node dist/cli.js codex preview <session-id>
node dist/cli.js codex import <session-id>

Generated runs are stored under .agent-cost/runs/; generated comparisons are stored under .agent-cost/compares/. Both are ignored by git.

node dist/cli.js run -- node examples/noisy-agent-run.js
node dist/cli.js report

node dist/cli.js codex sessions --dir examples/fixtures/codex-archives
node dist/cli.js codex preview --dir examples/fixtures/codex-archives launch-baseline

The example intentionally repeats a diagnostic line and writes example-output.txt, so the report has a visible waste pattern to show. The Codex fixture is synthetic and safe to use in screenshots, docs, and tests.

Current adapters:

• generic: stable default adapter for any command.
• codex: experimental adapter. It captures the wrapped process and attempts high-confidence auto-linking to local Codex archived sessions for token and tool telemetry.

See docs/codex-telemetry.md for Codex telemetry and auto-linking details.

agent-cost codex sessions
agent-cost codex sessions --cwd /path/to/project --since 7d --limit 20
agent-cost codex sessions --json
agent-cost codex preview <session-id>
agent-cost codex import <session-id>
agent-cost import codex-session ~/.codex/archived_sessions/session.jsonl

agent-cost codex sessions scans ~/.codex/archived_sessions by default. Use --dir <path> for synthetic fixtures or alternate Codex archive locations. The scanner reads only archived session JSONL files from that directory; it does not read Codex auth files or other sensitive configuration.

The compatibility import command is still available: agent-cost import codex-session <jsonl-path>. The newer agent-cost codex import <session-id-or-path> resolves unique session ids from the scan directory, then uses the same importer.

Imported sessions produce normal report.json and report.html files with model usage, token summary, cache/context metrics, and merged tool-call tables. agent-cost compare also shows token, cache-ratio, failed-tool, and command-count deltas when the compared runs include Codex telemetry.