{"slug": "show-hn-claude-code-replay-get-lost-project-code-back-from-claude-code-logs", "title": "Show HN: Claude-code-replay – get lost project code back from Claude Code logs", "summary": "Claude-code-replay reconstructs lost project state from Claude Code session logs by replaying file writes and optionally classifying Bash events through Claude Sonnet 4.6. The tool walks JSONL log files in chronological order to restore files and commits, serving as a last resort when destructive commands have wiped a project tree. Users can run it via npx or npm install, with an opt-in classifier that determines which Bash events to execute during recovery.", "body_md": "Replay Claude Code session logs (`*.jsonl`\n\n) to reconstruct the lost project\nstate — file by file, commit by commit, in the order events happened.\nThe tool of last resort when a destructive command wiped the tree.\n\nThere are two replay layers, and the second is opt-in:\n\n**Deterministic replay**— walks every`*.jsonl`\n\nunder`--logs-dir`\n\n(including subagent JSONLs under`<session>/subagents/`\n\n) in strict chronological order and applies file writes.**Claude classifier**(opt-in,`--enable-llm-classifier`\n\n) — every Bash event would otherwise be skipped. With the classifier on, each Bash event is sent to Claude (Sonnet 4.6) which decides`execute`\n\nor`skip`\n\nper event, with reasons. See[How the classifier works](#how-the-classifier-works).\n\nPrerequisites:\n\n**Node 20 or newer.****Claude Code CLI installed and authenticated**(`claude login`\n\n) — only needed for the classifier (`--enable-llm-classifier`\n\n). The classifier reuses that auth via the Claude Agent SDK, so no separate Anthropic API key is needed.\n\nRun without installing:\n\n```\nnpx claude-code-replay --target … --source-root … [flags]\n```\n\nOr install globally:\n\n```\nnpm install -g claude-code-replay\nclaude-code-replay --target … --source-root … [flags]\n```\n\nOr, build from source — clone, `npm install`\n\n, then either\n`npm run replay -- <flags>`\n\ndirectly or `npm link`\n\nto expose it as\n`claude-code-replay`\n\non your `PATH`\n\n.\n\n```\nclaude-code-replay \\\n  --target      /tmp/myrepo-recovered/ \\\n  --source-root /Users/you/projects/myrepo \\\n  --enable-llm-classifier\n```\n\nWhat you'll see on stdout (from a real 304-event replay):\n\n```\nINFO collecting events from /Users/you/.claude/projects/-Users-you-projects-myrepo\nINFO collected 304 events\nINFO building snapshot index from file-history-snapshot entries\nINFO snapshot index covers 43 paths\nINFO classifier: 4 batch(es) over 208 payload events (117 Bash, 91 context); sizes=[71,64,59,14]\nINFO classifier model=claude-sonnet-4-6, mode=base, source-roots=1\nINFO classifier batch 1/4 cache hit\nINFO classifier batch 2/4 cache hit\nINFO classifier batch 3/4 cache hit\nINFO classifier batch 4/4 cache hit\nINFO classifier returned 208 decisions\n=== claude-code-replay summary ===\nevents total:        304\n  replayed:          64 (of 64)\n  skipped:           240\nbash executed:       25 of 25\nclassifier batches:  4 (4 cached, 0 live)\nhalted:              no\nelapsed:             3.70s\ntarget files:        732   (8519381 bytes total)\n```\n\nThe summary omits rows that would be zero on a typical run (overrides,\ncwd-filtered Bash, snapshot heals, lenient-read skips). Per-event\n`CLASSIFY`\n\n/ `APPLY`\n\n/ `CHECK`\n\ntraces and detailed classifier\ndiagnostics are gated behind `--debug`\n\n. Real errors (argv parse\nfailures, classifier API errors) go to stderr; this run log goes to\nstdout so you can pipe it without losing diagnostics.\n\nExit codes: `0`\n\nsuccess, `2`\n\nargv error, `10`\n\nhalted on command failure.\n\n`--target <path>`\n\n— directory the replay writes into. Must be distinct from every logs dir (in either direction); replayed`rm -rf .`\n\ncould otherwise destroy the logs mid-run.`--source-root <path>`\n\n— original absolute`cwd`\n\nfrom the session. Compared verbatim against`event.cwd`\n\nin the logs, so it must match character-for-character (no relative paths, no symlink-resolved paths). Repeatable for sessions that moved across roots.\n\n`--logs-dir <path>`\n\n— directory containing the session`*.jsonl`\n\nfiles (and any`<session>/subagents/`\n\nJSONLs). Optional, repeatable. By default, one logs dir is inferred from each`--source-root`\n\nas`~/.claude/projects/<encoded-source-root>`\n\n(every`/`\n\nin the absolute source-root is replaced with`-`\n\n). Inferred dirs that don't exist on disk are silently skipped; explicit`--logs-dir`\n\nvalues are added on top of the inferred set and must exist.`--cutoff <iso-ts>`\n\n— drop events at or after this ISO 8601 timestamp at parse time. Use when the session's later events include the destructive operation you're recovering from.`--start <iso-ts>`\n\n— start replay at the first event whose timestamp is at or after this. Composes with`--cutoff`\n\nto define a window. The target dir is trusted to already reflect the state events before`--start`\n\nwould have produced.`--from-index <N>`\n\n— start replay at event index`N`\n\n(events`0..N-1`\n\nare not classified or applied). Composes with`--start`\n\n; whichever lands later wins. The halt-and-resume primitive: on a halt at`K`\n\n, fix the cause and resume with`--from-index K`\n\n.\n\n`--strict`\n\n— disable both heal layers (snapshot heal*and*apply-reads heal). Any Read mismatch or missing target halts immediately. Useful when measuring how much of a replay needs healing (e.g. when evaluating a classifier — heal counts in default mode signal what the classifier left on the table).`--strict-reads`\n\n— halt on the first failed Read checkpoint instead of the default (log + continue). Useful for debugging which event triggered a missing-file scenario; the default-on lenient behaviour is what keeps long replays from stopping every time the classifier correctly omits a producing Bash chain (see the cascade rule in).`docs/classifier-prompt.md`\n\n`--enable-llm-classifier`\n\n— opt in to LLM calls. Required to use the classifier at all. The base prompt always includes a git-focused supplement that calls out`git add`\n\n/`git commit`\n\n/`git branch`\n\n/`git checkout`\n\n/`git merge`\n\n/`git rebase`\n\n/`git revert`\n\n/`git reset`\n\n/`git tag`\n\n/`git filter-repo`\n\n(non-exhaustive; the same logic extends to any equivalent state-mutating command, and to heredoc/sed writes whose content a later commit captures). Restoring the original git history is the dominant real-world use case for replay, so it ships as the default rather than an opt-in flag.`--custom-intent \"<intent>\"`\n\n— append a natural-language intent describing what the replay should accomplish. Use for behaviour beyond the built-in git focus, e.g.`\"keep all dependency installs (npm/pip) so node_modules ends up populated\"`\n\nor`\"skip any docker/podman commands; this replay runs without a daemon\"`\n\n. Repeatable; each value is joined with a newline.`--override-classifier-cache`\n\n— skip reading from the classifier cache and force a fresh LLM call, but still write the new response back to the cache (overwriting any existing entry).`--skip-uncached-tail`\n\n— if the cached run's`last_event_ts`\n\nfalls inside the current logs, drop every event with a later timestamp before the classifier sees them. The classifier then full-hits the cache and the runtime replays only what was already cached. Intended for \"re-run yesterday's replay against today's slightly grown logs without paying for the new tail.\" If no cache exists, the flag warns and proceeds without truncation.**Caveat:** events past the cap go unclassified — if the appended tail contains a destructive command, you won't see it.\n\n`--override-skip <INDEX>`\n\n— repeatable. Force event`INDEX`\n\nto skip, regardless of any rule-based or LLM classification. Works on any event type (`Bash`\n\n,`Read`\n\n,`Edit`\n\n,`Write`\n\n, checkpoint).`--override-execute <INDEX>[=CMD]`\n\n— repeatable. Force event`INDEX`\n\n(`Bash`\n\nonly) to execute. Bare form runs the event's original command;`=CMD`\n\nruns the substring`CMD`\n\ninstead (must be a literal substring of the event's original command — same constraint as the LLM classifier's`decision.command`\n\n). Subject to the same`cwd`\n\n-inside-source-roots check as classifier-approved executes.\n\n`--dry-run`\n\n— classify only, no execution. Walks the event stream, prints the summary, but does not apply Writes/Edits, verify Read checkpoints, or execute approved Bash. Combine with`--debug`\n\nto see the per-event`CLASSIFY`\n\nline for every event.`--debug`\n\n— turn on the per-event`CLASSIFY`\n\n/`APPLY`\n\n/`CHECK`\n\ntrace (one line per event) plus verbose classifier instrumentation. Off by default because the default run keeps to a handful of`INFO`\n\nsetup lines and the final summary.\n\nAll requests go through the Claude Agent SDK (`claude-sonnet-4-6`\n\n,\nmulti-turn streaming, no tool use). It reuses Claude Code's existing\nauth — no separate API key needed. The default model id targets the\n200k-context variant; switching to the 1M-context variant (`[1m]`\n\nsuffix) requires Anthropic \"Usage credits\" opt-in and is currently a\nsource-level toggle in `src/llm-classifier/sdk.ts`\n\n.\n\nThe Bash payload is split into batches of 50–100 events, cut at the first\n`git commit`\n\npast the threshold. Each batch becomes one user turn in a\nsingle conversation, so the system prompt and earlier batches are\ncache-served on subsequent turns.\n\nPer-batch responses are cached at\n`$XDG_CACHE_HOME/claude-code-replay/<encoded-target>/batch-NNNN.json`\n\nplus a single `meta.json`\n\n. The encoding mirrors Claude Code's own\nproject-dir scheme: every `/`\n\nin the absolute `--target`\n\npath becomes\n`-`\n\n, so `/tmp/myrepo-recovered`\n\nlives at\n`$XDG_CACHE_HOME/claude-code-replay/-tmp-myrepo-recovered/`\n\n. The cache\ndirectory is intentionally outside `--target`\n\nso a replayed\n`git add .`\n\ncan't sweep it in.\n\n**Cache invalidation.** All-or-nothing: one shared key covers every\nbatch, so any input change invalidates the entire run at once. On a\nmismatch the stale entries are wiped, the classifier recomputes from\nscratch, and the run log states *which* input changed (e.g.\n`INFO classifier cache miss: inputs changed (session logs); wiping stale entries and recomputing 4 batch(es)`\n\n). The following changes\ninvalidate:\n\n**Editing the system prompt**(`src/llm-classifier/prompts.ts`\n\n).**Adding, removing, or changing any**.`--custom-intent`\n\n**Changing the**.`--source-root`\n\nset**Claude Code logs set changes**— a new session JSONL appears, an existing one grows, or`--cutoff`\n\n(applied at parse time) crops the set. Resuming the same logs with a different`--from-index`\n\n/`--start`\n\ndoes NOT invalidate.— forces a fresh call without consulting the cache; results are still written back.`--override-classifier-cache`\n\n**Pointing at a different**— the cache subdir is the encoded target path, so a different target is a different cache namespace (the old one is left orphaned, not deleted).`--target`\n\nThe literal system prompt — including the file-dependency cascade\nrule — lives in\n[ src/llm-classifier/prompts.ts](/glebmish/claude-code-replay/blob/main/src/llm-classifier/prompts.ts).\n\n[explains its rules and the speculation/cache machinery with worked examples; the README does not duplicate the prompt itself.](/glebmish/claude-code-replay/blob/main/docs/classifier-prompt.md)\n\n`docs/classifier-prompt.md`\n\n**Only** Anything else (`Write`\n\n,`Edit`\n\n,`Read`\n\nare deterministic.`Bash`\n\n,`Task`\n\n,`TodoWrite`\n\n,`WebFetch`\n\n, MCP tools, …) is skipped in the default path. The classifier closes the gap for`Bash`\n\nonly; the rest stays skipped.**The classifier is an assistant, not an oracle.** With`--enable-llm-classifier`\n\n, every approved`execute`\n\nruns a real shell command in`--target`\n\n. Run`--dry-run`\n\nand review the`CLASSIFY`\n\n/`APPLY`\n\nstream before trusting it on a fresh tree.**Default-lenient Read checkpoints** mean a misclassified Bash chain can silently produce missing-file Reads that get skipped rather than halted. Use`--strict-reads`\n\n(or the broader`--strict`\n\n) when debugging suspected cascade misses.\n\nA contributor-facing module map of `src/`\n\nlives in\n[ docs/architecture.md](/glebmish/claude-code-replay/blob/main/docs/architecture.md). The system prompt the\nclassifier ships with is in\n\n[, with behavioural explanation in](/glebmish/claude-code-replay/blob/main/src/llm-classifier/prompts.ts)\n\n`src/llm-classifier/prompts.ts`\n\n[. The empirically-derived Claude Code session log format the replayer reads is documented in](/glebmish/claude-code-replay/blob/main/docs/classifier-prompt.md)\n\n`docs/classifier-prompt.md`\n\n[.](/glebmish/claude-code-replay/blob/main/docs/log-format.md)\n\n`docs/log-format.md`\n\n```\nnpm test          # vitest run\nnpm run typecheck # tsc --noEmit\n```\n\nSee [GitHub Releases](https://github.com/glebmish/claude-code-replay/releases)\nfor per-version release notes.\n\nMIT — see [LICENSE](/glebmish/claude-code-replay/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-claude-code-replay-get-lost-project-code-back-from-claude-code-logs", "canonical_source": "https://github.com/glebmish/claude-code-replay", "published_at": "2026-05-29 13:20:11+00:00", "updated_at": "2026-05-29 13:47:49.160326+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "large-language-models"], "entities": ["Claude", "Anthropic", "Claude Code", "Sonnet"], "alternates": {"html": "https://wpnews.pro/news/show-hn-claude-code-replay-get-lost-project-code-back-from-claude-code-logs", "markdown": "https://wpnews.pro/news/show-hn-claude-code-replay-get-lost-project-code-back-from-claude-code-logs.md", "text": "https://wpnews.pro/news/show-hn-claude-code-replay-get-lost-project-code-back-from-claude-code-logs.txt", "jsonld": "https://wpnews.pro/news/show-hn-claude-code-replay-get-lost-project-code-back-from-claude-code-logs.jsonld"}}