Cost Session

DevOps & Security

cost-session

Cost Session is an Agent Skill for devops & security published in the ruvnet/ruflo repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/ruvnet/ruflo/blob/HEAD/plugins/ruflo-cost-tracker/skills/cost-session/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cost-session, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.