Cost Report

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

Behavior

When triggered:

Fleet mode

For --fleet, run the native CLI handler. It reads ~/.config/aiwg/fleet.yaml, resolves each key_ref only from ~/.config/aiwg/keys/ or AIWG_OPENROUTER_KEY_*, and reports bot | machine | spend MTD | cap | % used | top-3 expensive sessions.

Fleet manifests contain references only. Never read a credential from a project manifest, print a credential, or copy one into an artifact. AIWG observes and correlates spend; OpenRouter enforces all limits and caps. Session/model correlation is optional and uses locally recorded bot=, session=, and generation_id= tags in .aiwg/activity.log.

bashCopy code
aiwg cost-report --fleet
aiwg cost-report --fleet --json
aiwg cost-report --key <key_ref> --monthly-cap 10

For setup and security details, see @$AIWG_ROOT/docs/guides/openrouter-fleet-costs.md.

Session mode

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:

   bashCopy code
   # 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-5
   
   # Budget threshold check
   aiwg cost-report --budget 5.00
   

Report Format

Standard Output

Copy code
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

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

Data Sources

Examples

Example 1: Quick session report

User: "How much did that cost?"

Extraction: Cost report for most recent session

Action:

bashCopy code
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:

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

Response:

Copy code
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:

bashCopy code
aiwg cost-report --by-model

Response:

Copy code
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
• @$AIWG_ROOT/docs/guides/openrouter-fleet-costs.md — OpenRouter fleet configuration and security contract