Cost Session
FreeAnalyze per-message costs in flagged sessions.
Free · Opens the source repo
What Cost Session does
Cost Session is a specialized tool designed for developers and operators who need to understand the financial implications of their AI model interactions. When a session is flagged as an outlier by the cost-anomaly skill, Cost Session provides a detailed breakdown of which specific messages contributed to the increased cost. This is crucial for identifying whether the costs stemmed from output tokens, cache writes, or model escalations, allowing for targeted investigation and optimization.
The skill operates by parsing session logs and calculating the cost of each message based on a shared pricing model. It sorts these messages by cost, enabling users to quickly identify the most expensive interactions. Additionally, Cost Session computes the p50, p90, and p99 percentiles of message costs, providing context for evaluating whether a message is an outlier. This feature is particularly useful for operators who want to determine if a high-cost message is an anomaly worth further investigation.
Cost Session is not just about identifying high-cost messages; it also surfaces the underlying reasons for those costs. For example, if a message incurs a high cost due to a large number of cache writes, operators can question why so much context was cached for a relatively small input. This insight can lead to more efficient usage of AI resources and better cost management.
This skill is targeted at AI operators, developers, and engineers who are responsible for monitoring and optimizing the cost of AI interactions. By integrating Cost Session into their workflow, users can gain a clearer understanding of their session costs and make informed decisions about resource allocation and model usage.
When to use it
Use this tool when a session has been flagged as an outlier and you need to analyze the cost breakdown of individual messages.
When not to use it
This skill is not suitable for general cost analysis across all sessions; it is specifically for sessions flagged by cost-anomaly.
What you can build with it
Investigating a High-Cost Session
After a session is flagged as an outlier, use Cost Session to drill down into the specific messages that drove up costs.
Optimizing AI Resource Usage
By identifying expensive messages, operators can adjust their prompts or model settings to reduce unnecessary costs.
Understanding Cache Costs
Gain insights into how cache writes contribute to session costs, allowing for better management of ephemeral resources.
How to install Cost Session
View source1. Install with the skills CLI
npx skills add ruvnet/ruflo/cost-session --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by ruvnetWhen 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
usageblocks. - 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-idnot found in any project's jsonls → exit 2 with error.--topmust be a positive integer → exit 2.
Frequently asked questions about Cost Session
Similar skills
Heap Snapshot Analysis
Investigate V8 heap snapshots for memory issues.
VS Code Performance Workflow
Automate performance investigations in VS Code.
Memory Leak Audit
Prevent memory leaks with effective coding patterns.
CPU Profile Analysis
Analyze V8 and Chrome performance profiles for optimization.
Chat Performance Testing
Benchmark and validate chat UI performance in VS Code.
Vercel React Best Practices
Optimize your React and Next.js applications for performance.