Skip to main content
skill CX Codex

cost-session — Claude Code skill: what it does, how to install

cost-session is a Claude Code skill that breaks down costs per message in a session to reveal expensive requests.

MIT 249 installs ★ 82,234 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ruvnet/ruflo --skill cost-session -a claude-code
Open on GitHub

What cost-session does

The skill runs [scripts/session.mjs](../../scripts/session.mjs) to parse session JSONL logs, pricing each message by tokens and cache usage. It computes p50, p90, and p99 percentiles to surface in-session outliers that exceed twice the p99 benchmark.

The skill relies on the Bash tool to execute Node.js scripts and scan local project directories. Missing session IDs return exit code 2 with an error.

Node.js and Claude Code must be available in your environment to execute the scripts.

What it helps with

  • break down session cost per message
  • locate expensive requests and cache writes
  • compute p50 and p99 cost percentiles
  • filter messages by timestamp using --since

Example prompts for the agent

  • Break down session --session-id <id> by message cost
  • Show top 10 expensive messages in the session
  • Analyze messages since 2026-06-16T13:00:00Z

How to install cost-session

1Skills CLI (Vercel)

npx skills add ruvnet/ruflo --skill cost-session -a claude-code

2Manually: put the files in place

~/.claude/skills/cost-session/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cost-session/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cost-session

How to install cost-session in Claude Code?

Run npx skills add ruvnet/ruflo --skill cost-session -a claude-code, then check ~/.claude/skills/cost-session/SKILL.md.

What does cost-session do?

It parses session logs to attribute costs per message, calculates cost percentiles, and flags expensive outliers.

What is required to run cost-session?

The skill requires the Bash allowed tool, Node.js, and local session JSONL files stored under ~/.claude/projects/*/.

Source text

SKILL.md · MIT
---
name: cost-session
description: Per-message cost breakdown within a single session. The drill-down companion to cost-anomaly — when an outlier session is flagged, this surfaces the specific expensive messages so operators can see whether the cost came from output tokens, cache writes, or model escalations.
argument-hint: "[--session-id <id>] [--top 20] [--since <iso-ts>] [--format table|json]"
allowed-tools: Bash
disable-model-invocation: true
---

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

| Question | Skill |
|---|---|
| "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`](../../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

```bash
# 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:

```bash
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.

© ruvnet · MIT · ruvnet/ruflo

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set155

The whole set →
gaia-submission gaia-submission runs the full GAIA benchmark pipeline from API key checks to building a HAL-compatible submission package. Useful when evaluating agent accuracy. CX Codex +1 436installs gaia-debugging gaia-debugging diagnoses why a GAIA benchmark task failed: extracts the trace, classifies the failure mode, and proposes a fix. Runs when gaia-bench run reports failed or incorrect answer for a task_id. CX Codex +1 436installs gaia-architecture-comparison gaia-architecture-comparison — a skill for Claude Code, Codex, Cursor, Copilot, and Gemini CLI that runs a side-by-side breakdown of the ruflo GAIA harness against Princeton's HAL reference across nine dimensions. CX Codex +1 433installs nested-subagents nested-subagents spawns a tree of sub-agents where each child can spawn its own children. Useful when intermediate state would overflow a single agent's context. CX Codex +1 317installs cost-projection The cost-projection Claude Code skill projects future spend from recent session data. It estimates daily costs and shows when configured budget thresholds may be reached. CX Codex +1 249installs cost-health cost-health runs four cost checks at once and returns a single status: budget, burn acceleration, session outliers and days left before the budget is gone. CX Codex +1 249installs cost-counterfactual cost-counterfactual evaluates LLM routing by comparing actual session spend against hypothetical always-haiku, always-sonnet, and always-opus baselines. Useful for tracking over-escalation and ROI. CX Codex +1 249installs cost-diff The cost-diff Claude Code skill compares two JSON snapshots of spending. Use it to detect cost changes between a baseline and a pull request branch. CX Codex +1 248installs

Project sponsors

Companies that keep this analytics open