{"id":51115050,"url":"https://github.com/glebmish/claude-code-replay","last_synced_at":"2026-06-24T21:00:57.642Z","repository":{"id":360623267,"uuid":"1249482548","full_name":"glebmish/claude-code-replay","owner":"glebmish","description":"Replay Claude Code session logs to reconstruct lost project files, commit by commit.","archived":false,"fork":false,"pushed_at":"2026-05-27T08:14:29.000Z","size":472,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T08:15:38.777Z","etag":null,"topics":["claude-code","cli","recovery","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glebmish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T18:45:24.000Z","updated_at":"2026-05-27T08:14:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/glebmish/claude-code-replay","commit_stats":null,"previous_names":["glebmish/claude-code-replay"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/glebmish/claude-code-replay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glebmish%2Fclaude-code-replay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glebmish%2Fclaude-code-replay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glebmish%2Fclaude-code-replay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glebmish%2Fclaude-code-replay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glebmish","download_url":"https://codeload.github.com/glebmish/claude-code-replay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glebmish%2Fclaude-code-replay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34749211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cli","recovery","typescript"],"created_at":"2026-06-24T21:00:52.497Z","updated_at":"2026-06-24T21:00:57.627Z","avatar_url":"https://github.com/glebmish.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-code-replay\n\n[![CI](https://github.com/glebmish/claude-code-replay/actions/workflows/ci.yml/badge.svg)](https://github.com/glebmish/claude-code-replay/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](./package.json)\n\nReplay Claude Code session logs (`*.jsonl`) 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\n## How it works\n\nThere are two replay layers, and the second is opt-in:\n\n1. **Deterministic replay** — walks every `*.jsonl` under `--logs-dir`\n   (including subagent JSONLs under `\u003csession\u003e/subagents/`) in strict\n   chronological order and applies file writes.\n2. **Claude classifier** (opt-in, `--enable-llm-classifier`) — every Bash\n   event would otherwise be skipped. With the classifier on, each Bash\n   event is sent to Claude (Sonnet 4.6) which decides\n   `execute` or `skip` per event, with reasons. See\n   [How the classifier works](#how-the-classifier-works).\n\n## Install\n\nPrerequisites:\n\n- **Node 20 or newer.**\n- **Claude Code CLI installed and authenticated** (`claude login`) — only\n  needed for the classifier (`--enable-llm-classifier`). The classifier\n  reuses that auth via the Claude Agent SDK, so no separate Anthropic API\n  key is needed.\n\nRun without installing:\n\n```bash\nnpx claude-code-replay --target … --source-root … [flags]\n```\n\nOr install globally:\n\n```bash\nnpm install -g claude-code-replay\nclaude-code-replay --target … --source-root … [flags]\n```\n\nOr, build from source — clone, `npm install`, then either\n`npm run replay -- \u003cflags\u003e` directly or `npm link` to expose it as\n`claude-code-replay` on your `PATH`.\n\n## Quick start\n\n```bash\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` / `APPLY` / `CHECK` traces and detailed classifier\ndiagnostics are gated behind `--debug`. 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` success, `2` argv error, `10` halted on command failure.\n\n## Flags\n\n### Required\n- `--target \u003cpath\u003e` — directory the replay writes into. Must be distinct\n  from every logs dir (in either direction); replayed `rm -rf .` could\n  otherwise destroy the logs mid-run.\n- `--source-root \u003cpath\u003e` — original absolute `cwd` from the session.\n  Compared verbatim against `event.cwd` in the logs, so it must match\n  character-for-character (no relative paths, no symlink-resolved paths).\n  Repeatable for sessions that moved across roots.\n\n### Replay window\n- `--logs-dir \u003cpath\u003e` — directory containing the session `*.jsonl` files\n  (and any `\u003csession\u003e/subagents/` JSONLs). Optional, repeatable. By\n  default, one logs dir is inferred from each `--source-root` as\n  `~/.claude/projects/\u003cencoded-source-root\u003e` (every `/` in the absolute\n  source-root is replaced with `-`). Inferred dirs that don't exist on\n  disk are silently skipped; explicit `--logs-dir` values are added on\n  top of the inferred set and must exist.\n- `--cutoff \u003ciso-ts\u003e` — drop events at or after this ISO 8601 timestamp\n  at parse time. Use when the session's later events include the\n  destructive operation you're recovering from.\n- `--start \u003ciso-ts\u003e` — start replay at the first event whose timestamp\n  is at or after this. Composes with `--cutoff` to define a window. The\n  target dir is trusted to already reflect the state events before\n  `--start` would have produced.\n- `--from-index \u003cN\u003e` — start replay at event index `N` (events `0..N-1`\n  are not classified or applied). Composes with `--start`; whichever\n  lands later wins. The halt-and-resume primitive: on a halt at `K`, fix\n  the cause and resume with `--from-index K`.\n\n### Verification\n- `--strict` — disable both heal layers (snapshot heal *and* apply-reads\n  heal). Any Read mismatch or missing target halts immediately. Useful\n  when measuring how much of a replay needs healing (e.g. when\n  evaluating a classifier — heal counts in default mode signal what the\n  classifier left on the table).\n- `--strict-reads` — halt on the first failed Read checkpoint instead of\n  the default (log + continue). Useful for debugging which event\n  triggered a missing-file scenario; the default-on lenient behaviour is\n  what keeps long replays from stopping every time the classifier\n  correctly omits a producing Bash chain (see the cascade rule in\n  [`docs/classifier-prompt.md`](./docs/classifier-prompt.md)).\n\n### Bash classifier (opt-in)\n- `--enable-llm-classifier` — opt in to LLM calls. Required to use the\n  classifier at all. The base prompt always includes a git-focused\n  supplement that calls out `git add` / `git commit` / `git branch` /\n  `git checkout` / `git merge` / `git rebase` / `git revert` /\n  `git reset` / `git tag` / `git filter-repo` (non-exhaustive; the same\n  logic extends to any equivalent state-mutating command, and to\n  heredoc/sed writes whose content a later commit captures). Restoring\n  the original git history is the dominant real-world use case for\n  replay, so it ships as the default rather than an opt-in flag.\n- `--custom-intent \"\u003cintent\u003e\"` — append a natural-language intent\n  describing what the replay should accomplish. Use for behaviour\n  beyond the built-in git focus, e.g.\n  `\"keep all dependency installs (npm/pip) so node_modules ends up populated\"`\n  or `\"skip any docker/podman commands; this replay runs without a daemon\"`.\n  Repeatable; each value is joined with a newline.\n- `--override-classifier-cache` — skip reading from the classifier cache\n  and force a fresh LLM call, but still write the new response back to\n  the cache (overwriting any existing entry).\n- `--skip-uncached-tail` — if the cached run's `last_event_ts` falls\n  inside the current logs, drop every event with a later timestamp\n  before the classifier sees them. The classifier then full-hits the\n  cache and the runtime replays only what was already cached.\n  Intended for \"re-run yesterday's replay against today's slightly\n  grown logs without paying for the new tail.\" If no cache exists, the\n  flag warns and proceeds without truncation. **Caveat:** events\n  past the cap go unclassified — if the appended tail contains a\n  destructive command, you won't see it.\n\n### Per-event overrides\n- `--override-skip \u003cINDEX\u003e` — repeatable. Force event `INDEX` to skip,\n  regardless of any rule-based or LLM classification. Works on any event\n  type (`Bash`, `Read`, `Edit`, `Write`, checkpoint).\n- `--override-execute \u003cINDEX\u003e[=CMD]` — repeatable. Force event `INDEX`\n  (`Bash` only) to execute. Bare form runs the event's original command;\n  `=CMD` runs the substring `CMD` instead (must be a literal substring\n  of the event's original command — same constraint as the LLM\n  classifier's `decision.command`). Subject to the same\n  `cwd`-inside-source-roots check as classifier-approved executes.\n\n### Diagnostics\n- `--dry-run` — classify only, no execution. Walks the event stream,\n  prints the summary, but does not apply Writes/Edits, verify Read\n  checkpoints, or execute approved Bash. Combine with `--debug` to see\n  the per-event `CLASSIFY` line for every event.\n- `--debug` — turn on the per-event `CLASSIFY` / `APPLY` / `CHECK`\n  trace (one line per event) plus verbose classifier instrumentation.\n  Off by default because the default run keeps to a handful of `INFO`\n  setup lines and the final summary.\n\n## How the classifier works\n\nAll requests go through the Claude Agent SDK (`claude-sonnet-4-6`,\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]`\nsuffix) requires Anthropic \"Usage credits\" opt-in and is currently a\nsource-level toggle in `src/llm-classifier/sdk.ts`.\n\nThe Bash payload is split into batches of 50–100 events, cut at the first\n`git commit` past 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/\u003cencoded-target\u003e/batch-NNNN.json`\nplus a single `meta.json`. The encoding mirrors Claude Code's own\nproject-dir scheme: every `/` in the absolute `--target` path becomes\n`-`, so `/tmp/myrepo-recovered` lives at\n`$XDG_CACHE_HOME/claude-code-replay/-tmp-myrepo-recovered/`. The cache\ndirectory is intentionally outside `--target` so a replayed\n`git add .` can'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\nstale entries and recomputing 4 batch(es)`). The following changes\ninvalidate:\n\n- **Editing the system prompt** (`src/llm-classifier/prompts.ts`).\n- **Adding, removing, or changing any `--custom-intent`**.\n- **Changing the `--source-root` set**.\n- **Claude Code logs set changes** — a new session JSONL appears, an\n  existing one grows, or `--cutoff` (applied at parse time) crops the\n  set. Resuming the same logs with a different `--from-index` /\n  `--start` does NOT invalidate.\n- **`--override-classifier-cache`** — forces a fresh call without\n  consulting the cache; results are still written back.\n- **Pointing at a different `--target`** — the cache subdir is the\n  encoded target path, so a different target is a different cache\n  namespace (the old one is left orphaned, not deleted).\n\nThe literal system prompt — including the file-dependency cascade\nrule — lives in\n[`src/llm-classifier/prompts.ts`](./src/llm-classifier/prompts.ts).\n[`docs/classifier-prompt.md`](./docs/classifier-prompt.md) explains its\nrules and the speculation/cache machinery with worked examples; the\nREADME does not duplicate the prompt itself.\n\n## Limitations\n\n- **Only `Write`, `Edit`, `Read` are deterministic.** Anything else\n  (`Bash`, `Task`, `TodoWrite`, `WebFetch`, MCP tools, …) is skipped in\n  the default path. The classifier closes the gap for `Bash` only; the\n  rest stays skipped.\n- **The classifier is an assistant, not an oracle.** With\n  `--enable-llm-classifier`, every approved `execute` runs a real shell\n  command in `--target`. Run `--dry-run` and review the\n  `CLASSIFY` / `APPLY` stream before trusting it on a fresh tree.\n- **Default-lenient Read checkpoints** mean a misclassified Bash chain\n  can silently produce missing-file Reads that get skipped rather than\n  halted. Use `--strict-reads` (or the broader `--strict`) when\n  debugging suspected cascade misses.\n\n## Architecture\n\nA contributor-facing module map of `src/` lives in\n[`docs/architecture.md`](./docs/architecture.md). The system prompt the\nclassifier ships with is in\n[`src/llm-classifier/prompts.ts`](./src/llm-classifier/prompts.ts), with\nbehavioural explanation in\n[`docs/classifier-prompt.md`](./docs/classifier-prompt.md). The\nempirically-derived Claude Code session log format the replayer reads\nis documented in [`docs/log-format.md`](./docs/log-format.md).\n\n## Tests\n\n```bash\nnpm test          # vitest run\nnpm run typecheck # tsc --noEmit\n```\n\n## Changelog\n\nSee [GitHub Releases](https://github.com/glebmish/claude-code-replay/releases)\nfor per-version release notes.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglebmish%2Fclaude-code-replay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglebmish%2Fclaude-code-replay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglebmish%2Fclaude-code-replay/lists"}