Skip to main content
skill CX Codex

telemetry · sethgammon — Claude Code and Codex skill: track session costs and hook activity

Skill for Claude Code and Codex that displays session cost, spending today and all-time totals, hook activity, trust level, and a directory of telemetry commands.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What telemetry does

The skill gathers API call costs in real time: exact token burn from session-tokens.js, cost per minute, cache savings. Displays history across sessions and campaigns, recent hook fires with execution time, current trust level (novice, familiar, trusted). All data lives in .planning/telemetry/*.jsonl — logs of session costs, hook timings, and errors.

Running /telemetry shows the full dashboard with stats and command menu. Flags show costs only (--costs), hook activity only (--hooks), or verify record integrity (--verify). Controls settings in harness.json: disables cost alerts (/telemetry off), sets alert thresholds (/telemetry --threshold 10 triggers alerts every $10).

Needs at least basic log files in .planning/telemetry/ — without them, displays zeros or skips sections. Runs on Claude Code and Codex; for other platforms, the skill installs into platform-specific directories (~/.claude/, .agents/, .cursor/, etc.).

What it helps with

  • see how much a session or day of work cost
  • track when and why automated hooks fired
  • check trust level and completed campaign statistics
  • turn off cost alerts or adjust notification thresholds
  • verify telemetry logs for tampering or corruption

Example prompts for the agent

  • Show me telemetry for this session and today's spending.
  • What trust level am I at? How many sessions have I completed?
  • Turn off the cost alerts but keep hook safety checks enabled.

How to install telemetry

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill telemetry -a claude-code

3Manually: put the files in place

~/.claude/skills/telemetry/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/telemetry/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about telemetry

How do I install telemetry in Claude Code?

Run these in order: /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local, then npx skills add SethGammon/Citadel --skill telemetry -a claude-code. The skill is located at ~/.claude/skills/telemetry/SKILL.md.

What does telemetry do?

It displays session cost, spending for today and all-time, shows recent hook executions, displays trust level, and lists all available telemetry commands. You can disable alerts and adjust cost thresholds for notifications.

What data does it need to work?

The skill reads logs from .planning/telemetry/ (session-costs.jsonl, hook-timing.jsonl, hook-errors.jsonl) and config from harness.json. If files are missing, it shows zeros. Exact costs come from node scripts/session-tokens.js --today.

Source text

SKILL.md · MIT
---
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 `telemetry.sessionSummary = "off"` and `telemetry.costAlerts = false` in harness.json. Output: "Telemetry summary disabled. Hook safety checks remain active." Safety hooks (protect-files, circuit-breaker, external-action-gate) are never disabled.

**`/telemetry on`:** Set `telemetry.sessionSummary = "auto"` and `telemetry.costAlerts = true`. Output: "Telemetry re-enabled."

**`/telemetry --threshold N`:** Validate N is positive. Generate `[N, N*2, N*5, N*10, N*20, N*50, N*100]` (capped at 500). Write to `harness.json` under `policy.costTracker.thresholds`.

**`/telemetry --verify`:** Run the project verifier:

```
node scripts/verify-telemetry-integrity.js
```

The verifier scans `.planning/telemetry/*.jsonl` and `.planning/artifacts/*.jsonl`. Display verified, signed, legacy, tampered, invalid, and signature-warning counts. Use `--strict-legacy` only when old unsigned records should fail the check.

Output format:
```
=== Telemetry Integrity ===

file.jsonl
  Total records:    N
  Verified (hash):  N
  Verified (signed): N
  Legacy (no hash): N
  TAMPERED:         N
  Invalid JSON:     N
  Signature warnings: N

Status: CLEAN or FAILED
```

If any tampered records: list each with `timestamp`, `event`, and both the stored and expected hash (first 16 chars each). Tampering can indicate log corruption, manual edits, or a bug — not necessarily malicious.

If only legacy records (no tampered): note "Legacy records were written before telemetry integrity hashing was added. New telemetry and artifact records are hashed automatically."

**`/telemetry --config`:** Show current settings with the `node -e "..."` command to change each — don't auto-apply.

### Step 4: ACCURACY BADGES

Always mark data source clearly:
- `[real]` — data from Claude Code's native session JSONL (exact)
- `(est)` — estimated from the fallback model ($1 base + $0.50/agent + $0.10/min)
- `(override)` — manually entered by the user

Never blend real and estimated in the same total without flagging it.

## What Telemetry Covers

**Covered:** session cost (real token data), duration/burn rate/message count, agent spawn count, hook timing and outcomes, campaign cost attribution, trust level.

**Not covered (by design):** per-tool-call cost, per-subagent cost isolation, real-time streaming token count.

**Safety hooks always on (cannot be disabled):** protect-files, external-action-gate, circuit-breaker, quality-gate.

## OTLP Export

The JSONL files under `.planning/telemetry/` stay canonical. For standard observability
stacks, `scripts/telemetry-otlp-export.js` translates new records into OTLP/HTTP JSON
metrics and POSTs them to a collector. Byte offsets per source file live in
`.planning/telemetry/otlp-export-state.json`, so repeat runs export only new records.

```bash
# Preview the OTLP payload without sending or advancing state
node scripts/telemetry-otlp-export.js --dry-run

# Export new records to a local collector (/v1/metrics appended when the url has no path)
node scripts/telemetry-otlp-export.js --endpoint http://localhost:4318
```

| Metric | Type | Source file |
|---|---|---|
| `citadel.session.cost.usd` | sum (delta), `session.id` / `cost.source` attributes | `session-costs.jsonl` |
| `citadel.session.tokens` | sum (delta), `token.type` attribute | `session-costs.jsonl` |
| `citadel.hook.duration.ms` | gauge, `hook.name` attribute | `hook-timing.jsonl` |
| `citadel.agent.runs` | sum (delta), `run.status` / `run.event` attributes | `agent-runs.jsonl` |

`--reset` clears the offsets for a full re-export. On a non-2xx response or network
error the exporter exits 1 without advancing state, so the next run retries the same
records. Data point timestamps come from the JSONL records, never the current clock.
Test with `node scripts/test-telemetry-otlp.js`.

**Local collector demo:** `examples/otel-collector/` contains a ready-made collector
config (OTLP HTTP receiver on 4318, debug exporter to stdout) and a README with the
two-command flow: `docker run` with the config mounted, then
`node scripts/telemetry-otlp-export.js --endpoint http://localhost:4318`. Without
Docker, `--dry-run` prints the exact OTLP payload instead.

## Quality Gates

- Never show raw JSONL to the user — always parse and format
- Cost totals must be labeled with their source (real / est / mixed)
- `/telemetry off` must NOT disable safety hooks — make this explicit in output
- Relative timestamps required — no raw ISO strings in output
- If all data sources are missing, show the empty-state version with setup hint

## Fringe Cases

- **`.planning/telemetry/` missing:** Show empty state with "Run `/do setup` to initialize telemetry."
- **`session-tokens.js` unavailable:** Fall back to session-costs.jsonl; mark `(est)`.
- **harness.json missing:** Show "(harness.json not found — defaults active)" and "→ Run /do setup to unlock cost tracking."
- **`telemetry.enabled: false`:** Show banner "Telemetry is disabled. Run `/telemetry on` to re-enable."
- **`--verify` with missing files:** Report "No telemetry or artifact JSONL files found." Not an error.
- **`--verify` when `scripts/verify-telemetry-integrity.js` is unavailable:** Report that the verifier is missing and show the raw file paths to inspect; do not claim hash verification ran.

## Contextual Gates

**Disclosure:** Read-only by default. `--threshold`, `off`, `on`, `--config` write `harness.json`.
**Reversibility:** amber — `harness.json` writes; undo with `git checkout .claude/harness.json`.
**Trust gates:** Any — no restrictions.

## Exit Protocol

/telemetry does not produce a HANDOFF block. It is a read-only observability
tool (except for `--threshold`, `off`, `on`, `--config` which write harness.json).
After displaying output, wait for the next user command.

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

telemetry by other authors comes first.

telemetry official OpenAI This skill adds and verifies macOS runtime telemetry with Logger. Use it to trace windows, sidebars, menus, and user actions during debugging. CX Codex GP ChatGPT +1 52installs telemetry Microsoft Sets whether the Power Apps Mobile Extension skills send usage telemetry: on, off or status. Useful when you want out of collection or a quick look at the current setting. CX Codex +1 ★ 1,167repo stars telemetry Microsoft telemetry is a Claude Code skill that toggles power-automate telemetry or reports its setting. It responds to requests to change the setting or inspect it. CX Codex +1 ★ 1,167repo stars claude-telemetry-hooks Fatih C. Akyon claude-telemetry-hooks — a Claude Code plugin that collects agent metrics — requests, rejections, session duration — and displays them in a single dashboard. Activates automatically after install. CX Codex ★ 1,216repo stars cx-telemetry-querying coralogix cx-telemetry-querying — a Claude Code skill that picks the right telemetry pillar for a question: logs, metrics, traces, or RUM. It loads the matching reference files before any query is written. CX Codex +1 6,300installs otel-component-telemetry ollygarden otel-component-telemetry scans one OpenTelemetry component at pinned versions and records the spans, metrics and logs it emits as change-point files. CX Codex +1 ★ 126repo stars cost-export ruvnet cost-export exports cost telemetry into Prometheus textfile or webhook JSON formats for external dashboards like Grafana or Datadog. CX Codex +1 681installs doca-telemetry NVIDIA Skill for reading DOCA hardware counters from BlueField DPU or ConnectX NIC via doca_telemetry_pcc, doca_telemetry_dpa, doca_telemetry_diag and other per-domain libraries. CX Codex +1 ★ 4,106repo stars doca-telemetry-utils NVIDIA Runs doca_telemetry_utils on a host with DOCA to track where telemetry metrics disappear between exporter and collector. CX Codex +1 ★ 4,106repo stars

From the same set55

The whole set →
pr-watch pr-watch monitors pull request CI status in the terminal, inspects failure logs, applies code fixes, and prompts to merge. CX Codex +1 ★ 937repo stars ascii-diagram The ascii-diagram skill plans and renders aligned text diagrams with boxes and arrows. Use it when a diagram needs to live in Markdown, a code comment, or plain text. CX Codex +1 ★ 937repo stars triage triage — a skill for investigating GitHub issues and reviewing PRs. Reads open issues, classifies them, searches the codebase for root cause, proposes fixes with file:line references, and optionally implements them. CX Codex +1 ★ 937repo stars watch watch monitors working directory changes and source marker comments to trigger skills or log batch tasks automatically. CX Codex +1 ★ 937repo stars experiment experiment runs scalar-metric optimization loops in isolated worktrees, checking each candidate against a locked baseline before it's kept. CX Codex +1 ★ 937repo stars research research investigates technical questions, cross-references documentation, and saves structured Markdown briefs with confidence ratings. CX Codex +1 ★ 937repo stars learn learn turns completed campaigns or evolve cycles into structured project wiki entries. Use it to carry decisions and recurring patterns into future sessions. CX Codex +1 ★ 937repo stars dashboard dashboard is a Claude Code skill that shows harness state, including campaigns, agent sessions, telemetry, and queues. Run it with /dashboard, /do status, or a request to show activity. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open