| name | telemetry-inspect |
| license | MIT |
| compatibility | Claude Code 2.1.220+. |
| author | OrchestKit |
| description | Inspects the OrchestKit telemetry pipeline for the current project — lists all known telemetry files with write counts, sizes, schema status, growth trend, and orphan detection. Use when verifying the observability pipeline is healthy, debugging a missing writer, or auditing which files have schema locks vs. which are drift-vulnerable. Read-only — never modifies telemetry files. |
| argument-hint | [--session <id>] [--json] |
| context | inherit |
| version | 1.0.0 |
| tags | ["telemetry","observability","diagnostics","metrics","session","health","schema","inspection"] |
| user-invocable | true |
| allowed-tools | ["Bash","Read","Grep","Glob"] |
| disallowed-tools | ["Write","Edit","MultiEdit","NotebookEdit"] |
| complexity | low |
| persuasion-type | collaborative |
| effort | low |
| model | haiku |
| metadata | {"category":"diagnostic"} |
/ork:telemetry-inspect
One-shot health check for OrchestKit's telemetry pipeline. Reports writer activity, file sizes, schema lock coverage, orphan files, and growth warnings. Use when verifying the pipeline is flowing correctly or debugging a missing writer.
When to use
- Before or after a risky hook refactor, to prove telemetry still writes as expected
- Weekly health check on a long-running project
- When
/ork:analytics output looks suspicious — inspect the underlying data first
- When adding a new telemetry file and wanting to confirm it's picked up
- Auditing which files are schema-locked vs. drift-vulnerable
What it checks
- Writer activity — for each registered telemetry file, recent write count (from mtime scan) and last-write delta
- File health — size (warn at 256 KB, critical at 1 MB), line count, mtime
- Schema lock status — which files have validators in
lib/telemetry-schemas.ts
- Orphan detection — files on disk under
.claude/{telemetry,logs,state,feedback}/ that aren't in the registry (possible stale writer or new file needing schema), plus inventory rows whose writer hook no longer exists in src/hooks/src/ (dead writer → orphan)
- Growth trend — bytes per hour since session start (fire alert if > 100 KB/hr)
- Coordination layer (M168) — live counts from
sessions.db (running sessions, held locks, pending worktree links, skill invocations) plus write throughput from coordination-metrics.jsonl
- Runtime fired-census — which hooks actually fired, from the per-invocation records
run-hook.mjs writes to ~/.claude/analytics/hook-timing.jsonl. Checks 1–4 answer "is the file being written?"; this answers "is the writer running at all?" — the upstream question. A hook can be wired and reachable (the closure gate proves that statically) and still never fire: #2886 shipped exactly that with 12 green tests.
Usage
/ork:telemetry-inspect
/ork:telemetry-inspect --session sess-abc123
/ork:telemetry-inspect --json
Default mode: terminal-friendly ASCII report. --json emits a structured result suitable for piping into another tool or uploading.
Output shape (ASCII mode)
Telemetry Health — 2026-07-09 11:50
────────────────────────────────────
Schema-locked files (7)
.claude/telemetry/pre-compact-decisions.jsonl ◆ 3 lines 1.1 KB ✓ healthy
.claude/telemetry/image-responses.jsonl ◆ 0 lines — ✗ no writes
.claude/logs/decisions.jsonl ◆ 0 lines — ✗ no writes
.claude/logs/subagent-spawns.jsonl ◆ 6 lines 3 KB ✓ healthy
.claude/state/edit-history.jsonl ◆ 94 lines 412 KB ⚠ rotate
.claude/state/ork-metrics-*.json ◆ (N/A) 2.1 KB ✓ healthy
.claude/logs/skill-channels.jsonl ◆ 12 lines 4 KB ✓ healthy
Unlocked telemetry files (14)
.claude/feedback/changelog-decisions.json ○ 4 KB ✗ no schema
.claude/feedback/learned-patterns.json ○ 8 KB ✗ no schema
(...14 more...)
Orphan files (1)
.claude/feedback/skill-usage.json — delisted, writer unwired since #959
Runtime fired-census (7d window)
ALIVE 59 IDLE 3 NEVER 83 UNOBSERVABLE 54
tree 8.75.0 · installed 8.73.0/8.74.0 <-- SKEW: NEVER is not a verdict
never-fired writers (the ones that matter here):
posttool/dirty-file-tracker [PostToolUse] 0 fires, ever
Summary
Pipeline health: GREEN (21/21 expected writers active)
Schema coverage: 7/21 (33%)
Largest file: edit-history.jsonl (412 KB)
Hotspot: edit-history.jsonl +40 KB/hr
