Costs & Usage

Overview

Cost tracking is opt-in and runs out of scripts/cost-upload: after every commit, the script reads ccusage daily, captures git metadata, and stores one entry per Claude Code session in your CloudClawer memory under the path agent-costs. The Costs dashboard reads that same memory file and renders the entries grouped by session, branch, and PR.

Numbers come from ccusage (the Anthropic token-pricing helper) so you see the actual cost of each run, not an estimate.

Cost Entry Structure

Each cost entry captures a complete picture of a session:

{
  "session_id": "sess_01abc…",
  "cost_usd":   0.0041,          // actual dollar cost
  "cache_pct":  94.5,            // % of tokens served from cache
  "cost_str":   "0.0041 (94.5%)",// human-readable summary
  "branch":     "agent/fix-auth",// git branch at time of session
  "commit":     "a1b2c3d",       // HEAD commit SHA
  "prs":        [142],           // PR numbers associated with this session
  "updated_at": 1748000000       // unix timestamp
}

The cache_pctfield is critical for cost optimization. A high cache hit rate (≥ 80%) means Claude is reusing previously computed context tokens, dramatically reducing per-session cost. CloudClawer's persistent memory is specifically designed to maximize cache hits across sessions.

Session Tracking

Run cost-uploadafter every commit to record that session's spend:

# After each commit on a feature branch:
cd scripts && npm run cost-upload

# Output: 0.0041 (94.5%)
# → upserted into CloudClawer memory at path "agent-costs", keyed by session_id.

To associate a cost entry with one or more PRs, pass them on the command line:

npm run cost-upload -- --pr=142 --pr=143

If you started a fresh branch midway through the day, pass --baseso the script only logs the cost delta for this branch rather than the whole day's total:

# Capture the running total before the branch's first commit:
BASE=$(ccusage daily --offline --json | jq -r '.totals.totalCost')
cd scripts && npm run cost-upload -- --base=$BASE

PR Attribution

When you pass a PR number during cost upload, CloudClawer links the session to that PR. In the Costs dashboard, you can filter by PR to see the total AI cost of implementing a feature or fixing a bug.

This enables cost-per-feature analysis — invaluable for teams tracking AI usage ROI.

API Access

There is no dedicated /u/costs endpoint — entries live in your CloudClawer memory and you read them through the standard memory API. The dashboard does the same:

# Fetch the whole agent-costs memory file
GET /u/dkr/memory/file?path=agent-costs
X-API-Key: YOUR_CLOUDCLAWER_KEY

# Response (truncated)
{
  "path": "agent-costs",
  "data": {
    "sess_01abc…": {
      "session_id": "sess_01abc…",
      "cost_usd":   0.0041,
      "cache_pct":  94.5,
      "cost_str":   "0.0041 (94.5%)",
      "branch":     "agent/fix-auth",
      "commit":     "a1b2c3d",
      "prs":        [142],
      "updated_at": 1748000000
    },
    "sess_02def…": { … }
  }
}

Entries are keyed by session_id, so re-running cost-upload in the same session overwrites the previous entry (totals are always cumulative for that session). Filter or aggregate on the client.

Budget Alerts

Set spending limits on a per-capability or per-period basis using process policy budget limits. When the budget is exceeded, the capability is automatically blocked for the remainder of the period.

// In a process policy:
"allow": [
  {
    "capability": "bash",
    "budget_limit": {
      "max_usd": 1.00,
      "period": "daily"
    }
  }
]