Description
codebase-snapshot is a utility designed to transform a code repository into a set of LLM-ready parts, adhering to a strict byte budget. It addresses the challenges of feeding large repositories to language models, where files can be too big and context windows too small. The tool operates deterministically, ensuring consistent output across runs for unchanged input.
Read More
The core functionality revolves around creating a `snapshot/` directory containing plain-text parts. Each part is limited by a `maxPartBytes` ceiling; files exceeding this budget are truncated with explicit omission markers. For very large files, it provides a head/tail excerpt. Alongside the code parts, it generates a `manifest.json` file. This manifest acts as a comprehensive index, listing every included file with details like its layer, kind, language, part, hash, and a structural summary. Crucially, it also records every excluded file along with the specific reason for its omission, such as `gitignore`, `sensitive-file`, or `binary`.
A key feature for maintaining context integrity is the `validate` command. This command re-hashes the repository against the generated snapshot and exits with a non-zero code if any drift is detected. This ensures that the LLM context remains fresh and accurate, preventing models from working with outdated code. The tool is designed to be safe by default, skipping credential files unless explicitly requested, redacting secret-shaped strings, and preventing accidental deletion of source code by refusing to overwrite directories it didn't create.
codebase-snapshot supports a wide range of programming languages and frameworks, including TypeScript, JavaScript, Python, Go, Rust, Java/Kotlin, C#/.NET, PHP, Ruby, C/C++, Vue, Svelte, Astro, Next.js, Nuxt, Remix, Angular, Solid, NestJS, Express, Fastify, Koa, Django, FastAPI, Flask, Laravel, and Rails, often without requiring configuration. It provides 25 automatic presets that contribute layers, kinds, ecosystem ignore patterns, and recommended part budgets. For non-TypeScript languages, it generates import/export/class/function summaries, labeling them as `ast`, `structural`, or `heuristic` to indicate their reliability.
Beyond human interaction, codebase-snapshot is built for AI agents. It offers a machine-readable contract and an installable skill, allowing agents to drive the entire process autonomously. Agents can use commands like `generate`, `validate`, `report`, and `explain` to manage snapshots, check for drift, audit secrets, and understand file inclusions/exclusions. The tool also supports programmatic API access for integration into larger systems. Its comprehensive documentation covers installation, CLI reference, configuration, snapshot output schema, and guides for using it effectively with LLMs like ChatGPT, Claude, and Cursor.
- CategoryAI Coding Assistants
- Pricing ModelFree
- DeploymentCLI, Programmatic API
- PlatformsNode.js 18+
codebase-snapshot's Core Features
Deterministic snapshot generation
Hard byte budget for parts
Comprehensive manifest.json index
Drift validation with `validate` command
Automatic detection for 25 project presets
Support for multiple programming languages and frameworks
Secret redaction and sensitive file exclusion
Machine-readable contract for AI agents
Installable agent skill
Programmatic API access
Detailed reporting and auditing
Guided first-run setup
Configurable output artifacts
Memory-bounded processing for large files
Snapshot comparison with `diff` command
How to use codebase-snapshot?
Install: Use npm, yarn, pnpm, or bun to install `codebase-snapshot` globally or as a project dependency.
Quick Start: Run `snapshot` in your project directory for a guided first run or automatic generation.
Configure: Use the `init` command for an interactive setup that writes a self-documenting `snapshot.config.ts` file.
Generate Snapshot: Execute `snapshot generate` to create the LLM-ready snapshot directory.
Validate Snapshot: Run `snapshot validate` to compare the snapshot against the current repository and check for drift.
Explain Paths: Use `snapshot explain <path>` to understand why a specific file was included, skipped, or where it landed.
Audit Reports: Generate `snapshot report` for health metrics, layer details, and secret audits.
codebase-snapshot's Use Cases
- LLM Context Generation
- AI Agent Code Analysis
- Code Review Automation
- Developer Onboarding
- Context Window Management
- Codebase Auditing
- Ensuring Context Freshness
- Cross-Repository Comparison
