GitHub - mkmkkkkk/compactdiff: Snapshot, diff, replay and branch AI coding-agent sessions. Reads Claude Code / Codex logs natively. Redaction on by default. Pure stdlib. · GitHub
/" data-turbo-transient="true" />
Skip to content
Type / to search
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
mkmkkkkk
compactdiff
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>8 Commits<br>8 Commits
compactdiff
compactdiff
demo
demo
tests
tests
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
RELEASE_CHECKLIST.md
RELEASE_CHECKLIST.md
decision.md
decision.md
pyproject.toml
pyproject.toml
View all files
Repository files navigation
compactdiff
Version, replay, and audit AI agent sessions — locally.
Privacy warning: agent transcripts can contain credentials, personal<br>information, source code, private prompts, and tool output. compactdiff<br>redacts common secret fields, tokens, email addresses, phone numbers, and<br>home-directory usernames by default before writing snapshots or exports .<br>Redaction is defense-in-depth, not a guarantee: inspect every replay before<br>sharing it and keep the vault directory private.
The problem: there is no good way to version, replay, or audit AI agent<br>sessions. Claude Code (and similar agents) persist sessions as JSONL, but<br>compaction rewrites them in place, there is no version history, no replay UI,<br>and no way to hand a session to someone else.
What v1 does (record · replay · share)
Capability<br>Implementation
Record (local file watcher)<br>watch polls Claude Code projects and ~/.codex/sessions/**/*.jsonl by default; every changed transcript is snapshotted into a content-addressed vault (~/.compactdiff). Compaction can never destroy history — every observed state is kept, idempotently.
Version<br>list shows every session's version chain (sha · time · lines).
Audit<br>diff proves what a rewrite removed: verdict append-only vs history-rewritten with occurrence-aware ordered line counts (including duplicates and blank lines), keyed on line uuid when present. integrity_chain gives a tamper-evident fingerprint.
Replay (timeline UI)<br>export -o replay.html writes a single self-contained HTML file : dark timeline of semantic events (user / assistant / thinking / tool calls), j/k stepping, click to expand. No server, no external assets.
Share<br>The replay HTML is the share artifact — send one file.
Branch<br>branch --at N -o fork.jsonl writes an inspectable truncated prefix after N conversational messages. Codex developer bootstrap records are preserved but do not consume branch numbers. It does not promise direct Codex/Claude resume.
Quick start
/.jsonl
compactdiff list<br>compactdiff diff # what compaction removed<br>compactdiff export -o replay.html<br>compactdiff branch --at 12 -o fork.jsonl"># install from this local checkout<br>python3 -m pip install -e .
# record continuously (Claude Code + Codex sessions)<br>compactdiff watch
# or snapshot one transcript now<br>compactdiff snapshot ~/.claude/projects/proj>/session>.jsonl
compactdiff list<br>compactdiff diff shaA> shaB> # what compaction removed<br>compactdiff export file|sha> -o replay.html<br>compactdiff branch file|sha> --at 12 -o fork.jsonl
Requires Python 3.9+. Zero runtime dependencies — Python stdlib only. Run tests:<br>python3 -m pytest tests/ -q (23 tests) or<br>python3 -m unittest discover -s tests.
Privacy model
Redaction is on by default for snapshot, watch, export, and branch.
Default vault registries store only each source file's basename, not its full<br>home-directory path.
Raw mode requires both --no-redact and the explicit<br>--i-understand-sensitive-data acknowledgement. Put both global flags before<br>the subcommand. Raw vaults and exports may contain secrets.
Session IDs, prose, uncommon credential formats, and proprietary content may<br>still be sensitive even after pattern redaction. Never publish a replay<br>without a human review.
The offline demonstration is already generated at demo/demo_replay.html; its<br>static screenshot is demo/demo_replay.png. Regenerate the HTML locally with:
python3 -m compactdiff.cli export demo/demo_session.jsonl -o demo/demo_replay.html
Data sources and event boundaries
Claude Code JSONL (~/.claude/projects//*.jsonl): each<br>user/assistant/system content block is an event; other records stay meta.
Codex-native JSONL (~/.codex/sessions/**/*.jsonl): visible<br>response_item messages, reasoning summaries, tool calls, and tool results<br>are events. Mirrored event_msg records and runtime-only token/context state<br>are intentionally not duplicated into the replay.
Nerve Codex runner logs...