Claude utilities for session transcripts, star schema analytics, data exploration, and probably more as it comes up as a use case in my day to day.
Origin: This project began as a fork of Simon Willison's claude-code-transcripts. It has since diverged significantly with star schema analytics, a visual data explorer, modular architecture, and as a broader Claude utility.
uv tool install -e .Or run without installing:
uv run ccutils --help# Interactive two-phase picker - select projects, then sessions
ccutils
# Convert a single session file (opens in browser)
ccutils session.jsonl
# Export to DuckDB for SQL analytics
ccutils --format duckdb -o ./archive
# Export with star schema (22 tables + 10 views)
ccutils --format duckdb-star -o ./analytics
# Launch visual data explorer
ccutils explore ./analytics/archive.duckdb| Command | Description |
|---|---|
local |
Interactive picker + single-file conversion -- default (no subcommand needed) |
all |
Batch convert all sessions (HTML archive, DuckDB, or JSON) |
web |
Import from Claude API (auto-detects credentials from macOS keychain) |
explore |
Launch Data Explorer web UI for star schema databases |
import |
Import Claude.ai account exports (Settings > Privacy > Export) |
schema |
Inspect JSON structure without exposing content (safe to share publicly) |
The default command. With no arguments, launches a two-phase interactive picker (projects then sessions). Pass a session file to convert it directly.
Thinking blocks and subagent sessions are included by default.
ccutils # Interactive picker
ccutils session.jsonl # Convert file, open in browser
ccutils session.jsonl --format duckdb-star -o . # Star schema from file
ccutils --format duckdb-star -o ./analytics # Pick sessions, star schema
ccutils -p myproject # Filter by project name
ccutils --flat # Legacy single-list mode
ccutils --no-thinking --no-subagents # Exclude thinking/agents
ccutils --format duckdb-star --embed -o . # With ColBERT embeddingsBatch convert every session. Agents and thinking blocks included by default.
ccutils all -o ./archive # HTML archive with search index
ccutils all --format duckdb-star -o ./analytics # Star schema for all sessions
ccutils all --format duckdb-star --embed -o ./out # With ColBERT embeddings
ccutils all -j 4 --batch-size 20 -o ./archive # Parallel processing
ccutils all --no-agents --no-thinking # Exclude agents and thinking
ccutils all --dry-run # Preview without convertingImport Claude.ai web conversation exports (the ZIP/directory from Settings > Privacy).
ccutils import ./my-claude-export --open # HTML, opens in browser
ccutils import ./export --format duckdb -o data.duckdb # DuckDB
ccutils import ./export --interactive # Pick conversations
ccutils import ./export --list # List without convertingVisual query builder for star schema DuckDB databases. Runs a local web server.
ccutils explore ./analytics/archive.duckdbInspect JSON file structure without exposing content. Output is safe to share publicly or paste into AI assistants.
ccutils schema conversations.json
ccutils schema ./my-claude-export/ # Inspect all files in directory
ccutils schema ./export --json > schema.json # Machine-readable outputSchema type is auto-inferred from --format: duckdb-star and json-star use star schema, plain duckdb and json use simple.
Clean, mobile-friendly HTML with pagination, commit timeline, tool stats, and full-text search.
ccutils -o ./transcript --open
ccutils all -o ./archive # Archive with master index and searchccutils --format duckdb -o ./archiveTables: sessions, messages, tool_calls, thinking
ccutils --format duckdb-star -o ./analyticsDimensional model designed for analytics:
- 6 dimensions: sessions (with heuristic classifications), projects, tools (with categories), models (with families), dates, times
- 6 core facts: messages, tool calls (with duration tracking), session summaries (with inclusive agent metric rollup), file operations, errors (with type classification), tool chain steps
- 5 granular tables: files (with language detection), session chains, content blocks, code blocks, entity mentions
- 3 agent/bridge tables: agent delegations (with denormalized metrics), cross-session file tracking, task-agent mapping
- 2 optional: ColBERT embeddings, tool input parameters
- 10 semantic views: pre-joined views for common queries (includes project context and file tracking)
The star schema ETL runs heuristic classification during ingestion with zero external dependencies -- no LLM, no API key needed. Results are stored on dim_session:
| Classifier | Method | Values |
|---|---|---|
| Intent | Score-based keyword matching on first user message | bug_fix, feature, refactor, debug, test, docs, review, explore |
| Complexity | Points-based scoring from session metrics | trivial, simple, moderate, complex |
| Outcome | Inferred from last assistant message + error rate | success, failure, unknown |
| Domain | Inferred from file extensions touched | web, backend, data, devops, docs, mixed, unknown |
| Error type | Classified from error message text (on fact_errors) |
permission_denied, file_not_found, syntax_error, timeout, import_error, tool_error |
-- What kinds of sessions do I have?
SELECT intent, complexity, COUNT(*) as sessions
FROM dim_session GROUP BY intent, complexity ORDER BY sessions DESC;
-- Tool usage by category
SELECT dt.tool_category, COUNT(*) as uses
FROM fact_tool_calls ftc
JOIN dim_tool dt ON ftc.tool_key = dt.tool_key
GROUP BY dt.tool_category ORDER BY uses DESC;
-- Am I more productive mornings or evenings?
SELECT dti.time_of_day, COUNT(*) as sessions, AVG(fss.total_messages) as avg_msgs
FROM fact_session_summary fss
JOIN dim_time dti ON fss.time_key = dti.time_key
GROUP BY dti.time_of_day;
-- Most-touched files across all sessions
SELECT df.file_path, SUM(bsf.write_count + bsf.edit_count) as modifications
FROM bridge_session_file bsf
JOIN dim_file df ON bsf.file_key = df.file_key
GROUP BY df.file_path ORDER BY modifications DESC LIMIT 20;
-- Catch up on a project (what was worked on recently)
SELECT first_user_message, last_assistant_message, intent, created_at
FROM semantic_project_context
WHERE project_name = 'my-project' LIMIT 5;# Simple schema - single file
ccutils --format json -o ./sessions.json
# Star schema - directory structure (dimensions/ + facts/ + meta.json)
ccutils --format json-star -o ./star-export/# Output
-o, --output PATH Output directory or file
--format FORMAT html, duckdb, duckdb-star, json, json-star
--open Open result in browser
# Content (included by default -- use flags to exclude)
--no-thinking Exclude thinking blocks
--no-subagents Exclude related agent sessions (local)
--no-agents Exclude agent-* session files (all)
--private Sanitize file paths for sharing
# Selection (local command)
--flat Flat single-list mode (skip project grouping)
--expand-chains Show individual sessions in resumed chains
-p, --project TEXT Filter by project name
# Embeddings (local and all commands, star schema only)
--embed [MODEL] Run ColBERT embeddings (optionally specify model)
# Batch processing (all command)
-j, --jobs N Parallel workers (default: 1)
--batch-size N Sessions per transaction (default: 10)
--no-search-index Skip search index generation- Star Schema Reference -- table definitions, ETL capabilities, heuristic classification, example queries
- Data Explorer Guide -- visual query builder features and architecture
uv run pytest # Run tests (~737 passing)
uv run ccutils --help # Run development version
uv run pytest --cov=ccutils # CoverageApache-2.0