claude-session-introspect
Inspect Claude Code session JSONL files at ~/.claude/projects/ to extract real conversation telemetry: token counts (input/output/cache reads/cache writes), assistant turn counts, human prompt counts, tool-use counts, compaction boundaries, and the contents of compaction summaries. Use this skill when the user asks "how many tokens did this session use", "how many prompts have I sent", "show me the stats for this conversation", "what got compacted", "where are the compaction boundaries", "introspect the session", "do brain surgery on the JSONL", or wants any data point that lives inside the on-disk session log rather than the live context window. Inspired by Tal Raviv's "I wanted to know how compaction works" article.
swyxio · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add swyxio/skills --skill claude-session-introspect技能说明
name: claude-session-introspect
description: |
Inspect Claude Code session JSONL files at ~/.claude/projects/ to extract real conversation telemetry: token counts (input/output/cache reads/cache writes), assistant turn counts, human prompt counts, tool-use counts, compaction boundaries, and the contents of compaction summaries. Use this skill when the user asks "how many tokens did this session use", "how many prompts have I sent", "show me the stats for this conversation", "what got compacted", "where are the compaction boundaries", "introspect the session", "do brain surgery on the JSONL", or wants any data point that lives inside the on-disk session log rather than the live context window. Inspired by Tal Raviv's "I wanted to know how compaction works" article.
license: MIT
compatibility: |
Requires jq. Sessions live at ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl. The encoded-cwd is the absolute working directory with / replaced by - and a leading -. Each line is a JSON object with type, message, toolUseResult, etc.
metadata:
author: swyxio
version: "1.0"
last-updated: "2026-04-08"
primary-tools: jq, bash
Claude Session Introspect
Claude Code persists every conversation as a JSONL file on disk. This skill is the recipe for opening one and pulling out the numbers you actually want — token usage, prompt counts, compaction events, tool calls — without guessing.
Where sessions live
~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl
<encoded-cwd> is the absolute path of the project's working directory with / replaced by - and a leading -. Example: /Users/swyx/Work/foo → -Users-swyx-Work-foo.
Each line is one event. The interesting type values:
| type | what it is |
|---|---|
user | a real user message OR a tool result (distinguished by toolUseResult being non-null) |
assistant | an assistant turn (one model response). message.usage has the token counts. |
system | system messages (mostly compaction-related) |
file-history-snapshot | edited-file snapshots used for undo |
attachment | image/file attachments |
permission-mode | permission mode toggles |
Quick locate: find the current session
# 1. encode current working directory
ENC="-$(pwd | sed 's,/,-,g' | sed 's/^-//')"
# 2. list the project's session files, newest first
ls -t "$HOME/.claude/projects/$ENC/"
# 3. the most recent .jsonl is usually the live one
SESSION="$HOME/.claude/projects/$ENC/$(ls -t "$HOME/.claude/projects/$ENC/" | head -1)"
echo "$SESSION"
If you know the session UUID (Claude Code shows it, and image-cache paths embed it), you can grep all projects:
find ~/.claude/projects -name '<uuid>.jsonl'
The headline stats (one-shot)
The stats.sh script in this skill folder takes a session path and prints token totals, turn counts, prompt counts, tool-use counts, and any compaction events.
bash stats.sh "$SESSION"
If you don't have the script handy, here are the inline jq one-liners.
Token totals across the whole session
jq -s '
[.[] | select(.message.usage)] |
{
assistant_turns: length,
input_tokens: (map(.message.usage.input_tokens // 0) | add),
output_tokens: (map(.message.usage.output_tokens // 0) | add),
cache_read_tokens: (map(.message.usage.cache_read_input_tokens // 0) | add),
cache_create_tokens: (map(.message.usage.cache_creation_input_tokens // 0)| add)
}
' "$SESSION"
input_tokens is the FRESH (non-cached) input. cache_read_tokens is the dominant number on long sessions — it's how much was re-read from prompt cache. cache_create_tokens is what got newly written into the cache. Effective total tokens processed = input + cache_read + cache_create.
Counts by event type
jq -r '.type' "$SESSION" | sort | uniq -c
Real human prompts (excluding tool results and system reminders)
A type:"user" line is a human message only if toolUseResult is null. Even then, the content may be a system-injected reminder, not the human's words.
jq -r '
select(.type == "user" and .toolUseResult == null) |
(.message.content
| if type == "string" then .
else (map(select(.type == "text") | .text) | join("\n"))
end)
' "$SESSION" > /tmp/prompts.txt
# total non-empty user message blocks
grep -cv '^$' /tmp/prompts.txt
# distinct human messages = blocks not starting with <system-reminder> or <command-
awk '
BEGIN { n = 0; cur = "" }
/^$/ { if (cur != "" && cur !~ /^<system-reminder>/ && cur !~ /^<command-/) n++; cur=""; next }
{ if (cur=="") cur=$0 }
END { if (cur != "" && cur !~ /^<system-reminder>/ && cur !~ /^<command-/) n++; print n }
' /tmp/prompts.txt
(Blunt but works. If you want surgical accuracy, parse the content array and skip blocks whose first text element is a <system-reminder> tag.)
Tool calls — how many and which tools
jq -r '
select(.type == "assistant") |
.message.content[]? |
select(.type == "tool_use") |
.name
' "$SESSION" | sort | uniq -c | sort -rn
Compaction boundaries — where, why, and what survived
Compaction inserts a system event with subtype:"compact_boundary" (older builds may use isCompactSummary on the next user message). The summary itself is the next user message, prefixed with "This session is being continued from a previous conversation that ran out of context."
# count compaction events
jq -r 'select(.type=="system" and (.subtype // "") == "compact_boundary") | .timestamp' "$SESSION" | wc -l
# was each one auto or manual?
jq -r '
select(.type == "system" and (.subtype // "") == "compact_boundary") |
{ts: .timestamp, trigger: (.compactMetadata.trigger // "unknown"), preTokens: (.compactMetadata.preCompactTokens // null)}
' "$SESSION"
# read the compaction summaries (the actual contents that survived)
jq -r '
select(.type == "user"
阅读完整来源 ↗