/cost-report - Token Cost Attribution Report
Display token usage and cost attribution by task, track, and session using the Ralph Wiggum TokenEconomicsService (ADR-111).
Usage
# Show today's cost summary
/cost-report
# Show costs for a specific date range
/cost-report --from 2026-02-10 --to 2026-02-16
# Filter by track
/cost-report --track H
# Filter by task
/cost-report --task H.8.4.7
# Show budget utilization
/cost-report --budgets
# Show per-model cost breakdown
/cost-report --models
# Export as JSON
/cost-report --json
# Show efficiency metrics
/cost-report --efficiency
System Prompt
When /cost-report is invoked, execute the following:
1. Load Token Economics Data
import sys, json, os
from pathlib import Path
from datetime import datetime, date, timedelta
# Add coditect-core to path
CORE_DIR = Path(os.environ.get('CODITECT_CORE', os.path.expanduser('~/.coditect')))
sys.path.insert(0, str(CORE_DIR))
sys.path.insert(0, str(CORE_DIR / 'scripts' / 'core'))
try:
from ralph_wiggum.token_economics import TokenEconomicsService, PricingService
HAS_SERVICE = True
except ImportError:
HAS_SERVICE = False
# Data directory
DATA_DIR = Path.home() / "PROJECTS" / ".coditect-data" / "token-economics"
RECORDS_DIR = DATA_DIR / "records"
TOTALS_FILE = DATA_DIR / "running_totals.json"
BUDGETS_FILE = DATA_DIR / "budgets.json"
2. Display Cost Summary
Format output as:
╔══════════════════════════════════════════════════════════════╗
║ COST REPORT (ADR-111) ║
║ 2026-02-16 ║
╠══════════════════════════════════════════════════════════════╣
║ Period: Today (2026-02-16) ║
║ Total Tokens: 245,000 input / 38,000 output ║
║ Total Cost: $4.35 ║
╠══════════════════════════════════════════════════════════════╣
║ BY MODEL ║
║ ───────── ║
║ claude-opus-4-6 180K in / 28K out $3.80 ║
║ claude-sonnet-4-5 65K in / 10K out $0.55 ║
╠══════════════════════════════════════════════════════════════╣
║ BY TRACK ║
║ ───────── ║
║ H (Framework) 185K tokens $3.20 74% ║
║ J (Memory) 60K tokens $1.15 26% ║
╠══════════════════════════════════════════════════════════════╣
║ BY TASK (Top 5) ║
║ ────────── ║
║ H.8.4.7 /cost-report creation 45K $0.85 ║
║ H.8.4.5 /token-status enhance 38K $0.72 ║
║ H.8.1.9 checkpoint hooks 32K $0.60 ║
║ J.4.2.1 semantic search 28K $0.53 ║
║ H.8.4.6 budget hooks 22K $0.42 ║
╚══════════════════════════════════════════════════════════════╝
3. Handle Options
--budgets
Show budget utilization:
╔══════════════════════════════════════════════════════════════╗
║ BUDGET UTILIZATION ║
║ ───────────────── ║
║ Organization: $45.00 / $100.00 (45%) [████████░░░░░░░░░░] ║
║ Project PILOT: $32.00 / $50.00 (64%) [████████████░░░░░░] ║
║ Task H.8: $12.50 / $20.00 (63%) [████████████░░░░░░] ║
╚══════════════════════════════════════════════════════════════╝
--models
Per-model breakdown with pricing:
╔══════════════════════════════════════════════════════════════╗
║ MODEL PRICING ║
║ ───────────── ║
║ Model Input $/M Output $/M Usage Today ║
║ claude-opus-4-6 $15.00 $75.00 180K / 28K ║
║ claude-sonnet-4-5 $3.00 $15.00 65K / 10K ║
║ claude-haiku-4-5 $0.80 $4.00 0K / 0K ║
╚══════════════════════════════════════════════════════════════╝
--efficiency
Show efficiency metrics:
╔══════════════════════════════════════════════════════════════╗
║ EFFICIENCY METRICS ║
║ ────────────────── ║
║ Cost per Task Completed: $0.87 ║
║ Cost per File Modified: $0.43 ║
║ Tokens per Tool Call: ~1,200 ║
║ Output/Input Ratio: 15.5% ║
║ Cache Hit Rate: 62% ║
╚══════════════════════════════════════════════════════════════╝
--from DATE --to DATE
Filter records by date range. Dates in YYYY-MM-DD format.
--track LETTER
Filter to a specific track (e.g., H, J, A).
--task ID
Filter to a specific task ID (e.g., H.8.4.7).
--json
Output as JSON for programmatic consumption.
4. Data Sources
The command reads from TokenEconomicsService storage:
| File | Purpose |
|---|---|
~/PROJECTS/.coditect-data/token-economics/running_totals.json | Cumulative totals |
~/PROJECTS/.coditect-data/token-economics/budgets.json | Budget definitions |
~/PROJECTS/.coditect-data/token-economics/records/{date}.jsonl | Daily consumption records |
5. Script Implementation
python3 "$CODITECT_CORE/scripts/core/cost-report-command.py" [OPTIONS]
Examples
Daily Summary
> /cost-report
COST REPORT — 2026-02-16
Total: 245,000 tokens ($4.35)
By Model:
opus-4-6: 180K in / 28K out ($3.80)
sonnet-4-5: 65K in / 10K out ($0.55)
By Track:
H Framework: 185K ($3.20, 74%)
J Memory: 60K ($1.15, 26%)
Top Tasks:
H.8.4.7 45K $0.85
H.8.4.5 38K $0.72
Budget Check
> /cost-report --budgets
Organization: $45.00 / $100.00 (45%) ✓
Project PILOT: $32.00 / $50.00 (64%) ⚠
Task H.8: $12.50 / $20.00 (63%) ⚠
Week Summary
> /cost-report --from 2026-02-10 --to 2026-02-16
COST REPORT — 2026-02-10 to 2026-02-16
Total: 1,245,000 tokens ($22.85)
Daily Average: $3.26
Peak Day: 2026-02-14 ($5.80)
Files
| File | Purpose |
|---|---|
scripts/core/cost-report-command.py | CLI implementation |
scripts/core/ralph_wiggum/token_economics.py | TokenEconomicsService |
~/PROJECTS/.coditect-data/token-economics/ | Data directory |
Related
- ADR-111: Token Economics Instrumentation
- /token-status - Context window token usage
- /checkpoint - Agent checkpoint management
- /health-status - Agent health monitoring
- TokenEconomicsService
Track: H (Framework) Task: H.8.4.7 Version: 1.0.0 Created: 2026-02-16