Skip to main content
Glama
npx codebase-snapshot generate  # no install: straight to the snapshot
snapshot                        # once installed: detects the project, sets it up, generates

That writes ./snapshot/ — a directory you can drop into a chat, a prompt, a RAG pipeline or a repository review. TypeScript and JavaScript first, but also Python, Go, Rust, Java/Kotlin, C#/.NET, PHP, Ruby, C/C++, Vue, Svelte and Astro, without configuration.

Two ways to give a repository to a model: a dump that was silently truncated, and a snapshot
with a manifest and a validator


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, and nothing overflows it silently: a file too big for a part becomes a head/tail excerpt with an omission marker, and manifest.json records it in incomplete[] with the line ranges it lost.

  • An index, not just text. manifest.json lists every included file with its layer, kind, language, part, hash and a structural summary, every excluded file with the reason, and an incomplete[] list of every file it could only emit in part, with the line ranges it lost.

  • 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.

Related MCP server: DevProjex MCP Server

Install

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, 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

Quick start

Type it. That is the whole first run.

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:

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.

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
├── PROMPT.md                  the instruction sheet to paste with it
├── 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

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 explain <path> answers the same question for any single file.

  • Counts describe what was emitted. includedBytes and includedLines are measured from the block in the part, not from the file on disk. A file that is not valid UTF-8 is kept and labelled utf-8-lossy rather than vanishing as "binary".

  • Drift is checked, not assumed. validate compares every file's hash and a digest of the settings the snapshot was generated with, so a changed budget or secret pattern is drift rather than silence.

  • The output directory is the tool's. Each run is written to a scratch directory and swapped in atomically, and it refuses to replace a directory it did not create — --out-dir src cannot destroy source code.

  • The brief travels with the payload. PROMPT.md is a brief, not a packing slip: the job, the system map the manifest can prove (layers, load-bearing modules, entry points, indexed surfaces), the recent commit history as claims to verify rather than rediscover, the evidence bar, the coverage owed, and calibration examples. Then the apparatus — this run's parts, partial files with their missing line ranges, fingerprint, and the attachment arithmetic. The judgement half can come from your own file (brief) and the job from promptTask. A prompt that names the wrong snapshot is a lie that reads as current, so it is an artifact with a recorded digest and validate fails when it is edited.

  • Credential files are excluded by default — .env, *.pem, .npmrc, id_rsa, *.tfstate and more — and secret-shaped strings inside ordinary files are redacted by masking only the matched span, never the whole line.

Supported projects

25 presets, detected from the repository — each contributing layers, kinds, ecosystem ignore patterns and a recommended part budget.

Next.js

Nuxt

SvelteKit

Remix

Astro

Angular

Solid

Vue + Vite

React + Vite

NestJS

Express / Fastify / Koa

Node library

Monorepo

Django

FastAPI / Flask

Python library

Go

Rust

Java / Spring

.NET

Laravel (PHP)

Rails (Ruby)

Terraform / Docker infra

Docs-only

generic fallback

Non-TypeScript languages get import/export/class/function summaries rather than being treated as opaque text, and every summary is labelled ast, structural or heuristic so you know how much to trust it.

→ Preset table and detection rules

Commands

Command

Does

(none)

The guided first run. Asks once when the project has no config; generates otherwise.

generate (default)

Write the snapshot. --autopilot sets the project up first, unasked.

setup

Config, npm scripts, devDependency, install and generate, in one command.

validate / check

Compare the snapshot with the repository; exit 1 on drift.

report

Snapshot health, layer metrics, secret audit.

init

Interactive (or --yes) setup that writes a self-documenting config.

explain <path>

Why one path is included, which part it lands in, or why it was skipped.

diff <a> <b>

Compare two snapshots.

describe

The machine-readable contract (--format json).

update

Ask npm whether a newer release exists; exit 1 if it does.

skill

Print or install the agent skill.

mcp

Serve the repository to an MCP client over stdio.

Exit codes: 0 success · 1 drift, refused generation, or nothing to snapshot · 2 usage error, or a first run with no terminal and no --autopilot.

Once a day it checks the npm registry for a newer release and mentions it on stderr — skipped in CI, in any --format json run, and in mcp. Turn it off with --no-update-check.

→ Full CLI reference

For AI agents

Everything an agent needs is available as data, and the tool can install its own skill.

npx codebase-snapshot describe --format json   # contract: workflow, options, exit codes
npx codebase-snapshot skill --install          # into .claude/skills + .cursor/rules
npx -y codebase-snapshot@0.20.6 mcp             # or serve it over MCP

An agent told only "use npx codebase-snapshot" can read the contract, follow its ordered workflow, and produce a validated snapshot unaided — that path is covered by a test.

The MCP server exposes 26 tools — status, health, budget, history, tests, workspace, entrypoints, neighbors, routes, cycles, search, stats, review, diff_context, symbol, context, query, plan_for, answer, plan, generate, validate, locate, dependents, read and explain — plus snapshot:// resources and seven prompts. Its reads come from the snapshot rather than the working tree, so an excluded file stays excluded and a redacted value stays redacted, and snapshot_validate answers the question an agent otherwise cannot ask: is the context I was given still true?

→ Using this with an AI agent · MCP server · AGENTS.md · llms.txt

Configuration

snapshot.config.ts (or .mjs) is written by init with every setting at its current value, commented and grouped, so it doubles as the reference. Deleting any line is safe: the defaults are real.

const config = {
  maxPartBytes: "120k",                                   // hard budget per part
  excludePatterns: ["vendor/**", "**/*.min.js"],
  artifacts: { monolith: false },                         // single-file output stays off
  budgets: { default: "120k", byLayer: { docs: 40_000 } },
  includeSensitiveFiles: false,                           // .env, *.pem … stay out
};

export default config;

→ Configuration reference

Programmatic API

import { generateSnapshot, resolveConfig, validateSnapshot, loadConfigFile } from "codebase-snapshot";

// Pass the repository explicitly: loadConfigFile returns only the config it found, so a
// directory with no config file would leave resolveConfig scanning process.cwd() instead.
const dir = "/path/to/repo";
const config = resolveConfig(await loadConfigFile(dir), { cwd: dir });
const manifest = generateSnapshot(config);
const validation = validateSnapshot(config);

CommonJS works too (require("codebase-snapshot")), with type definitions for both. The CLI, the API and the MCP server share one implementation, so anything one of them does is available in the others.

Documentation

Installation

Every client, version pinning, agent skill install

CLI reference

Commands, options, exit codes, examples

Configuration

Every setting, all 25 presets, budgets, hooks, secrets

Snapshot output

Directory layout and the full manifest schema

Health audit

Leak, integrity and token audit of a generated snapshot

In the browser

serve: a local page to generate, preview and download a snapshot

Remote repositories

--remote: a shallow, SSRF-safe clone with recorded provenance

Delta packs

--delta: only what changed since a base snapshot, with its importers

Task slices

--slice: only what the planner picks for a question, at a token budget

Signed snapshots

--sign: an Ed25519 signature over the manifest, verified by health

Benchmarks

Reproducible token and time numbers for the three modes

Security review

Threat model, controls, tests and residual risks

Deploy

Container, compose and systemd, with the token requirement

Migrating

What changed from 0.12.14 to 0.17.0, and the two behaviour changes

Workspaces

--workspace: one snapshot per member, plus the index

Token budget

--budget-tokens: whole files chosen to fit a limit, not torn to fit a part

The brief

The half of PROMPT.md only you can write, and what is refused

AI agents

The contract, the skill, what an agent should avoid

MCP server

26 tools, resources, both protocol eras

Troubleshooting

Every message and what to do about it

Changelog

Release history and breaking changes

Guides: feeding a codebase to ChatGPT, Claude or Cursor · stale LLM context is a bug · how many tokens a codebase is · budgeting a context window · vs repomix · vs gitingest · vs code2prompt

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md and the code of conduct. Security reports: SECURITY.md.

License

MIT © Ankur Halder

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Generates AI context files (CLAUDE.md, AGENTS.md, Cursor/Windsurf/Cline/Continue/Kilo Code/Trae rules, GEMINI.md, Copilot, Aider, Junie, Warp) for any repository. Runs as CLI or MCP server, 100% local.
      3
      46 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Turn any folder or Git repository into token-efficient context for Claude Code, Codex, and Cursor: up to 40% fewer tokens than Repomix, secrets always masked. MCP server with code search, a dependency graph, Git diff review, and Live Context. No embeddings, no vector database.
      8
      6
      43
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Local-first code context CLI + MCP server: discover, index, and search repos; generate task-aware context packs, code maps, agent harnesses, and PR-review/merge-readiness gates for coding agents and reviewers.
      14
      468 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local LLM tools and agentic IDEs to inspect repository token maps, retrieve clean token-bounded codebase snapshots, and audit code for hardcoded secrets via MCP over stdio.
      4
      MIT