cc-history_skill

Overview

This skill documents how to inspect and analyze Claude Code conversation history files using shell tools and jq. It explains directory layout, message types and structures, and provides practical commands for searching, extracting, and aggregating conversation data. The focus is on reproducible queries for tokens, tool usage, and subagent correlation.

How this skill works

The skill shows how to locate a project directory derived from the current working directory, then read JSONL conversation files line-by-line. It explains message fields (type, uuid, parentUuid, timestamp, sessionId, message) and content block types (thinking, tool_use, text). Example jq and shell pipelines extract messages, count tokens, list tool calls, and correlate subagent files with parent Task invocations.

When to use it

• Audit recent or historical conversations and token expenditure
• Identify and count tool invocations and which tools are used most
• Extract specific messages by uuid, timestamp, or type
• Correlate parent conversations with spawned subagents and their tasks
• Search conversations for specific skill invocations or commands

Best practices

• Compute PROJECT_DIR from $PWD using the provided path-encoding rule to avoid manual lookup
• Use jq -c and selective filters to keep output compact and line-delimited for further processing
• Summarize token usage with jq -s to combine per-line usage into session totals
• Filter assistant content[] before selecting tool_use blocks to avoid null errors
• When correlating subagents, read first user message in each subagent file and match to Task tool_use input in the parent

Example use cases

• List all session files sorted by modification time to find recent activity
• Extract an assistant message by uuid for debugging a specific response
• Count tool calls by name to prioritize optimization or deprecation
• Aggregate token usage across a session to estimate cost and cache impact
• Match subagent task descriptions to Task invocations in the parent conversation to understand automated workflows