/cost-report

namespace: aiwg
name: cost-report
platforms: [all]
description: Generate a cost report for an AIWG session or observe per-bot OpenRouter fleet spend

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>` | | Fleet spend | "show fleet spend" | `aiwg cost-report --fleet` |

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

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**:

   # 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

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