Skip to content
fblissjrPublic

About

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.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

439 Commits

Folders and files

Repository files navigation

ccutils

Claude Code transcript analytics: browsable HTML/markdown transcripts and a DuckDB star-schema warehouse with full ETL lineage, built from the session JSONL Claude Code already writes.

Origin: This project began as a fork of Simon Willison's claude-code-transcripts. It has since diverged significantly with star schema analytics, modular architecture, and as a broader Claude utility.

Installation

uv tool install -e .

Or run without installing:

uv run ccutils --help

Quick Start

# Interactive two-phase picker - select projects, then sessions
ccutils

# Convert a single session file (opens in browser)
ccutils session.jsonl

# Export to DuckDB (v0.15 star schema + four-tier ETL + Parquet lake)
ccutils --format duckdb -o ./analytics

# Everything on the machine, in one warehouse
ccutils --source --format duckdb -o ./analytics

# Open what you built
ccutils open -o ./analytics

Commands

One command converts; two do the things that are not converting.

Invocation What it does
ccutils Interactive picker -- the default, no subcommand needed
ccutils PATHS... Convert exactly the session files you name
ccutils --source Convert every session under a directory (the Claude projects dir by default)
ccutils import Import a Claude.ai account export (Settings > Privacy > Export)
ccutils open Open a built warehouse in the DuckDB SQL UI
ccutils audit Check a built warehouse for the defect classes that have shipped; exits nonzero on any error (--strict: on warnings too)
ccutils guide Regenerate the reader's guide (README.md) beside a warehouse; every duckdb build writes it

A conversion that skips a session (it is reported, and the others still load) writes everything it can and then exits 1, so a script can tell a partial build from a complete one.

Removed in 0.20.0, with no aliases: local and all were one operation split by scope, and the split is what let their behaviour drift apart -- global post-loop sources ran on one path and not the other. convert was a hidden duplicate of local and is now the name of the single conversion command. web and schema were deleted outright: one read a different data source through an undocumented API, the other was a generic JSON introspector, and neither had a path to the warehouse. The old names fail with a pointer rather than silently redirecting.

Converting sessions (default)

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 (writes to <archive>/picked/)
ccutils session.jsonl                            # Convert one file, open in browser
ccutils a.jsonl b.jsonl -o ./out                 # Convert several
ccutils session.jsonl --format duckdb -o ./out   # v0.15 star schema DuckDB
ccutils session.jsonl --format markdown -o ./out # One .md per session (quick sharing)
ccutils --format duckdb -o ./analytics           # Pick sessions, star schema
ccutils -p myproject                             # Filter by project name
ccutils --flat                                   # Single-list picker mode
ccutils --no-thinking --no-subagents             # Exclude thinking blocks / related agent sessions

Converting everything

Batch convert every session. Agents and thinking blocks included by default.

ccutils --source -o ./archive                    # Flat HTML archive: index + one file per session
ccutils --source --format markdown -o ./md-archive   # One .md per session, per-project tree
ccutils --source --format duckdb -o ./analytics  # v0.15 star schema for all sessions
ccutils --source -j 4 --batch-size 20 -o ./archive   # Parallel processing
ccutils --source --no-subagents --no-thinking    # Exclude agents and thinking (any format)
ccutils --source --dry-run                       # Preview without converting

import

Import Claude.ai web conversation exports (the ZIP/directory from Settings > Privacy). HTML output only.

ccutils import ./my-claude-export --open         # HTML, opens in browser
ccutils import ./export --interactive            # Pick conversations
ccutils import ./export --list                   # List without converting

Exploring the warehouse

DuckDB ships its own local UI, which is a better SQL notebook than anything worth wrapping, so ccutils open launches it rather than reimplementing it:

ccutils open                      # the default archive
ccutils open -o ./analytics       # a warehouse you built elsewhere
duckdb -ui ./analytics/archive.duckdb   # or drive it yourself

The reader's guide

Every --format duckdb build writes a README.md beside archive.duckdb, generated from the warehouse itself: which projects and sessions it holds, every table and view with its status, row count and reason, the join paths present in the file, and the audit findings accepted with a reason. It is written for an agent opening the directory cold. ccutils guide -o DIR regenerates it.

Auditing the warehouse

ccutils audit                     # the default archive
ccutils audit -o ./analytics      # a warehouse you built elsewhere
ccutils audit --strict            # warnings fail too: for a full-corpus build

Every structural bug this project shipped passed its unit suite and was caught by a person eyeballing corpus numbers. ccutils audit is that eyeballing as a command: natural keys unique, one token-usage row per API response, foreign keys resolving, declared coverage (etl.table_coverage) against what runs actually wrote (etl.steps.table_name), every kept view executing, no run left running or failed, delegation rollups scored against the agent's own transcript, and the grains of fact_messages and fact_tool_calls checked per session against the parquet_lake/ beside the warehouse (only files this warehouse's successful runs wrote). Those are errors. Columns that are always NULL or single-valued, on tables large enough to mean it, are warnings: on a build scoped to one project, one git branch is the scope, not a defect. Exit 0 is no errors, 1 is errors (or warnings, under --strict), 2 is no warehouse or one written by a different schema. Accepted findings live in etl.audit_exceptions with a reason, so a check is never deleted to make a warehouse pass.

It launches; it does not build. With no warehouse there it says so and tells you the command that would create one.

The first run fetches the ui extension (one-time, needs network). For a terminal UI instead, any DuckDB client works — point it at the same file.

lake (experimental)

ccutils lake antigravity                    # mirror Google Antigravity's store into ~/.ccutils/lake/machine=<name>/
ccutils lake antigravity --machine desk     # name this machine (once; the lake remembers, default: the hostname)
ccutils lake antigravity --store antigravity-cli -o DIR
ccutils lake antigravity --decode           # ...then derive readable tables and views beside it
ccutils lake antigravity --decode --verbose # a line on stderr per unit as it is written or decoded

On a terminal the command redraws one progress line in place, naming the unit it is working on, and removes it before the summary. -v/--verbose prints a line per unit that was written, marked gone or decoded, with its row counts, and says nothing about units that did not change. Both go to stderr; with neither a terminal nor the flag (a scheduler, a pipe) nothing is added.

One lake, every machine. The lake base (~/.ccutils/lake) holds a directory per machine, machine=<name>/, with that machine's whole lake inside: every harness, its manifest and lock, and what is decoded from it. A run writes only its own machine's directory. To read two machines together, copy one machine's directory into the other's base and run --decode there; the views read every machine=* directory and carry a machine column, and no run ever touches a directory that is not its own:

rsync -a otherhost:.ccutils/lake/machine=laptop/ ~/.ccutils/lake/machine=laptop/
ccutils lake antigravity --decode

The name lives in the path and nowhere else, so nothing in the archive is rewritten to add it. A lake written before this (directly under the base) is moved into its machine's directory whole on the next run.

Mirrors another harness's native transcript store into a Parquet lake, Tier 1 only (no warehouse). For Antigravity that is every table of every conversations/<id>.db (SQLite of protobuf blobs, kept as bytes), the conversation index, the brain files (transcripts, agent messages, tool outputs, artifacts, the per-conversation .git snapshot history; media as inventory only), and the encrypted legacy .pb files as ciphertext. Nothing is decoded yet. The lake is an archive: unchanged units are skipped, and nothing it held leaves the current tree. Rows the app deleted (a conversation, its summary row, a brain file) stay with source_present = false, and a conversation that was reverted keeps its old snapshot under _superseded/. A step the CLI has emptied in place keeps its full row beside the emptied one, also source_present = false, so steps can hold more than one row for an idx. Reads are an allowlist, so the OAuth tokens beside the data are never opened; the lake is still private data. Experimental: the command and the layout are outside semver until declared stable. Store map and measured claims: docs/ANTIGRAVITY_CONTRACT.md; design and phases: docs/HARNESS_ARCHITECTURE.md.

-- DuckDB over the lake; union_by_name because a drifted file can carry extra columns
SELECT store, step_type, count(*)
FROM read_parquet('~/.ccutils/lake/machine=*/antigravity/*/conversations/*/steps.parquet', union_by_name = true)
WHERE source_present          -- the source's current rows; drop it to add what the app has since
                              -- deleted, and the fuller version of every step it emptied
GROUP BY ALL ORDER BY 3 DESC;

Reading it: --decode. The lake is bytes. --decode derives a second tree from it, machine=<name>/antigravity-decoded/, and never writes inside the archive: one step.parquet and one transcript_line.parquet per conversation. It then writes ~/.ccutils/lake/antigravity.duckdb, a DuckDB file holding only views, over every machine under the base. Deleting that tree loses nothing; the next --decode rebuilds it, and only the conversations that changed. Steps are read by protobuf field number, each reading a measured claim in docs/ANTIGRAVITY_CONTRACT.md (17, 18). --no-thinking writes no thinking text into anything derived (the lake itself still holds it).

duckdb -readonly ~/.ccutils/lake/antigravity.duckdb

Every view's first column is machine, and a conversation or step is keyed with it: the same conversation id on two machines is two rows, and nothing joins across machines.

View One row is What it settles for you
antigravity_conversations a conversation on a machine parent, depth and agent name as the app states them; is_pruned for one the app has deleted and the lake still holds; project, the repository's name in lower case, which is what stays the same when one repository sits at different paths on two machines and is cloned from different remotes (project_source says whether it came from the stated repository or, failing one, the workspace's directory name; repo_slug, git_remote, git_branch and project_path are beside it)
antigravity_steps a step one row per step however many versions the lake kept; text, thinking and tool_output read from the database, else the fuller row the lake kept, else the brain transcript, with a *_source column saying which; is_inherited for steps a fork replayed
antigravity_tool_calls a tool call with its result keyed on the step, because a call id repeats; both encodings, a GENERIC step and the per-tool step types older conversations hold (step_type_name says which). For the older ones the output is read from the brain transcript; their bodies are not decoded yet. is_error is never NULL, and is true for a call answered by an error message step, whose message is error_text
antigravity_usage a step's stated token counts a fork's inherited responses left out, so a sum counts each once; step_type_name separates a model response from a checkpoint, which states the usage of its own call and no model
antigravity_tasks a background task the command that started it, its exit code and its log, which share only a step index: outcome is finished, canceled, or NULL when nothing reported it; the launch columns are NULL when a revert left the log behind; log_text is the whole log
SELECT strftime(created_at, '%Y-%m') AS month, count(*) AS responses,
       sum(input_tokens) AS input, sum(cache_read_tokens) AS cache_read, sum(output_tokens) AS output
FROM antigravity_usage GROUP BY 1 ORDER BY 1;

Background commands that failed, newest first:

SELECT conversation_id, idx, started_at, exit_code, left(tool_args, 120) AS command
FROM antigravity_tasks
WHERE outcome = 'finished' AND exit_code <> 0
ORDER BY started_at DESC LIMIT 20;

One project across machines, by day:

SELECT c.project, c.machine, s.created_at::DATE AS day,
       count(DISTINCT c.conversation_id) AS conversations, count(*) AS steps
FROM antigravity_steps s JOIN antigravity_conversations c USING (machine, conversation_id)
WHERE c.project IS NOT NULL AND s.is_inherited IS NOT TRUE
GROUP BY ALL ORDER BY day DESC, steps DESC LIMIT 30;

To catch up on one conversation, the prompts and the written replies in order. A lake run first makes it current; an agent reading the brain transcript by hand gets the same rows, wrapped in the app's markup and only until the app prunes the conversation:

SELECT idx, created_at, step_type_name, left(text, 200) AS said
FROM antigravity_steps
WHERE conversation_id = (SELECT conversation_id FROM antigravity_conversations
                         ORDER BY last_modified_time DESC LIMIT 1)
  AND step_type_name IN ('USER_INPUT', 'PLANNER_RESPONSE') AND text IS NOT NULL
ORDER BY idx;

A value read from the transcript is the transcript's form of it: user, system and tool text arrive wrapped, and long values can be cut (transcript_is_truncated). Not decoded yet: exit codes, model id strings, agent-to-agent messages, artifacts. Experimental like the lake: the tree's layout and the views are outside semver.

Run it on a schedule. The agy CLI deletes old conversations on its own once enough newer ones exist, brain directory included, and has no setting for it (docs/ANTIGRAVITY_CONTRACT.md claim 13). It also empties the body of old steps while a conversation is still going (claim 16), and the lake can only keep a body it read before that happened. So run it often: hourly costs little, because a run that changes nothing takes seconds and one that is interrupted is picked up by the next. With systemd (a user timer, no root):

# ~/.config/systemd/user/ccutils-lake-antigravity.service
[Service]
Type=oneshot
ExecStart=/path/to/uv run --project /path/to/ccutils ccutils lake antigravity

# ~/.config/systemd/user/ccutils-lake-antigravity.timer
[Timer]
OnCalendar=hourly
Persistent=true
[Install]
WantedBy=timers.target

then systemctl --user enable --now ccutils-lake-antigravity.timer. On macOS a launchd agent with StartCalendarInterval does the same job.

Export Formats

Four formats: html, markdown, duckdb, json (plus both = html+duckdb on all). html and markdown are render-only transcripts; duckdb and json both write the v0.15 star schema. Coverage differs on purpose: the warehouse formats ingest every session on disk (including ones with no summary line), while html/markdown skip warmup/no-summary sessions for a curated browsing archive.

HTML Transcripts

One self-contained .html file per session -- styling and script inlined and pinned by sha256 in a strict CSP, so a transcript is a single file you can open from disk or send to someone. Batch output is flat: one filterable index.html plus one file per session; projects are a filter over the one list, not a page tree. In-page navigation is a collapsible prompt list plus a client-side filter box (no network calls -- the old fetch-based search silently returned zero results when opened from file://).

ccutils -o ./transcript --open
ccutils --source -o ./archive               # Flat archive: index + one file per session

DuckDB Analytics (v0.15 star schema)

ccutils --format duckdb -o ./analytics

v0.15 rebuilds the ETL as a four-tier pipeline:

  1. Tier 0 -- raw JSONL on disk (Claude Code writes).
  2. Tier 1 -- Parquet lake under <output>/parquet_lake/projects/<project>/<session>/. Typed-columnar cache of every parsed JSONL entry. Persistent and re-derivable; the DuckDB warehouse can be torn down and rebuilt from Parquet without re-parsing JSONL.
  3. Tier 2 -- DuckDB staging table (etl.log_entries) loaded from Parquet via read_parquet(), cleared at the end of every run.
  4. Tier 3 -- DuckDB warehouse: dimensions, facts, and semantic views consumers query. The warehouse is persistent and incremental: re-running the CLI against the same database file accumulates new sessions instead of wiping and rebuilding.

Every fact carries the v0.15 lineage convention: created_at, last_updated_at, created_by_version_key, last_updated_by_version_key, etl_run_id, record_source, hash_diff, plus soft-delete (is_deleted, deleted_at). Re-running ETL on unchanged source is a no-op (the hash_diff gate prevents spurious UPDATEs). There are no schema migrations: etl.schema_version is a one-row stamp of the schema fingerprint and ccutils version that wrote the file, and opening a warehouse whose table shapes differ from what the current code creates is refused with a rebuild instruction.

Run metadata (three grains): every CLI invocation writes one etl.batch_runs row; every session ETL writes one etl.runs row (linked via batch_run_id, carrying a CDC data window of min/max entry timestamps); every pipeline node writes one etl.steps row with real affected-row counts. Counts on the parent rows are derived from the children at completion -- the audit trail cannot drift from what the DML actually did. Query semantic_etl_runs for the joined picture.

Subagent transcripts are first-class sessions: agent files carry their parent's sessionId internally, so ccutils keys them by file identity (agent-<id>), links them to their parent session, and computes delegation depth -- your agents don't silently merge into their parents.

Replayed history is kept and marked, not double-counted. A resumed, backgrounded or forked session starts its transcript with a copy of earlier history, under the same tool-call ids. Each transcript's copy is its own row in fact_tool_calls and fact_file_operations (keyed on the session and the call), and the semantic_tool_call_replay view says which rows are copies; every semantic_ view that counts tool calls, file operations or delegations leaves them out. A fork is described by its own work: dim_session.fork_cut_timestamp records where its own history starts, and its classifications, summary totals and delegation figures begin there. A query against the raw facts has to apply both itself. docs/JSONL_CONTRACT.md claims 11 and 12 say what the source does and does not state about this.

Tables populated by run_v15_etl:

  • Machinery, in the etl schema: etl.versions, etl.batch_runs, etl.runs, etl.steps, etl.schema_version (plus transient etl.log_entries staging). main holds only dimensions, facts and views.
  • Dimensions: dim_session (with intent/complexity/outcome/domain enrichment + subagent linkage), dim_project, dim_tool, dim_model, dim_file, dim_session_chain.
  • Core facts: fact_messages, fact_tool_calls (one row per tool use per transcript: the call, its typed toolUseResult payload where the transcript states one, the derived failure kind, and its position in the agentic run), fact_token_usage (R11 cache split: cache_creation_5m_tokens + cache_creation_1h_tokens), semantic_session_summary.
  • Entry-type facts: fact_entry_events (attachments, every permission-mode / title / agent-name / last-prompt entry, file-history snapshots, queue operations and PR links, one row per entry in file order), fact_progress_events, fact_system_events.
  • Derived: fact_file_operations (+ the semantic_session_files view), fact_diagnostics, fact_plan_revisions (structural outcome from fact_tool_calls.is_error), the semantic_agent_delegations view (each Agent/Task spawn a session made itself, joined to the agent's own session), and the semantic_tool_call_replay view (which tool-call rows are a transcript's own).

Populated after the per-session loop (global sources, not per-session, so they are outside run_v15_etl; every command that builds a warehouse runs them, and a build of a subset keeps prompt history to the projects it covers):

  • dim_prompt -- user prompts from the Claude Code prompt-history JSONL, linked to sessions by sessionId.
  • dim_memory + bridge_memory_link -- Claude Code auto memory: the markdown Claude writes to itself per project, plus subagent memory in all three scopes. A Type 2 SCD, because Claude Code overwrites memory files in place and keeps no history of its own -- one row per (memory file, content version), so re-ingesting does not destroy what the memory said before. Deleted memories are closed, not erased. bridge_memory_link carries the link graph in both forms Claude actually writes -- [[wiki-links]] between topic files and the [Title](file.md) entries by which MEMORY.md indexes them -- kept apart by link_syntax, dangling links included. Query semantic_memory / semantic_memory_links for the current state, dim_memory for the history.

The JSON export mirrors the warehouse, so it includes dim_memory — auto-memory bodies and all. That is the same treatment fact_messages already gives full transcript text, but worth knowing before you move an export somewhere else.

Coverage is declared in the warehouse itself. etl.table_coverage lists every table and view in main with its status, what writes it, and why it exists. There are no empty-by-design tables: a table with no writer is not created. No table is conditional on a flag. etl.steps.table_name records what each run actually wrote, so SELECT DISTINCT table_name FROM etl.steps is the measured counterpart.

-- Sessions ranked by uncached-equivalent token cost
SELECT
  ds.session_id,
  fss.total_input_tokens,
  fss.total_output_tokens,
  fss.total_cache_creation_5m_tokens,
  fss.total_cache_creation_1h_tokens,
  fss.total_cache_read_tokens,
  fss.total_uncached_equivalent_tokens
FROM semantic_session_summary fss
JOIN dim_session ds USING (session_key)
ORDER BY total_uncached_equivalent_tokens DESC
LIMIT 20;

-- Tool usage by category. A resumed or forked session's transcript holds
-- copies of calls another session made; NOT is_replay counts each call once.
SELECT dt.tool_category, COUNT(*) AS uses
FROM fact_tool_calls ftu
JOIN semantic_tool_call_replay rp USING (tool_call_key)
JOIN dim_tool dt USING (tool_key)
WHERE ftu.is_deleted = FALSE AND NOT rp.is_replay
GROUP BY dt.tool_category
ORDER BY uses DESC;

-- Bash invocations that failed, with the derived reason
SELECT
  ftu.session_id,
  json_extract_string(ftu.input_json, '$.command') AS command,
  ftu.derived_exit_code,
  ftu.derived_failure_kind,
  ftu.timestamp
FROM fact_tool_calls ftu
JOIN semantic_tool_call_replay rp USING (tool_call_key)
WHERE ftu.tool_name = 'Bash'
  AND ftu.is_error
  AND ftu.is_deleted = FALSE AND NOT rp.is_replay
ORDER BY ftu.timestamp DESC
LIMIT 20;

-- ETL observability: per-session run status, duration, batch context,
-- CDC window, and step rollups in one view
SELECT
  etl_run_id,
  batch_run_id,
  status,
  duration_ms,
  data_start_ts,
  data_end_ts,
  step_count,
  rows_inserted,
  rows_updated,
  ccutils_version
FROM semantic_etl_runs
ORDER BY started_at DESC
LIMIT 10;

-- Orchestration-level scorecard: what did each CLI invocation do
SELECT
  status, sessions_seen, sessions_succeeded, sessions_failed,
  rows_inserted, data_start_ts, data_end_ts, output_format
FROM etl.batch_runs
ORDER BY started_at DESC
LIMIT 5;

JSON Export

The v0.15 star schema as a JSON directory tree (meta.json + dimensions/ + facts/ + etl/ for run metadata; staging is never exported).

ccutils --format json -o ./json-export/

Archiving the full corpus (encrypted)

ccutils --source with no value walks every project under your Claude config dir (the --source default) and writes a single archive.duckdb plus a parquet_lake/ cache covering every session on the machine. ccutils does not do encryption itself -- that's an ops concern, kept out of the tool's scope -- but the export lands as plain files, so any encrypted-volume or encrypt-the-tarball approach works. On macOS the least-friction option is an encrypted sparse disk image: create it once, then mount → export → detach each run.

# One-time: create a password-protected, AES-256 encrypted sparse image.
# Size it for your corpus -- a full-system DuckDB + parquet lake is
# typically tens to a few hundred MB; grow the image if needed.
IMG=cc-archive.sparseimage   # put this wherever you keep backups
hdiutil create -size 5g -type SPARSE -encryption AES-256 \
  -fs APFS -volname CCArchive "$IMG"

# Each run: mount (prompts for password), export everything, detach.
hdiutil attach "$IMG"
ccutils --source --format duckdb -o /Volumes/CCArchive/$(date +%Y-%m-%d)
hdiutil detach /Volumes/CCArchive

The encrypted volume covers both the DuckDB file and the parquet lake (they're just files on it). Two caveats for a full-system export:

  • --private is best-effort and not wired through the v0.15 ETL (the flag is rejected on duckdb/json). On the render formats (html, markdown) it only masks cwd/home-prefixed paths in a subset of channels -- tool_use inputs (file_path/command/content/path) and string tool_result content. It does not sanitize message text, thinking blocks, non-message entries (e.g. file-history-snapshot paths), project directory names, or absolute paths from another machine/user pasted into content. When it can't resolve a working directory (agent transcripts, .json/claude.ai exports) it now prints a loud warning rather than silently no-opping. Treat --private as a convenience for local encrypted archives, not a guarantee for public sharing; review output before sharing. (Comprehensive channel-walking is a tracked follow-up.)
  • The archive is machine-wide transcript data -- keep it out of your checkouts. With no -o the output goes to ~/.ccutils/claude-archive, which is home-anchored precisely so a default run never writes unredacted transcripts for every project on the machine into whatever repo you happened to be standing in. If you pass -o yourself, point it somewhere outside your worktrees (an encrypted volume as above, or any path a git add -A cannot reach).

Portable alternative (any OS), encrypting the export as a single artifact with age:

ccutils --source --format duckdb -o ./archive
tar czf - ./archive | age -r <recipient-key> > archive.tar.gz.age && rm -rf ./archive

Common Options

# Output
-o, --output PATH          Output DIRECTORY, always. --format duckdb writes
                           DIR/archive.duckdb + DIR/parquet_lake/ inside it.
                           Default: ~/.ccutils/claude-archive -- deliberately
                           outside any checkout (single-file conversion with
                           no -o still uses a temp dir)
-s, --source [PATH]        Convert every session under PATH instead of
                           picking. With no value, the Claude projects dir.
                           Mutually exclusive with PATHS
--format FORMAT            html, markdown, duckdb, json (+ both with --source)
--open                     Open result in browser

# Content (included by default -- use flags to exclude)
--no-thinking              Exclude thinking from outputs. Drops thinking from
                           dim_session messages and clears the staging
                           artifact (fact_messages already excludes thinking
                           by projection). Parquet lake is unaffected -- delete it
                           post-run if needed.
--no-subagents             Exclude related agent sessions
--include-temp-sessions    Include sessions whose cwd is under the OS temp
                           directory (excluded by default -- typically
                           sandboxed/ephemeral tooling like eval harnesses,
                           not real projects)
--private                  Sanitize file paths for sharing (html/markdown only; not wired through the v0.15 ETL)

# Rejected rather than ignored
# --private is a hard error on duckdb/json rather than a silent no-op.

# Selection
--flat                     Flat single-list mode (picker)
--expand-chains            Show individual sessions in resumed chains (picker)
-p, --project TEXT         Filter by project name
--dry-run                  Preview without converting (--source)

# Batch processing (--source)
-j, --jobs N               Parallel workers (default: 1)
--batch-size N             Sessions per batch (default: 10)
-q, --quiet                Suppress output except errors
--no-search-index          Deprecated no-op (there is no search index); accepted for compatibility

Documentation

Development

uv run pytest tests/ --confcutdir=tests   # Full suite, in parallel (-n0 to run serially)
uv run ccutils --help                     # Run development version
uv run pytest --cov=ccutils               # Coverage

Project conventions and hard-won pitfalls live in CLAUDE.md.

License

Apache-2.0

About

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.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages