cost-report

namespace	aiwg
name	cost-report
platforms	["all"]
description	Generate a cost and token-spending report for the current or most recent workflow session

cost-report

You generate a cost and token-spending report for the current or most recent workflow session. You read accumulated token usage data from .aiwg/ralph/cost-tracking.json and present a breakdown by operation, model, and time period.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "how much did that cost" → report for most recent session
• "what did this iteration cost" → report scoped to current agent loop
• "token breakdown" → report with per-model detail
• "did we stay in budget" → report with budget threshold comparison

Trigger Patterns Reference

Pattern	Example	Action
Session cost	"cost report"	aiwg cost-report
Current loop cost	"how much has this session cost so far"	aiwg cost-report --session current
Named session	"cost for the greenfield run"	aiwg cost-report --session greenfield
Model breakdown	"show costs by model"	aiwg cost-report --by-model
Budget check	"are we over budget"	aiwg cost-report --budget <N>

Behavior

When triggered:

1. Determine scope:

   • Default: most recent completed session
   • --session current: running session (live data)
   • --session <name>: named session from history

2. Read cost tracking data:

   • Primary source: .aiwg/ralph/cost-tracking.json
   • Fallback: aggregate from .aiwg/ralph/sessions/*/metrics.json

3. Compute the report:

   • Total tokens (input + output)
   • Estimated cost using model pricing table
   • Breakdown by workflow step and model
   • Comparison to MetaGPT baseline (124 tokens/line, REF-013)

4. Run the command:

   # Default report (most recent session)
   aiwg cost-report
   
   # Current running session
   aiwg cost-report --session current
   
   # JSON output (for scripting)
   aiwg cost-report --json
   
   # Filter to specific model
   aiwg cost-report --model claude-sonnet-4-5
   
   # Budget threshold check
   aiwg cost-report --budget 5.00
   

Report Format

Standard Output

Cost Report — Session: sdlc-review-20260401-143022
Duration: 4m 12s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Token Usage
  Input tokens:   42,310
  Output tokens:  18,940
  Total tokens:   61,250

Estimated Cost
  claude-sonnet-4-5:  $0.18  (61,250 tokens)
  Total:              $0.18

Efficiency vs Benchmark
  Tokens/line:    112  (MetaGPT baseline: 124)  [green]
  vs baseline:    -9.7%  (better than benchmark)

Steps
  architecture-designer  →  18,200 tokens  $0.07
  security-architect     →  14,600 tokens  $0.06
  test-architect         →  13,100 tokens  $0.05
  technical-writer       →  15,350 tokens  $0.06 (incl. synthesis)

Budget Check Output

Budget: $5.00
Used:   $0.18  (3.6% of budget)
Status: Within budget

Data Sources

Source	Contents
.aiwg/ralph/cost-tracking.json	Aggregated session costs
.aiwg/ralph/sessions/*/metrics.json	Per-session detailed metrics
src/metrics/token-counter.ts	Token estimation logic (4 chars/token)

Examples

Example 1: Quick session report

User: "How much did that cost?"

Extraction: Cost report for most recent session

Action:

aiwg cost-report

Response: Session report with token totals, estimated cost, and efficiency rating against the MetaGPT baseline.

Example 2: Budget check mid-session

User: "Are we over the $2 budget for this run?"

Extraction: Budget comparison for current session

Action:

aiwg cost-report --session current --budget 2.00

Response:

Budget: $2.00
Used:   $0.43  (21.5% of budget)
Status: Within budget
Projected total (at current rate): $0.71

Example 3: Model breakdown

User: "Show me costs broken down by model"

Action:

aiwg cost-report --by-model

Response:

Cost by Model
  claude-sonnet-4-5:   $0.12  (38,400 tokens)
  claude-haiku-3-5:    $0.02   (6,200 tokens)
  Total:               $0.14  (44,600 tokens)

Clarification Prompts

If the session is ambiguous:

• "Should I report on the current session or the most recent completed session?"

References

• @$AIWG_ROOT/src/cli/handlers/subcommands.ts — Cost report handler
• @$AIWG_ROOT/src/metrics/token-counter.ts — Token counting and MetaGPT baseline (REF-013)
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference