cost-history
You show cost trends across multiple workflow sessions. You read historical cost records from .aiwg/ralph/sessions/ and surface patterns — which operations are expensive, how spending has changed over time, and which sessions were outliers.
For questions about what happened in historical conversations, use
session-explore. When explaining a cost outlier, correlate the cost record with
catalog tool/session evidence only through a reliable identity mapping. Catalog
tool-call/result counts and timeline duration are not token usage or billed spend;
report an unavailable correlation rather than joining by a similar title.
Triggers
Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):
- "what have I spent overall" → full history summary
- "are costs going up or down" → trend analysis
- "most expensive sessions" → sorted history by cost
- "cost this week" / "cost this month" → time-windowed history
Trigger Patterns Reference
| Pattern | Example | Action |
|---|---|---|
| Full history | "show cost history" | aiwg cost-history |
| Recent sessions | "last 5 sessions" | aiwg cost-history --last 5 |
| Time window | "costs this week" | aiwg cost-history --since 7d |
| Trend summary | "are my costs trending up" | aiwg cost-history --trend |
| Sorted by cost | "most expensive sessions" | aiwg cost-history --sort cost |
Behavior
When triggered:
-
Determine scope:
- Default: all recorded sessions, newest first
--last N: most recent N sessions--since <duration>: sessions within the time window (e.g.,7d,30d,2026-03-01)
-
Read session records:
.aiwg/ralph/sessions/*/metrics.json— per-session cost records.aiwg/ralph/cost-tracking.json— aggregated history index
-
Compute trend data:
- Session-over-session delta
- Rolling 7-session average
- Outlier detection (sessions > 2x average)
-
Run the command:
bash# All sessions, newest first aiwg cost-history # Most recent 10 sessions aiwg cost-history --last 10 # Sessions in the past 30 days aiwg cost-history --since 30d # Trend analysis aiwg cost-history --trend # Sorted by cost descending aiwg cost-history --sort cost # JSON output aiwg cost-history --json
Report Format
Standard History Output
Cost History (12 sessions) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Date Session Tokens Cost Status ────────── ────────────────────────── ──────── ────── ────── 2026-04-01 sdlc-review-143022 61,250 $0.18 green 2026-03-31 greenfield-092211 94,800 $0.28 green 2026-03-30 security-review-174503 118,400 $0.36 yellow 2026-03-28 api-development-110022 52,100 $0.15 green 2026-03-26 full-stack-iteration-3 201,700 $0.61 red *outlier ... Totals (12 sessions) Total tokens: 842,100 Total cost: $2.54 Avg/session: $0.21 7-session rolling average: $0.23 Trend: stable (±8% over last 7 sessions)
Trend Output (--trend)
Cost Trend — Last 7 Sessions Session 6 (oldest): $0.28 Session 5: $0.22 Session 4: $0.36 Session 3: $0.15 Session 2: $0.61 ← outlier (full-stack-iteration-3) Session 1: $0.18 Current avg: $0.23 Direction: stable Outliers: 1 (full-stack-iteration-3 — 2.6x average)
Efficiency Thresholds
Sessions are color-coded by tokens/line ratio against the MetaGPT 124 tokens/line benchmark (REF-013):
| Status | Tokens/Line | Meaning |
|---|---|---|
| green | ≤ 124 | At or below MetaGPT benchmark |
| yellow | 125–150 | Above benchmark, acceptable |
| red | > 150 | Significantly above benchmark — review recommended |
Examples
Example 1: Quick history overview
User: "Show cost history"
Action:
bashaiwg cost-history
Response: Full session history table with totals, rolling average, and trend direction.
Example 2: Recent session costs
User: "What did the last 3 sessions cost?"
Extraction: --last 3
Action:
bashaiwg cost-history --last 3
Response:
Cost History (last 3 sessions) Date Session Tokens Cost ────────── ─────────────────────── ─────── ──── 2026-04-01 sdlc-review-143022 61,250 $0.18 2026-03-31 greenfield-092211 94,800 $0.28 2026-03-30 security-review-174503 118,400 $0.36 Total: $0.82 over 3 sessions (avg: $0.27)
Example 3: Identifying expensive outliers
User: "Which sessions were most expensive?"
Action:
bashaiwg cost-history --sort cost
Response: History table sorted by cost descending, with outlier flag on sessions more than 2x the rolling average.
Clarification Prompts
If a time window is ambiguous:
- "Should I show all-time history or a specific window? (e.g., last 7 days, last 30 days)"
References
- @$AIWG_ROOT/src/cli/handlers/subcommands.ts — Cost history handler
- @$AIWG_ROOT/src/metrics/token-counter.ts — Token counting and MetaGPT baseline (REF-013)
- @$AIWG_ROOT/docs/cli-reference.md — CLI reference
