codebase-snapshot
A snapshot you can prove is current.
Plain-text parts under a hard byte budget, an index of every file and every skipped
file with the reason, and a validate command that fails when the code moves.
A snapshot you can prove is current.
Plain-text parts under a hard byte budget, an index of every file and every skipped
file with the reason, and a validate command that fails when the code moves.
Install · Quick start · Trust · AI agents · Docs · Site
--- ## Why Feeding a real repository to a model is awkward: files are too big, context windows are too small, and choosing what matters by hand neither scales nor repeats. This does it deterministically. - **A hard ceiling, not a target.** `maxPartBytes` is a limit. A file bigger than the budget is cut with an explicit omission marker naming the budget, and above `largeFileBytes` it becomes a head/tail excerpt instead — nothing silently overflows the window you sized. - **An index, not just text.** `manifest.json` lists every included file with its layer, kind, language, part, hash and a structural summary, and every *excluded* file with the reason. - **Provably current.** `validate` re-hashes the repository against the snapshot and exits non-zero on any drift, so a pipeline can gate on the context being fresh. - **Repeatable.** Two runs over unchanged input give byte-identical parts and the same `manifest.fingerprint`; only the artifacts that carry a timestamp, run id or pid differ. ## Install ```bash npm install -g codebase-snapshot # puts `snapshot` on your PATH npx codebase-snapshot generate # or no install at all, one-off npm install -D codebase-snapshot # or add it to a project ``` `codebase-snapshot` is the canonical name to script against; `snapshot` is the short command a global install provides, and from a project dependency the same binary is `npx snapshot` or the `npm run snapshot` script `init` writes. Requires **Node.js 18+**. Any npm client works — npm, yarn (classic and Berry with strict PnP), pnpm and bun. Published from GitHub Actions with [build provenance](https://docs.npmjs.com/generating-provenance-statements), so `npm audit signatures` verifies the tarball came from this repository at a tagged commit. This is a **0.x** release: the CLI surface may still change in a minor release until 1.0.0, so pin an exact version if you need a fixed surface today. → [Installation guide](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/install.md) ## Quick start Type it. That is the whole first run. ```bash snapshot ``` It recognises the project and says what it keyed on — `Detected nextjs` / `Because next.config.ts` — then offers the recommended setup in one keystroke, or a walk through every setting with each question starting on its default. Either way it writes the config, adds the npm scripts and the devDependency, installs with your package manager, and generates. A project that already has a config just generates. Nothing to press — CI, a container, an agent: ```bash npx codebase-snapshot --autopilot ``` **A first run never guesses.** With no terminal and no `--autopilot` it exits `2` and names the three ways forward, because a snapshot built from settings nobody chose is a snapshot nobody can check. ```bash npx codebase-snapshot init --yes # config + scripts + devDependency + .gitignore npm install # the package, into node_modules npm run snapshot # generate npm run snapshot:validate # exit 0 = current with disk ``` The fingerprint is printed in full — all 64 hex characters, never elided — and it is the same value as `manifest.fingerprint`. ## What you get ``` snapshot/ ├── README.md human summary of this snapshot ├── manifest.json machine index: files, parts, hashes, config, skips ├── parts/part-001.md … the code, grouped and size-budgeted └── reports/ ├── project-tree.md directory tree of included files ├── navigation.md links between layers, kinds and parts └── audit.md secrets, large files, parse diagnostics, git state ``` Every artifact can be turned off (`--skip-artifacts`, `--only-artifacts`, or the config). → [Snapshot output and manifest schema](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/output.md) ## Built to be trusted with a whole repository A snapshot is only useful if you can believe it, so the tool is explicit about what it does *not* contain. - **Nothing is dropped silently.** Every excluded path is recorded in `manifest.skipped[]` with a reason — `binary`, `gitignore`, `sensitive-file`, `symlink`, `read-error`, `excluded` and the rest — and `explainBuilt by Ankur Halder · documentation · npm