/telemetry

name: telemetry
license: MIT
description: >-
  Unified telemetry hub. Shows current session cost, today's spend, all-time
  totals, hook activity, trust level, and a directory of every telemetry command
  available. Also the control surface to toggle telemetry on/off and tune
  thresholds. Single entry point for anyone asking "what does this cost" or
  "what telemetry does Citadel have".
user-invocable: true
auto-trigger: false
trigger_keywords:
  - telemetry
  - what did this cost
  - session cost
  - how much did that cost
  - how much have I spent
  - what hooks fired
  - trust level
  - show me telemetry
  - spending
  - session stats
  - what telemetry
  - verify audit
  - audit integrity
  - check audit
  - tampered records
last-updated: 2026-04-09

/telemetry — Telemetry Hub

When to Use

• "What does Citadel track?" / "What telemetry does it have?"
• "What did this session cost?" / "How much have I spent?"
• "How do I turn off the cost alerts?" / "Can I disable telemetry?"
• "Show me hook activity" / "What hooks fired?"
• "What trust level am I at?"
• Directly: `/telemetry`

Routed here by `/do` for: "telemetry", "what did this cost", "session stats", "session cost", "how much did that cost", "what hooks fired", "trust level", "show me telemetry", "cost breakdown", "spending".

Commands

| Command | Behavior | |---|---| | `/telemetry` | Full hub — stats + command directory + settings | | `/telemetry --costs` | Cost section only: session, today, all-time, by campaign | | `/telemetry --hooks` | Hook activity only: last 20 fires with timing and outcomes | | `/telemetry --verify` | Telemetry and artifact integrity check: verify hashes/signatures, flag tampered records, report legacy records | | `/telemetry --config` | Show current telemetry settings from harness.json | | `/telemetry off` | Disable session summary, reduce hook verbosity | | `/telemetry on` | Re-enable all telemetry | | `/telemetry --threshold N` | Set cost alert threshold step (e.g. `--threshold 10` = alert every $10) |

Protocol

Step 1: COLLECT DATA

Read the following in parallel. All are optional — treat missing files as zero/empty.

**Live session cost:**

• Run `node scripts/session-tokens.js --today 2>/dev/null` — captures real token data
• If unavailable, read `.planning/telemetry/cost-tracker-state.json` for burn rate
• Real cost is always preferred over estimated. Mark clearly: `$X.XX` vs `$X.XX (est)`

**Historical costs:**

• Run `node scripts/session-tokens.js --all 2>/dev/null` for all-time real totals
• Read last 20 lines of `.planning/telemetry/session-costs.jsonl` for recent sessions
• For each entry: prefer `real_cost` > `override_cost` > `estimated_cost`

**Hook activity:**

• Read last 20 lines of `.planning/telemetry/hook-timing.jsonl`
• For each `event: "timing"` entry: extract `hook`, `duration_ms`, `timestamp`
• For each `event: "counter"` entry: extract `hook`, `metric`
• Check `.planning/telemetry/hook-errors.jsonl` (last 20 lines) for recent blocks

**Trust level:**

• Read `.claude/harness.json` (Citadel's shared config path for all runtimes, including Codex) → `trust` object
• Compute: novice (sessions < 5), familiar (5-19), trusted (20+ with 2+ campaigns)
• If `trust.override` set, use that

**Settings:**

• Read `.claude/harness.json` → `telemetry` object
• Show current values with defaults if missing

Step 2: RENDER HUB

Output this format. Omit a section only if the data source is completely unavailable.

=== Citadel Telemetry ===

CURRENT SESSION
  Cost:       $X.XX [real] | $X.XX (est)
  Duration:   N min | $X.XX/min burn rate
  Tokens:     NNK input | NK output | NK cache read | NK cache write
  Messages:   N
  Agents:     N spawned
  Hooks fired: N (today)

TODAY
  $X.XX across N sessions
  Most expensive: {slug or "unattached"} — $X.XX

ALL TIME
  $X.XX across N sessions, N campaigns
  Cache savings: ~$X.XX (cache reads vs full input price)

BY CAMPAIGN (recent 5)
  {slug}: $X.XX — N sessions
  _unattached: $X.XX — N sessions

HOOK ACTIVITY (last 10 fires)
  {relative time} | {hook} | {duration_ms}ms | {outcome}
  (no hook timing recorded yet)

TRUST LEVEL
  Level:    {novice | familiar | trusted}
  Sessions: N completed
  Campaigns: N completed
  (novice = 0-4 sessions | familiar = 5-19 | trusted = 20+ with 2+ campaigns)

TELEMETRY SETTINGS
  Enabled:          {true | false}
  Session summary:  {auto | always | off}   ← the [session] line at session end
  Cost alerts:      {on | off}  at thresholds: {list or "default ($5,$15,$30...)"}
  Hook timing:      {on | off}
  Audit log:        {on | off}
  — or, when harness.json is absent —
  (harness.json not found — defaults active)
  → Run /do setup to unlock cost tracking, configure thresholds, and register your install.

COMMAND DIRECTORY
  /telemetry                            This screen
  /telemetry --costs                    Cost breakdown only
  /telemetry --hooks                    Hook activity only
  /telemetry --verify                   Telemetry/artifact integrity check (hash/signature verification)
  /cost                                 Deep cost exploration by session/campaign/week
  /dashboard                            Full harness state (campaigns, fleet, all costs)

  node scripts/session-tokens.js --today   Today's sessions with exact token counts
  node scripts/session-tokens.js --all     All-time totals (real data, not estimates)

  cat .planning/telemetry/session-costs.jsonl   Raw session cost log
  cat .planning/telemetry/hook-timing.jsonl     Raw hook execution log
  cat .planning/telemetry/audit.jsonl           Raw tool call audit log

CONTROLS
  /telemetry off                        Disable session summary + reduce verbosity
  /telemetry on                         Re-enable
  /telemetry --threshold N              Alert every $N (writes to harness.json)
  /telemetry --config                   Edit settings interactively

Step 3: SUB-COMMAND HANDLING

**`/telemetry off`:** Set