mcpField
C
cost-track

cost-track

github.com/ruvnetAgent workflows80.0k684 installsUpdated today
Repository

About cost-track

cost-track is a Claude Code skill that reads session usage, calculates per-model USD costs, and saves structured records to AgentDB. It is for tracking spend during or after a session so cost-report and related consumers can use the data.

Key features

  1. 01Reads Claude Code session JSONL
  2. 02Calculates costs by model
  3. 03Stores records in AgentDB
  4. 04Supports session and path overrides
  5. 05Offers dry-run and JSON output

Use cases

  1. 01Capture spend after a work segment
  2. 02Persist the final session tally
  3. 03Track costs periodically in long sessions

MCP support

It uses an MCP memory search tool to verify stored records in the cost-tracking namespace; it does not expose an MCP tool.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ruvnet/ruflo --skill cost-track

After installing, type/cost-trackin Claude Code to confirm it loaded.

Details

From the project README

Cost Track

Reads the active Claude Code session jsonl (~/.claude/projects/<encoded-cwd>/<session>.jsonl), tallies assistant-message usage per model, computes USD cost using REFERENCE.md pricing, and writes a structured record to the cost-tracking AgentDB namespace. This is the producer that gives cost-report and cost-optimize real data to consume.

When to use

  • After a meaningful chunk of work, to capture spend for the report.
  • At session-end to persist the final tally.
  • Periodically during long sessions (cron-friendly — see /loop 30m).

Steps

  1. Run the tracker from the project root:

    node plugins/ruflo-cost-tracker/scripts/track.mjs

    The script auto-discovers the session jsonl from the current working directory. To pin a specific session: TRACK_SESSION=/path/to/session.jsonl. To dry-run (no memory write): TRACK_DRY_RUN=1.

  2. Inspect the markdown summary — total cost, per-model and per-tier breakdowns, and the persisted memory key.

  3. Verify persistence — mcp__plugin_ruflo-core_ruflo__memory_search --query "session-" --namespace cost-tracking should list the new record. cost-report step 1 reads from this namespace.

Record shape (in cost-tracking namespace)

Key: session-<sessionId>. Value (JSON):

{
  "sessionId": "1dba3b8c-...",
  "cwd": "/Users/cohen/Projects/ruflo",
  "startedAt": "2026-05-04T...",
  "endedAt": "2026-05-05T...",
  "messageCount": 234,
  "byModel": {
    "claude-opus-4-7": {
      "tier": "opus",
      "input_tokens": 12345,
      "output_tokens": 6789,
      "cache_creation_input_tokens": 800000,
      "cache_read_input_tokens": 2000000,
      "messages": 50,
      "cost_usd": 1.23
    }
  },
  "byTier": { "haiku": 0.0, "sonnet": 0.45, "opus": 1.23, "unknown": 0 },
  "total_cost_usd": 1.68,
  "capturedAt": "2026-05-05T..."
}

Pricing source of truth

The script's PRICING constant mirrors REFERENCE.md "Model pricing (USD per 1M tokens)". Update both together when prices change. Cache-write tokens are billed at cache_write rate; cache-read tokens at cache_read (per Anthropic billing docs).

Env overrides

EnvDefaultPurpose
TRACK_CWDprocess.cwd()Override which project's sessions to scan
TRACK_SESSIONmost-recent jsonlPin a specific session file
TRACK_OUTunsetAlso write the JSON summary to this path
TRACK_DRY_RUN=1unsetSkip the memory store call
TRACK_QUIET=1unsetSuppress markdown output
TRACK_NAMESPACEcost-trackingOverride target namespace

Cross-references

  • cost-report (consumer) — reads records produced by this skill
  • REFERENCE.md "Cost attribution formula" — the math the script implements
  • cost-budget-check (consumer; landing in P2) — reads totals to evaluate alerts

Comments

Markdown supported