# codebase-snapshot

> Turn any repository into an LLM-ready snapshot: code packed into size-budgeted markdown
> parts, indexed by a JSON manifest, with a secret audit, in one command. Works on TypeScript,
> JavaScript, Python, Go, Rust, Java/Kotlin, C#/.NET, PHP, Ruby, C/C++, Vue, Svelte and Astro.

`codebase-snapshot` is a Node.js CLI (Node >= 18, one runtime dependency: `typescript`). It is
for handing a whole repository to a language model as context: it packs source files into
markdown parts that never exceed a byte budget, records every included file and every excluded
file (with the reason) in `manifest.json`, and reports secrets, large files and git state.

## Start here

- [Agent guide](https://ankurhalder.github.io/codebase-snapshot/agent.html): the machine-readable contract and the installable agent skill; the recommended entry point for an AI agent.
- [Installation](https://ankurhalder.github.io/codebase-snapshot/install.html): every npm-compatible client, version pinning, troubleshooting a shadowed `npx`.
- [CLI reference](https://ankurhalder.github.io/codebase-snapshot/cli.html): every command, every option with its default, exit codes, examples, and what the guided first run asks.
- [Configuration](https://ankurhalder.github.io/codebase-snapshot/configuration.html): every setting and default, the 25 project presets, byte budgets, artifacts, hooks, secret handling.
- [Snapshot output](https://ankurhalder.github.io/codebase-snapshot/output.html): directory layout and the complete `manifest.json` schema.
- [Troubleshooting](https://ankurhalder.github.io/codebase-snapshot/troubleshooting.html): every message the tool prints and what to do about it.
- [Changelog](https://github.com/ankurhalder/codebase-snapshot/blob/main/CHANGELOG.md): release history, breaking changes.

## Machine-readable entry points

- `snapshot` (after a global install) or `npx codebase-snapshot` — the guided first run. It reports the preset it detected and the file that decided it, asks one question, then writes the config, adds the npm scripts + devDependency + .gitignore entries, installs, and generates. A project that already has a config, or that generated before, just generates. **Unattended it exits 2 rather than guessing** and names the alternatives.
- `npx codebase-snapshot --autopilot` — the same first run with no questions, for CI, containers and agents. Keeps an existing config; `--no-install` skips the install.
- `npx codebase-snapshot setup` — the same one-command setup spelled as a command word: write the config (kept if one exists), add the npm scripts + devDependency + .gitignore entries, install dependencies with the project's package manager, then generate. `--no-install` skips the install; `--dry-run` writes nothing.
- `npx codebase-snapshot describe --format json` — the full contract as JSON on stdout: invocation, ordered workflow, commands, options with defaults, exit codes, presets, artifacts, config settings, output layout, safety rules, troubleshooting.
- `npx codebase-snapshot skill` — the bundled agent skill, printed on stdout.
- `npx codebase-snapshot skill --install` — writes the skill to the two registries agent tools read by name: `.claude/skills/codebase-snapshot/SKILL.md` and `.cursor/rules/codebase-snapshot.mdc`, and adds them to `.gitignore`. It never writes `AGENTS.md`; that file is the repository's own agent contract, so print the skill and paste it if you want it there.
- [package.json](https://github.com/ankurhalder/codebase-snapshot/blob/main/package.json) — npm metadata, keywords and entry points.
- npm registry: https://registry.npmjs.org/codebase-snapshot

## Typical use

```bash
npx codebase-snapshot init --yes   # detect the project, write a config
npx codebase-snapshot generate     # write ./snapshot/
npx codebase-snapshot validate     # exit 0 = snapshot matches the files on disk
```

Exit codes: `0` success, `1` drift, refused generation, or nothing to snapshot, `2` usage error —
including a first run that needs an answer and has no terminal. Human progress goes
to stderr; `--format json` payloads go to stdout and are safe to parse. A failing JSON-mode run
still writes one parseable document — `{"error":{"message":…,"exitCode":…}}` — so an agent never
has to parse an empty string or scrape stderr for prose.

## Notes for agents

- Pin an exact version — `npx codebase-snapshot --version` prints the current one — when the same version must run on every machine. The bare package name
  also works — both bin entries (`codebase-snapshot`, `snapshot`) point at the same file, which is what lets npm resolve it.
- **Do not run the bare command expecting it to just generate.** In a project with no configuration it exits 2 without a terminal. Say what you want: `generate` for the documented defaults, `--autopilot` for the full setup, or `init --yes` then `generate` when you want to see each step.
- **If discovery refuses** ("This directory is a git repository, but git could not list its
  files"), the fix is `--discovery walk`: it scans the tree directly and reads `.gitignore` files
  itself. `--discovery git` is the opposite — require git and refuse without it. The default,
  `auto`, uses git when it works and refuses rather than silently changing what the snapshot
  contains.
- The output directory is owned by the tool and is replaced atomically. It refuses to replace a
  directory it did not write, so never point `--out-dir` at source code.
- Credential files (`.env`, `*.pem`, `.npmrc`, `.ssh/`, `.tfstate`) are excluded unless
  `--include-sensitive-files` is given, and they are recorded in `manifest.skipped[]`.
- Secret-shaped strings inside ordinary files are redacted in the emitted parts; no excerpt of a
  matched line reaches any artifact. The count of masked **lines** is `manifest.totals.redactedLines`
  and the per-line table (file, line, every rule that matched) is `reports/audit.md` section 1.
  Redactions are reported separately from `manifest.warnings` — a masked value is the tool working,
  not a defect, so read `Redacted:` and `Warnings:` as different signals.
- Redaction is fail-closed: a `.env.example` placeholder (`JWT_SECRET=replace-with-…`) and a test
  literal (`process.env.X_SECRET = "test-value"`) are masked like live keys. Expect templates to be
  less readable inside the snapshot; do not "fix" that by re-reading the raw file into context.
- `manifest.files[]` carries `encoding` when a file was not plain UTF-8: `utf-16le`/`utf-16be` were
  transcoded to text, and `utf-8-lossy` means the body contains `U+FFFD` where undecodable bytes
  were. Its absence means clean UTF-8.
- `manifest.skipped[]` names a reason for every excluded path — `binary`, `gitignore`,
  `default-ignore`, `sensitive-file`, `sensitive-path`, `symlink`, `outside-root`, `read-error`,
  `not-file`, `nested-repository` (a submodule or nested checkout) or `excluded`. `nested-repository`
  and `not-file` only appear for candidates git listed as a directory.

## Optional

- [AGENTS.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/AGENTS.md): conventions for contributing to this repository.
- [Wiki](https://github.com/ankurhalder/codebase-snapshot/wiki): a pointer to the documentation site.
- [Releases](https://github.com/ankurhalder/codebase-snapshot/releases): version history with notes.
- [Feeding a codebase to ChatGPT, Claude or Cursor](https://ankurhalder.github.io/codebase-snapshot/how-to-feed-a-repo-to-claude.html): the end-to-end recipe, including what the model should be told about the snapshot it is reading.
- [Stale LLM context is a bug](https://ankurhalder.github.io/codebase-snapshot/stale-context-is-your-bug.html): why a snapshot goes out of date silently, and the fingerprint/validate/gate controls that make drift visible.
- [How many tokens is a codebase?](https://ankurhalder.github.io/codebase-snapshot/codebase-token-budget.html): the arithmetic of bytes, tokens and context windows, with a measured example and a budget table.
- [Budgeting LLM context](https://ankurhalder.github.io/codebase-snapshot/how-to-context-budget.html): how to choose `maxPartBytes`, `largeFileBytes` and per-layer ceilings from the consumer rather than from taste.
- [vs repomix](https://ankurhalder.github.io/codebase-snapshot/vs-repomix.html), [vs gitingest](https://ankurhalder.github.io/codebase-snapshot/vs-gitingest.html), [vs code2prompt](https://ankurhalder.github.io/codebase-snapshot/vs-code2prompt.html): honest comparisons that say where each alternative is the better choice.