Agent-Trace

Unified Agent-Trace schema and local profiler for coding agents (Pi, Claude Code, Codex, OpenCode).

Turn an agent's session file into a cost/usage Summary that answers why a session cost what it cost, not just "how many tokens".

Installation & Run (via bunx)

You do not need to install agent-trace globally. You can run it instantly using bunx (or bun x):

# Analyze a single session
bunx @liiiz/agent-trace analyze pi ~/.pi/agent/sessions/xxxx.jsonl

# Analyze all sessions in a folder from the last 7 days
bunx @liiiz/agent-trace analyze pi ~/.pi/agent/sessions --days 7

Output Explanation

When you analyze a session or a directory of sessions, agent-trace produces a structured summary of cost, tokens, context growth, and waste signals.

Here is what the output means:

1. Header & General Stats

=== Session  a2808a82-...  (claude) ===
Cost        $1.37
Tokens      in 1.1M  out 5K  cache_read 0  cache_write 0
Activity    26 tool calls · 8 read · 12 edited · 0 tests · 0 retries

• Cost: The calculated cost based on input/output tokens and cache usage.
• Tokens: Total token counts broken down by Input (in), Output (out), and Cache Reads/Writes.
• Activity: The total volume of work done by the agent (e.g., number of tool calls, file reads, edits, tests run, and CLI command retries).

2. Cost by Activity (Per-Turn Intent)

Cost by Activity (per-turn intent)
  Read       23%
  Edit       42%
  Shell      16%
  Generation 19%

• Breaks down where your money went based on what the agent was doing during each turn:
  • Read: Searching files, listing directories, reading code context.
  • Edit: Modifying files or writing new code.
  • Shell: Running build, test, lint, or custom terminal commands.
  • Generation: Normal chat turns, reasoning, or plans.

3. Context & Cache Metrics

Context
  Input growth  17K → 44K (2.6×)
  Cache hit     0%  (cache saves ≈$0.00)

• Input Growth: Shows how the system prompt + chat history grew from the first turn to the last turn. High growth (e.g., 5× or 10×) indicates a long conversation where the agent kept sending a huge backlog of history.
• Cache Hit: Percentage of tokens served by the model provider's context cache. High hits greatly reduce actual costs.

4. Waste Signals (Estimated)

Waste signals (estimated)
  ⚠ No cache use (capability unclear)
      no cache activity seen; 31 turn(s) with input but cache_read=0
  ⚠ Tool loops ≈$0.22 (16%)
      1 run(s) of 5+ same-tool calls; 5 calls total

This is the profiler aspect of the tool. It flags areas where tokens or money were spent inefficiently:

• No cache use: Warns you if context caching isn't active, which causes repetitive input tokens to be billed at full price on every single turn.
• Tool loops: Detects if the agent got stuck calling the exact same tool repeatedly in a loop (e.g., constantly checking the same file or running the same failing command), estimating the financial cost of that loop.
• Token waste / Redundant context: Flags when the agent loaded huge files into the context but barely changed any code.

Custom Pricing Configuration (pricing.json)

If you are using private deployments, new models, or special enterprise discounts, you can define your own pricing.json and load it via --pricing:

bunx @liiiz/agent-trace analyze pi ~/.pi/agent/sessions --pricing ./my-pricing.json

JSON Format

The JSON file is a simple map keyed by "provider/model". Unit prices are defined as USD per 1 Million tokens.

{
  "anthropic/claude-3-5-sonnet": {
    "input": 3.0,
    "output": 15.0,
    "cache_read": 0.3,
    "cache_write": 3.75
  },
  "openai/gpt-4o": {
    "input": 2.5,
    "output": 10.0,
    "cache_read": 1.25
  }
}

Fields

• input: Standard input token cost (USD / 1M tokens).
• output: Standard output token cost (USD / 1M tokens).
• cache_read: Discounted cost for tokens hit from context cache (USD / 1M tokens).
• cache_write: Cost to write/fill the context cache (USD / 1M tokens).