mcpField
C
cost-session

cost-session

github.com/ruvnetData & databases80.0k249 installsUpdated today
Repository

About cost-session

cost-session analyzes the costs of messages in a single session, calculating and ranking their costs. It shows cache read and write usage and in-session percentiles to help locate specific cost outliers.

Key features

  1. 01Reads JSONL messages for a session
  2. 02Calculates and ranks message costs
  3. 03Shows cache read and write usage
  4. 04Calculates message cost percentiles
  5. 05Flags in-session cost outliers

Use cases

  1. 01Inspect costly messages in an anomalous session
  2. 02Filter session messages by time range
  3. 03Investigate costs from cache writes
  4. 04Compare the top message with in-session percentiles

Install

Copy the command and run it in a terminal.

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

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

Details

From the project README

When cost-anomaly flags a session as a >3.5σ outlier, the next question is "which MESSAGES were expensive?". cost-session answers that.

QuestionSkill
"Which sessions cost the most?"cost-conversation
"Which sessions are outliers?"cost-anomaly
"Which messages in THIS session were expensive?"cost-session ← this

Algorithm

Implementation: scripts/session.mjs.

  1. Resolve session jsonl: --session-id <id> (scans ~/.claude/projects/*/) or --latest (default; picks most-recently-modified jsonl).
  2. Parse all assistant messages with usage blocks.
  3. Cost each message via shared PRICING (_prices.mjs).
  4. Sort descending by cost_usd, surface top-N (default 20).
  5. Compute p50/p90/p99 of message costs for in-session percentile context.
  6. Flag the top message if it's >2× the p99 — that's an in-session outlier.

Why this matters: cache writes are the silent cost

Example real session, top message:

| # | Model    | In | Out | Cache W | Cache R | Cost      |
| 1 | opus-4-7 | 6  | 569 | 881898  | 0       | $16.58    |

Without the Cache W column it looks like "569 output tokens cost $16" — that's wrong by 380×. The actual cost is ephemeral 1h cache write at opus pricing: 881,898 tokens × $18.75/1M = $16.54.

Operators reading the table see immediately: "the model wrote 881K tokens to ephemeral cache". From there the question becomes "why did we cache 881K tokens of context for a 6-input request?" — that's a real engineering signal.

Drill-down workflow

# Step 1: find outliers across all sessions
cost anomaly --alert-on-outliers 1 || cost anomaly  # see which session-ids

# Step 2: drill into the flagged session
cost session --session-id <flagged-id> --top 10

# Step 3: open that jsonl at the timestamp the top message reports,
# inspect the prompt + tool calls

Percentile context

Top of output:

| p50 (median) message | $0.85 |
| p90 message          | $1.45 |
| p99 message          | $1.74 |

Lets operators ask "is this top message a 2× outlier or a 380× one?" without having to compute it themselves. The "top is >2× p99" footer fires when the answer is "yes, this is an in-session outlier worth investigating".

--since filter

Useful for drilling into a specific time range within a long session:

cost session --since 2026-06-16T13:00:00Z --top 5

Only messages with timestamp >= --since are considered.

Edge cases

  • No costed assistant messages → "No costed assistant messages" + exit 0.
  • --session-id not found in any project's jsonls → exit 2 with error.
  • --top must be a positive integer → exit 2.

Comments

Markdown supported