Scripts

Utility scripts for analyzing Claude Code session data.

but_usage_report.py

Extracts and visualizes every invocation of the but CLI from past Claude Code sessions.

What it does

1. Scans all JSONL session files under ~/.claude/projects/ (~3k+ files)
2. Extracts every Bash tool call where the command starts with but or but-
3. Matches each command to its tool result output (handles two different JSONL result formats)
4. Detects errors via the is_error flag, non-zero exit codes, and stderr heuristics
5. Outputs structured data as JSON + CSV, and generates 4 analysis charts

Quick start

# Full pipeline: extract data + charts + summary
python3 but_usage_report.py

# Data only (no matplotlib needed)
python3 but_usage_report.py --extract-only

# Regenerate charts from existing data
python3 but_usage_report.py --charts-only

# Custom output location
python3 but_usage_report.py --output-dir /tmp/my-analysis

Prerequisites

• Python 3.10+
• matplotlib (only for charts; --extract-only works without it)

pip install matplotlib

Output files

All outputs go to ./but_usage_output/ by default (override with --output-dir):

File	Description
but_usage.json	Full extracted data (see schema below)
but_usage.csv	Same data, command output truncated to 5000 chars
but_subcommand_histogram.png	Subcommand popularity (horizontal bar chart)
but_error_rate.png	Error rate by subcommand (for commands with 5+ uses)
but_usage_over_time.png	Daily usage volume
but_subcommand_mix.png	Stacked daily breakdown by top 8 subcommands

Data schema

Each record in but_usage.json:

Field	Type	Description
session_id	string	Claude Code session UUID (from JSONL filename)
project	string	Project directory name from ~/.claude/projects/
timestamp	string|number	Message timestamp (epoch ms or ISO string)
command	string	Full shell command, e.g. but status --json
but_subcommand	string	Parsed subcommand: status, commit, branch, etc.
description	string	Claude's description of what the command does
output	string	Tool result text (stdout + stderr combined)
is_error	boolean	Whether the command failed

How it parses Claude Code sessions

Claude Code stores session transcripts as JSONL files in ~/.claude/projects/<project>/<session-id>.jsonl. Each line is a JSON object representing a message or event.

• Tool calls appear as tool_use blocks inside message.content with name: "Bash"
• Tool results appear in the next 1-3 lines in one of two formats:
  • tool_result blocks in message.content (with content text and is_error flag)
  • toolUseResult top-level field (with stdout, stderr, interrupted fields)

The script does a two-pass scan per file: first collecting all but tool calls, then searching forward for each call's matching result.

but_agent_friendliness.py

Deep analysis of how agent-friendly the but CLI is. Reads the but_usage.json produced by but_usage_report.py and evaluates 7 dimensions of agent-friendliness, producing a text report and 8 charts.

Quick start

# First, extract the data (if not already done)
python3 but_usage_report.py --extract-only

# Full analysis: text report + charts
python3 but_agent_friendliness.py

# Text report only (no matplotlib needed)
python3 but_agent_friendliness.py --report-only

# Charts only
python3 but_agent_friendliness.py --charts-only

# Output to a separate folder (copy but_usage.json there first)
python3 but_agent_friendliness.py --output-dir agent_friendliness_report

Analysis dimensions

#	Dimension	What it measures
1	Status overhead	% of commands that are but status; per-session distribution; status-sandwich patterns
2	JSON output gaps	--json adoption rate per subcommand; which commands have 0% JSON support
3	Pipe workarounds	What agents pipe to (jq/python3/head/grep); what JSON fields they extract
4	Retry patterns	Consecutive same-subcommand runs indicating agent struggle
5	Error categories	Classification: stale IDs, argument confusion, invalid targets, etc.
6	Error recovery	How agents respond after errors: adapt, pivot, blind-retry, or give up
7	Workflow sequences	Command transition matrix showing common multi-step patterns

Plus an Agent Friendliness Scorecard scoring 5 dimensions 0–100.

Output files

File	Description
agent_status_overhead.png	Per-session status check overhead histogram
agent_json_gaps.png	JSON adoption rate by subcommand (stacked bar)
agent_pipe_workarounds.png	Pipe targets + extracted fields (two-panel)
agent_retry_struggles.png	Struggle patterns by subcommand
agent_error_categories.png	Error classification with preventability color-coding
agent_error_recovery.png	Recovery behavior donut chart
agent_workflow_transitions.png	Command transition heatmap (10x10)
agent_friendliness_scorecard.png	Dimension scores bar chart