cctrace

Table of Contents

cctrace is a lightweight Python tool for extracting Claude Code session transcripts from the local JSONL files that Claude Code stores in ~/.claude/projects/. It reads the raw session data, parses the conversation structure, and outputs formatted transcripts suitable for archival in a git repository.

How It Works #

Claude Code stores session data as JSONL (JSON Lines) files in a project-specific directory under ~/.claude/projects/. Each line in these files represents a conversation turn – a human message, an assistant response, a tool invocation, or a system event.

cctrace reads these files and reconstructs the conversation flow, producing output that preserves:

The sequence of human prompts and AI responses
Tool calls and their results (file reads, edits, shell commands)
Timestamps for each turn
Session metadata (model used, project path, session ID)

Installation #

Install from PyPI:

pip install cctrace

Or with uv:

uv pip install cctrace

Basic Usage #

List available sessions for the current project:

cctrace list

Export a specific session:

cctrace export <session-id>

Export all sessions for the current project:

cctrace export --all

Output Formats #

cctrace produces structured transcript output that is both human-readable and machine-parseable. The output includes clear delineation between human and assistant turns, tool call details, and session metadata headers.

The structured output is ai-ready – an LLM can consume it directly to understand what happened in a session, review the decisions that were made, or continue work from where a previous session left off.

Archival Workflow #

A typical workflow for archiving Claude Code sessions with cctrace:

After a coding session, run cctrace export --all to extract new transcripts
Store the output in a dedicated directory (e.g., sessions/ or .ai-sessions/)
Commit the transcripts to git
Optionally, use git-annex for large transcript files

For automated archival, combine cctrace with Claude Code Hooks – a SessionEnd hook can trigger cctrace export automatically after each session completes.

Example hook script:

#!/bin/bash
# .claude/hooks/session-end.sh
SESSION_ID="$1"
cctrace export "$SESSION_ID" >> sessions/archive.jsonl
git add sessions/archive.jsonl
git commit -m "Archive AI session $SESSION_ID"

Comparison with Other Tools #

cctrace focuses on simplicity and directness. It reads local files and produces formatted output – no shadow branches, no metadata indexes, no multi-tool support.

For projects that need only Claude Code transcript archival and prefer a minimal dependency footprint, cctrace is a practical choice. For more comprehensive session management, see Entire.io (shadow branches, attribution, multi-tool) or ccexport (multiple output formats).

Limitations #

Alpha status – The tool is in early development. The output format and CLI interface may change.
Claude Code only – Does not support other AI tools (Cursor, Copilot, etc.).
No incremental export – Each export re-reads the full session; there is no built-in mechanism to export only new turns since the last archival run.
Local storage dependency – If Claude Code’s local storage format changes, cctrace will need to be updated to match.