How do I install the Cost Session skill?

Run npx skillmds@latest add ruvnet/cost-session in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Cost Session safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Cost Session?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Cost Session free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Cost Session?

ruvnet (@ruvnet) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Cost Session by ruvnet — Agent Skill

Name: Cost Session
Rating: 4.5 (4 reviews)
Author: ruvnet

Cost Session

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.

ruvnet 6675a3c 3.2 KB Updated Sep 9, 2026

File contents

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.

Resolve session jsonl: --session-id <id> (scans ~/.claude/projects/*/) or --latest (default; picks most-recently-modified jsonl).
Parse all assistant messages with usage blocks.
Cost each message via shared PRICING (_prices.mjs).
Sort descending by cost_usd, surface top-N (default 20).
Compute p50/p90/p99 of message costs for in-session percentile context.
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.

Source: ruvnet/ruflo → plugins/ruflo-cost-tracker/skills/cost-session/SKILL.md

---name: cost-sessiondescription: 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.--- 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. --- **Source:** [`ruvnet/ruflo`](https://github.com/ruvnet/ruflo) → `plugins/ruflo-cost-tracker/skills/cost-session/SKILL.md`

Frequently asked questions