Skip to main content
skill CX Codex

cost · sethgammon — Claude Code skill for session cost reports

See token usage and costs for sessions, campaigns, and time periods. Use it to check where spend is going and how quickly it is rising.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What cost does

Run /cost to inspect the current session, spending today or this week, lifetime totals, or a named campaign. Reports include token and message counts, costs, model breakdowns, and burn rate. The skill reads session data with scripts/session-tokens.js and also checks telemetry files and scripts/pricing.json.

If the script cannot run, cost data comes from session-costs.jsonl and is marked as estimated. When pricing.json cannot be read, the script uses its built-in pricing. The skill only reads data; it does not modify project files.

What it helps with

  • check the cost and burn rate of the current session
  • total spend for a day or week
  • compare costs across campaigns
  • inspect token usage by model

Example prompts for the agent

  • Show the current session cost with /cost.
  • Report this week's spend using /cost week.
  • Show the spend for campaign release with /cost campaign release.

How to install cost

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill cost -a claude-code

3Manually: put the files in place

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

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

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

Questions about cost

How do I install cost in Claude Code?

Add the marketplace with /plugin marketplace add SethGammon/Citadel, then install the plugin with /plugin install citadel@citadel-local.

What does cost do?

It reads session and telemetry data to report token usage and spending. You can view the current session, a time period, or a campaign.

Where does cost get its spending data?

It runs scripts/session-tokens.js and reads telemetry files plus scripts/pricing.json. If the script is unavailable, it uses session-costs.jsonl and labels the figures as estimates.

Source text

SKILL.md · MIT
---
name: cost
license: MIT
description: >-
  Deep cost exploration and transparency. Shows real token usage, session costs,
  campaign spend, burn rates, and model breakdown. Reads Claude Code's native
  session data for exact numbers. Complements /dashboard with focused cost views.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - cost
  - costs
  - cost breakdown
  - campaign cost
  - token usage
  - burn rate
  - model breakdown
last-updated: 2026-03-30
---

# /cost -- Session & Campaign Cost Explorer

## When to Use

- `/cost` -- current session cost and burn rate
- `/cost today` -- today's total spend
- `/cost week` -- this week's spend
- `/cost campaign {slug}` -- total spend for a specific campaign
- `/cost all` -- lifetime cost summary
- When /do routes "how much", "what's the cost", "spending", "tokens", "burn rate"

## Inputs

Optional arguments parsed from user message:
- `today` -- filter to today's sessions
- `week` -- filter to last 7 days
- `campaign {slug}` -- filter to a specific campaign
- `all` -- show all-time data
- No argument -- show current session

## Protocol

### Step 1: READ REAL DATA

Run the session-tokens.js script to get real token data:

```bash
node scripts/session-tokens.js              # current/latest session
node scripts/session-tokens.js --today      # today's sessions
node scripts/session-tokens.js --all        # all sessions (use for week/all/campaign)
```

Also read:
- `.planning/telemetry/cost-tracker-state.json` for live burn rate
- `.planning/telemetry/session-costs.jsonl` for campaign attribution
- `scripts/pricing.json` to show which pricing is being used

If `session-tokens.js` is not available or fails, fall back to session-costs.jsonl
data and clearly mark output as "(estimated)".

### Step 2: RENDER BASED ON SCOPE

**Current session (`/cost` with no args):**

```
=== Session Cost Report ===
Session: {sessionId (first 8 chars)}
Started: {relative time} ({absolute time})
Duration: {minutes} min

Tokens:
  Input:          {N} tokens
  Output:         {N} tokens
  Cache creation: {N} tokens
  Cache read:     {N} tokens
  Total:          {N} tokens

Cost: ${total}
Burn rate: ${rate}/min
Messages: {N} ({N} main + {N} across {N} subagents)

Model breakdown:
  claude-opus-4-6:         {N} messages (${cost}, {pct}% of spend)
  claude-haiku-4-5:        {N} messages (${cost}, {pct}% of spend)

Cache efficiency: {pct}% of input tokens served from cache
  (Higher = more cost-efficient. Cache reads cost 10x less than fresh input.)

Pricing source: scripts/pricing.json (version {version})
```

**Today / Week / All (`/cost today`, `/cost week`, `/cost all`):**

```
=== Cost Report: {Today / This Week / All Time} ===

Summary:
  Sessions: {N}
  Total cost: ${total}
  Subagents spawned: {N}
  Total messages: {N}

Top 5 sessions by cost:
  ${cost}  {duration}min  {agents} agents  {msgs} msgs  {date}
  ${cost}  {duration}min  {agents} agents  {msgs} msgs  {date}
  ...

By campaign (from session-costs.jsonl):
  {slug}: ${cost} across {N} sessions
  _unattached: ${cost} across {N} sessions

Average session: ${avg_cost} | ${avg_rate}/min | {avg_duration} min

For historical charts and billing-window views: npx ccusage
```

**Campaign (`/cost campaign {slug}`):**

```
=== Campaign Cost: {slug} ===

Total: ${cost} across {N} sessions ({N} agents, {N} min)
Average session: ${avg}

Sessions:
  {date}: ${cost} ({duration} min, {agents} agents, {msgs} msgs)
  {date}: ${cost} ({duration} min, {agents} agents, {msgs} msgs)
  ...
```

### Step 3: ADD CONTEXT

After the cost data, add one of these contextual lines based on the numbers:

- If burn rate > $2/min: "Burn rate is high. Consider whether subagent-heavy work
  could be restructured into smaller focused sessions."
- If cache hit rate < 50%: "Low cache hit rate. Long conversations with many tool
  results tend to have lower cache efficiency."
- If no real data available: "Cost data is estimated. Real token data becomes
  available when sessions complete and Claude Code writes session JSONL files."
- Otherwise: no extra context needed.

### Step 4: FRINGE CASES

**If scripts/session-tokens.js does not exist:**
Fall back to session-costs.jsonl data. Show estimated costs with "(est)" marker.

**If no session data exists:**
```
No session data found. Cost tracking requires Claude Code session files
at ~/.claude/projects/. These are created automatically by Claude Code.
```

**If pricing.json is missing or unreadable:**
Use hardcoded pricing in session-tokens.js. Note: "Using built-in pricing (pricing.json not found)."

**If user asks about Pro/Max subscription costs:**
```
Note: Pro/Max subscribers pay a flat monthly fee, not per-token.
The token counts shown here represent your usage volume, not billing.
For rate limit awareness, token throughput matters more than dollar cost.
```

## Fringe Cases

- **Telemetry directory missing**: `.planning/telemetry/` does not exist — output: "No telemetry data found. Run any skill first to generate session data, then re-run /cost."
- **Malformed telemetry JSON**: a `session-*.json` file fails to parse — output: "Telemetry file is corrupted. Delete `.planning/telemetry/session-*.json` and re-run the skill that generated it." Skip the bad file and continue with the rest.
- **MCP cost API returns no data**: Claude Code is not tracking this session — output: "Session cost unavailable from MCP. Check that Claude Code is running with cost tracking enabled. Showing telemetry file data only." Fall back to session-costs.jsonl.
- **All session files are from a different project**: project paths in the files do not match the current working directory — warn: "Session files found belong to a different project. You may be in the wrong directory." List the project paths found in the session files.

## Contextual Gates

**Disclosure:** "Reading telemetry and session data. No files modified."
**Reversibility:** green — read-only; no files modified
**Trust gates:**
- Any: full cost report, session data, campaign attribution.

## Quality Gates

- Always show real data when available, estimated when not
- Always label data source: (real) vs (est)
- Never claim specific dollar savings from Citadel -- show raw hook facts instead
- Suggest ccusage for features we don't replicate (charts, billing windows)
- Round costs to 2 decimal places, tokens to nearest K/M
- Total output must fit on one screen for current-session view

## Exit Protocol

/cost does not produce a HANDOFF block. It is a read-only cost exploration tool.
After displaying the report, wait for the next user command.

© SethGammon · MIT · SethGammon/Citadel

Similar skills

SKILL.md skills catalog →

cost by other authors comes first.

cost getagentseal A skill for Claude Code and Codex shows today’s AI coding spend. It breaks costs down by model and project, then flags unusual usage. CX Codex +1 ★ 11,881repo stars convex-cost convex convex-cost analyzes Convex deployment spend, ranks functions driving read costs, and projects growth curves. Points out the cheapest code fix for each bottleneck. CX Codex +1 43,800installs google-cloud-waf-cost-optimization official google google-cloud-waf-cost-optimization — a skill for Claude Code, Gemini CLI, and Codex that audits Google Cloud workloads against the Well-Architected Framework Cost Optimization pillar. CX Codex +1 14,266installs cost-optimization Seth Hobson The cost-optimization skill reviews AWS, Azure, GCP, and OCI spending, then guides rightsizing, tagging, pricing choices, and budget controls. CX Codex +1 11,506installs aws-billing-and-cost-management aws aws-billing-and-cost-management analyzes AWS spending, discovers savings opportunities, and sets up budgets. Helps evaluate Savings Plans, detect cost anomalies, and right-size infrastructure. CX Codex +1 10,300installs az-cost-optimize official github az-cost-optimize reviews Azure resources and IaC, finds cost-saving changes, and creates GitHub issues after approval. Use it when reviewing an Azure project's spend. CX Codex +1 8,700installs cost-aware-llm-pipeline affaan-m cost-aware-llm-pipeline is a Claude Code skill that routes simple tasks to cheaper models, tracks API spend, and caches prompts while preserving quality on hard requests. CX Codex +1 6,400installs

From the same set55

The whole set →
test-gen test-gen is a Claude Code skill that generates and runs unit tests matching a project's existing framework, covering happy paths, edge cases, and failures. CX Codex +1 ★ 937repo stars design This skill builds a design manifest from a project’s styles or your preferences. A post-edit hook flags mismatches in edited files. CX Codex +1 ★ 937repo stars live-preview live-preview takes screenshots of components during construction, not after completion. Catches layout regressions and invisible blocks before they propagate. CX Codex +1 ★ 937repo stars architect architect turns a PRD or task outline into an implementation plan with file trees, data models, and phased build steps. CX Codex +1 ★ 937repo stars merge-review merge-review scans the fleet worktree merge queue, flags files touched by more than one branch, and suggests a merge order before anything lands in main. CX Codex +1 ★ 937repo stars deploy-steward deploy-steward serializes PR merges into main, tracks CI gates, triggers deploys, and files repair tasks when checks fail. CX Codex +1 ★ 937repo stars prd prd turns an app idea into a structured product requirements document, asking about decisions that affect its shape. Use it before handing a project plan to Archon. CX Codex +1 ★ 937repo stars organize organize — a skill that audits and corrects project structure: checks file placement, moves files to match conventions, updates imports. Leaves code inside files untouched. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open