6 min read · by Ankur Halder

Installation

codebase-snapshot is published to the public npm registry, so it installs with any npm-compatible client. There is no second registry to add and nothing to configure.

Requires Node.js 18 or newer.

One command

npx codebase-snapshot --autopilot

Detects the project, writes the config (an existing one is kept), adds the npm scripts and the devDependency, installs them with the package manager your lockfile names, and generates the first snapshot. --no-install skips the install; --dry-run writes nothing. setup does the same as a command word, and the bare snapshot (or npx codebase-snapshot with no arguments) does the same after one question — see the first run. The sections below are the same steps taken one at a time.

The first run

With the package installed globally, the whole thing is one word:

snapshot

In a project with no configuration it names what it recognised and what it keyed on (Detected nextjs / Because next.config.ts), then offers the recommended setup in one keystroke or a walk through each setting with the defaults pre-filled. It writes the config, adds the npm scripts and devDependency, installs, and generates.

In a project that already has a config — or one it has generated before — the same command just generates, so nobody is walked through setup twice.

It never guesses. With no terminal (CI, a container, an agent) a first run exits 2 and names the three ways forward instead of generating with settings nobody chose. --autopilot is the answer for unattended use; naming the command (npx codebase-snapshot generate) is the other, and it runs on the documented defaults exactly as before.

One-off use

npx codebase-snapshot generate

This is the shortest path and needs no install.

Pin the version when you need the same build on every machine. --version prints the exact string to pin:

npx codebase-snapshot@latest generate
npx codebase-snapshot --version

Why the bare name works. npm resolves which binary to run from the package's bin entries. This package declares codebase-snapshot and snapshot pointing at the same file, so npm treats them as aliases and can always resolve one. Keep them aliases: two different executables under a scoped package name would make the bare form unresolvable.

If a command exits with no output at all, a stale global install is the usual cause — see Troubleshooting.

Add to a project

npm install -D codebase-snapshot
yarn add -D codebase-snapshot        # yarn classic and Berry
pnpm add -D codebase-snapshot
bun add -d codebase-snapshot

Then run it through your client so the binary resolves from the project:

snapshot works everywhere codebase-snapshot does — npx snapshot from a project dependency, pnpm exec snapshot, yarn snapshot, and the bare word after a global install. Adding the script to package.json is the most reproducible option:

{
  "scripts": {
    "snapshot": "npx codebase-snapshot generate",
    "snapshot:validate": "npx codebase-snapshot validate"
  }
}

codebase-snapshot init writes these entries for you, in exactly this npx form: the bare codebase-snapshot command only exists on PATH inside a client runner or a script that has already resolved the package, and init does not assume the install has happened yet.

One-off runners for other clients

yarn dlx -p codebase-snapshot codebase-snapshot generate   # yarn Berry
pnpm dlx codebase-snapshot generate
bunx codebase-snapshot generate

Agent skill

To make a repository discoverable by an AI agent — so it finds this tool without being told it exists — run:

npx codebase-snapshot skill --install

That writes .claude/skills/codebase-snapshot/SKILL.md and .cursor/rules/codebase-snapshot.mdc, and adds both to .gitignore so the install leaves nothing untracked. It does not touch AGENTS.md: that file is your project's own agent contract. To put the skill there, print it and paste it — npx codebase-snapshot skill >> AGENTS.md. See Using this with an AI agent.

Verified clients

Every client below installs the published package and runs it successfully; the release check enforces this on every pull request, so a change that breaks one fails the build rather than a user's terminal.

Yarn Berry's default strict PnP works: there is no node_modules directory, and the runtime typescript dependency still resolves through yarn's .pnp.cjs loader.

Before scanning a repository you do not own

A snapshot.config.ts, .js, .mjs or .cjs in the target repository is imported and executed when the tool runs there — that is what lets a config express a RegExp or a match function. Pointing --cwd at a checkout you do not trust therefore runs its code. --no-config ignores every config file and uses the built-in defaults plus the detected preset, and JSON configs are parsed rather than executed. See the trust boundary.

Global install

npm install -g codebase-snapshot

This is what puts the short snapshot command on your PATH.

Convenient, but prefer pinning per project: snapshots are only reproducible if the generator version is. A global install also shadows npx for this package — npm will run your global copy instead of the published one, which is confusing when the two differ. That is exactly the situation described under Troubleshooting.

Workspaces

The binary resolves from the workspace it is installed in. In a monorepo, install it in the package that runs the snapshot (usually the root), or use a one-off runner (npx / pnpm dlx / yarn dlx / bunx) which works from any subdirectory.

Upgrading

npm install -D codebase-snapshot@latest
npx codebase-snapshot generate     # rewrite the snapshot with the new version

manifest.generator.version records which version produced a snapshot. Re-run generate after an upgrade so the snapshot, and the version it records, match the build you are now running.

A snapshot written by 3.0.0 or earlier is refused rather than replaced: its .codebase-snapshot marker has no per-snapshot id, so the current build cannot prove it wrote the directory. Delete the old snapshot directory and generate again.

See CHANGELOG for breaking changes — 3.0.0 removed nothing, but it briefly did in error; 4.0.0 restored the snap alias, and 0.9.2 replaced that alias with snapshot when the version line was restarted.

Uninstalling

Standard for your client (npm uninstall, yarn remove, pnpm remove, bun remove). Snapshots already written to the output directory are ordinary files and are left alone. If you installed globally, npm rm -g codebase-snapshot also removes the shim that shadows npx.

Troubleshooting

codebase-snapshot: command not found — when installed locally (not globally) the binary lives in node_modules/.bin and is only on PATH inside a package script or a client runner. Use npx codebase-snapshot, pnpm exec codebase-snapshot, yarn codebase-snapshot or bun run codebase-snapshot.

A command exits 0 and prints nothing — almost always a stale global install shadowing npx. Check and remove it:

npm ls -g --depth=0 | grep codebase-snapshot
npm rm -g codebase-snapshot

Then re-run. If the package is not installed globally, clear the npx cache (npm cache clean --force) and retry.

Cannot find module 'typescript' — the package declares typescript as a runtime dependency for AST analysis. If your client prunes it (some --ignore-scripts CI setups do), rerun a clean install or pin typescript@^5 yourself.

yarn codebase-snapshot prints extra lines / breaks a script — yarn classic wraps everything: it echoes yarn run 1.22.x, the resolved command, your output, then Done in 0.37s.. For anything that parses the output, call the binary directly (./node_modules/.bin/codebase-snapshot or npx codebase-snapshot).

More symptoms — refusals, config errors, drift, missing files — are in Troubleshooting.