# Cost

Deep cost exploration and transparency.

- Repository: https://github.com/SethGammon/Citadel (927 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add SethGammon/Citadel --skill cost -g -a claude-code -y`
Codex: `npx skills add SethGammon/Citadel --skill cost -g -a codex -y`
Cursor: `npx skills add SethGammon/Citadel --skill cost -g -a cursor -y`
Gemini CLI: `npx skills add SethGammon/Citadel --skill cost -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add SethGammon/Citadel`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# /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)

The rest: https://github.com/SethGammon/Citadel/blob/HEAD/skills/cost/SKILL.md