claude-code-replay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gleb Mishchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# claude-code-replay
+
+[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](./package.json)
+
+Replay Claude Code session logs (`*.jsonl`) to reconstruct the lost project
+state — file by file, commit by commit, in the order events happened.
+The tool of last resort when a destructive command wiped the tree.
+
+## How it works
+
+There are two replay layers, and the second is opt-in:
+
+1. **Deterministic replay** — walks every `*.jsonl` under `--logs-dir`
+   (including subagent JSONLs under `<session>/subagents/`) in strict
+   chronological order and applies file writes.
+2. **Claude classifier** (opt-in, `--enable-llm-classifier`) — every Bash
+   event would otherwise be skipped. With the classifier on, each Bash
+   event is sent to Claude (Sonnet 4.6) which decides
+   `execute` or `skip` per event, with reasons. See
+   [How the classifier works](#how-the-classifier-works).
+
+## Install
+
+Prerequisites:
+
+- **Node 20 or newer.**
+- **Claude Code CLI installed and authenticated** (`claude login`) — only
+  needed for the classifier (`--enable-llm-classifier`). The classifier
+  reuses that auth via the Claude Agent SDK, so no separate Anthropic API
+  key is needed.
+
+Run without installing:
+
+```bash
+npx claude-code-replay --target … --source-root … [flags]
+```
+
+Or install globally:
+
+```bash
+npm install -g claude-code-replay
+claude-code-replay --target … --source-root … [flags]
+```
+
+Or, build from source — clone, `npm install`, then either
+`npm run replay -- <flags>` directly or `npm link` to expose it as
+`claude-code-replay` on your `PATH`.
+
+## Quick start
+
+```bash
+claude-code-replay \
+  --target      /tmp/myrepo-recovered/ \
+  --source-root /Users/you/projects/myrepo \
+  --enable-llm-classifier
+```
+
+What you'll see on stdout (from a real 304-event replay):
+
+```
+INFO collecting events from /Users/you/.claude/projects/-Users-you-projects-myrepo
+INFO collected 304 events
+INFO building snapshot index from file-history-snapshot entries
+INFO snapshot index covers 43 paths
+INFO classifier: 4 batch(es) over 208 payload events (117 Bash, 91 context); sizes=[71,64,59,14]
+INFO classifier model=claude-sonnet-4-6, mode=base, source-roots=1
+INFO classifier batch 1/4 cache hit
+INFO classifier batch 2/4 cache hit
+INFO classifier batch 3/4 cache hit
+INFO classifier batch 4/4 cache hit
+INFO classifier returned 208 decisions
+=== claude-code-replay summary ===
+events total:        304
+  replayed:          64 (of 64)
+  skipped:           240
+bash executed:       25 of 25
+classifier batches:  4 (4 cached, 0 live)
+halted:              no
+elapsed:             3.70s
+target files:        732   (8519381 bytes total)
+```
+
+The summary omits rows that would be zero on a typical run (overrides,
+cwd-filtered Bash, snapshot heals, lenient-read skips). Per-event
+`CLASSIFY` / `APPLY` / `CHECK` traces and detailed classifier
+diagnostics are gated behind `--debug`. Real errors (argv parse
+failures, classifier API errors) go to stderr; this run log goes to
+stdout so you can pipe it without losing diagnostics.
+
+Exit codes: `0` success, `2` argv error, `10` halted on command failure.
+
+## Flags
+
+### Required
+- `--target <path>` — directory the replay writes into. Must be distinct
+  from every logs dir (in either direction); replayed `rm -rf .` could
+  otherwise destroy the logs mid-run.
+- `--source-root <path>` — original absolute `cwd` from the session.
+  Compared verbatim against `event.cwd` in the logs, so it must match
+  character-for-character (no relative paths, no symlink-resolved paths).
+  Repeatable for sessions that moved across roots.
+
+### Replay window
+- `--logs-dir <path>` — directory containing the session `*.jsonl` files
+  (and any `<session>/subagents/` JSONLs). Optional, repeatable. By
+  default, one logs dir is inferred from each `--source-root` as
+  `~/.claude/projects/<encoded-source-root>` (every `/` in the absolute
+  source-root is replaced with `-`). Inferred dirs that don't exist on
+  disk are silently skipped; explicit `--logs-dir` values are added on
+  top of the inferred set and must exist.
+- `--cutoff <iso-ts>` — 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>` — start replay at the first event whose timestamp
+  is at or after this. Composes with `--cutoff` to define a window. The
+  target dir is trusted to already reflect the state events before
+  `--start` would have produced.
+- `--from-index <N>` — start replay at event index `N` (events `0..N-1`
+  are not classified or applied). Composes with `--start`; whichever
+  lands later wins. The halt-and-resume primitive: on a halt at `K`, fix
+  the cause and resume with `--from-index K`.
+
+### Verification
+- `--strict` — 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` — 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`](./docs/classifier-prompt.md)).
+
+### Bash classifier (opt-in)
+- `--enable-llm-classifier` — 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` / `git commit` / `git branch` /
+  `git checkout` / `git merge` / `git rebase` / `git revert` /
+  `git reset` / `git tag` / `git filter-repo` (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>"` — 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"`
+  or `"skip any docker/podman commands; this replay runs without a daemon"`.
+  Repeatable; each value is joined with a newline.
+- `--override-classifier-cache` — 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` — if the cached run's `last_event_ts` falls
+  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.
+
+### Per-event overrides
+- `--override-skip <INDEX>` — repeatable. Force event `INDEX` to skip,
+  regardless of any rule-based or LLM classification. Works on any event
+  type (`Bash`, `Read`, `Edit`, `Write`, checkpoint).
+- `--override-execute <INDEX>[=CMD]` — repeatable. Force event `INDEX`
+  (`Bash` only) to execute. Bare form runs the event's original command;
+  `=CMD` runs the substring `CMD` instead (must be a literal substring
+  of the event's original command — same constraint as the LLM
+  classifier's `decision.command`). Subject to the same
+  `cwd`-inside-source-roots check as classifier-approved executes.
+
+### Diagnostics
+- `--dry-run` — 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` to see
+  the per-event `CLASSIFY` line for every event.
+- `--debug` — turn on the per-event `CLASSIFY` / `APPLY` / `CHECK`
+  trace (one line per event) plus verbose classifier instrumentation.
+  Off by default because the default run keeps to a handful of `INFO`
+  setup lines and the final summary.
+
+## How the classifier works
+
+All requests go through the Claude Agent SDK (`claude-sonnet-4-6`,
+multi-turn streaming, no tool use). It reuses Claude Code's existing
+auth — no separate API key needed. The default model id targets the
+200k-context variant; switching to the 1M-context variant (`[1m]`
+suffix) requires Anthropic "Usage credits" opt-in and is currently a
+source-level toggle in `src/llm-classifier/sdk.ts`.
+
+The Bash payload is split into batches of 50–100 events, cut at the first
+`git commit` past the threshold. Each batch becomes one user turn in a
+single conversation, so the system prompt and earlier batches are
+cache-served on subsequent turns.
+
+Per-batch responses are cached at
+`$XDG_CACHE_HOME/claude-code-replay/<encoded-target>/batch-NNNN.json`
+plus a single `meta.json`. The encoding mirrors Claude Code's own
+project-dir scheme: every `/` in the absolute `--target` path becomes
+`-`, so `/tmp/myrepo-recovered` lives at
+`$XDG_CACHE_HOME/claude-code-replay/-tmp-myrepo-recovered/`. The cache
+directory is intentionally outside `--target` so a replayed
+`git add .` can't sweep it in.
+
+**Cache invalidation.** All-or-nothing: one shared key covers every
+batch, so any input change invalidates the entire run at once. On a
+mismatch the stale entries are wiped, the classifier recomputes from
+scratch, and the run log states *which* input changed (e.g.
+`INFO classifier cache miss: inputs changed (session logs); wiping
+stale entries and recomputing 4 batch(es)`). The following changes
+invalidate:
+
+- **Editing the system prompt** (`src/llm-classifier/prompts.ts`).
+- **Adding, removing, or changing any `--custom-intent`**.
+- **Changing the `--source-root` set**.
+- **Claude Code logs set changes** — a new session JSONL appears, an
+  existing one grows, or `--cutoff` (applied at parse time) crops the
+  set. Resuming the same logs with a different `--from-index` /
+  `--start` does NOT invalidate.
+- **`--override-classifier-cache`** — forces a fresh call without
+  consulting the cache; results are still written back.
+- **Pointing at a different `--target`** — 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).
+
+The literal system prompt — including the file-dependency cascade
+rule — lives in
+[`src/llm-classifier/prompts.ts`](./src/llm-classifier/prompts.ts).
+[`docs/classifier-prompt.md`](./docs/classifier-prompt.md) explains its
+rules and the speculation/cache machinery with worked examples; the
+README does not duplicate the prompt itself.
+
+## Limitations
+
+- **Only `Write`, `Edit`, `Read` are deterministic.** Anything else
+  (`Bash`, `Task`, `TodoWrite`, `WebFetch`, MCP tools, …) is skipped in
+  the default path. The classifier closes the gap for `Bash` only; the
+  rest stays skipped.
+- **The classifier is an assistant, not an oracle.** With
+  `--enable-llm-classifier`, every approved `execute` runs a real shell
+  command in `--target`. Run `--dry-run` and review the
+  `CLASSIFY` / `APPLY` stream 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` (or the broader `--strict`) when
+  debugging suspected cascade misses.
+
+## Architecture
+
+A contributor-facing module map of `src/` lives in
+[`docs/architecture.md`](./docs/architecture.md). The system prompt the
+classifier ships with is in
+[`src/llm-classifier/prompts.ts`](./src/llm-classifier/prompts.ts), with
+behavioural explanation in
+[`docs/classifier-prompt.md`](./docs/classifier-prompt.md). The
+empirically-derived Claude Code session log format the replayer reads
+is documented in [`docs/log-format.md`](./docs/log-format.md).
+
+## Tests
+
+```bash
+npm test          # vitest run
+npm run typecheck # tsc --noEmit
+```
+
+## Changelog
+
+See [GitHub Releases](https://github.com/glebmish/claude-code-replay/releases)
+for per-version release notes.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).