contextify-cli

Scan a codebase and produce a single Markdown/text file — with a token count — ready to paste into an AI so it instantly understands your whole project structure.

Install (local dev)

git clone <your-repo-url>
cd contextify-cli
npm install
npm run build
npm link   # makes the `contextify` command available globally

Windows / Git Bash note: make sure typescript is pinned to a stable release in package.json (e.g. "typescript": "5.9.3", no ^). An unpinned install can resolve to the in-progress TypeScript 7.x preview, which handles ESM/shebang output differently and will break the compiled CLI.

Usage

# Scan the current directory, output context.md (compact mode is on by default)
contextify

# Scan a specific project
contextify ../my-other-project

# Output both .md and .txt
contextify --format both

# Custom output name
contextify -o my-context

# Only include specific files
contextify --include "src/**/*.ts"

# Exclude extra paths beyond the built-in defaults
contextify --exclude "**/tests/**,**/*.spec.ts"

# Change the max file size before a file is skipped (default 100kb)
contextify --max-file-size 500kb

# Ignore .gitignore rules
contextify --no-gitignore

# Keep full original code, comments and all
contextify --no-compact

# Drastically shrink tokens: signatures only, bodies collapsed to '...'
contextify --skeleton

What it does

1. Walks the target directory with fast-glob.
2. Skips common junk automatically: .git, node_modules, dist, lockfiles, .min.js, images, fonts, binaries, etc.
3. Respects your project's .gitignore (unless --no-gitignore is passed).
4. Skips any file over --max-file-size.
5. Builds a directory tree.
6. Applies a compression mode (see below) to each file's contents.
7. Concatenates everything into fenced, language-tagged code blocks.
8. Estimates the token count of the final output (via gpt-tokenizer) so you know if it'll fit in your AI's context window, and reports the size reduction vs. the raw source.
9. Writes context.md and/or context.txt.

Compression modes

Pasting an entire codebase into an AI chat can burn through a huge chunk of its context window. There's no real way to shrink that with binary compression — an AI reads plain text tokens, not gzip, so making the bytes smaller (e.g. base64-encoding compressed data) usually makes the token count worse, not better. The only thing that reliably helps is making the actual text shorter while keeping it meaningful. contextify gives you two levels of that:

--compact (default: on)

Strips comments and collapses extra blank lines/trailing whitespace. All real code is kept exactly as-is — nothing is removed that changes what the code does or how an AI would read it. Typically saves 10-25% of tokens for free. Disable with --no-compact if you want the AI to see your comments too (useful if you're asking it to review comment quality, or the comments carry real context).

The stripper tracks string literals as it scans, so things like "http://example.com" or a // looks like a comment inside a string are left untouched — only actual //, /* */, and #-style comments (depending on language) are removed.

--skeleton (default: off)

Replaces function, method, and constructor bodies with a placeholder (/* ... */ or ...), while keeping every signature, class/interface declaration, import, and top-level constant fully visible. This is the "drastic" reduction — commonly 60-80% fewer tokens — because implementation details are gone.

Use this when you want the AI to understand your project's shape: what modules exist, what functions/classes are exposed, how things are named and organized. Don't use it when you need help with actual logic, debugging a specific function, or a detailed code review — for that, use the default compact mode (or --no-compact for the full source).

Skeleton mode currently supports curly-brace languages (TypeScript, JavaScript, Java, C/C++, C#, Go, Rust, Swift, Kotlin, PHP) and Python. It's a heuristic brace/indentation scanner, not a real parser — very unusual formatting can occasionally confuse it. Other languages are passed through unchanged.

Which mode should I use?

| Goal | Mode | |---|---| | Debugging, code review, "why is this broken" | --no-compact (full source) | | General-purpose "understand my project" (default) | --compact | | Huge repo that doesn't fit in context, or "explain my architecture" | --skeleton |

Flags

| Flag | Description | Default | |---|---|---| | -o, --output <name> | Output file base name | context | | -f, --format <md\|txt\|both> | Output format(s) | md | | --max-file-size <size> | Skip files larger than this (e.g. 100kb, 1mb) | 100kb | | --include <glob> | Only include matching files | **/* | | --exclude <glob> | Extra comma-separated excludes | — | | --no-gitignore | Don't respect .gitignore | respects it | | --no-compact | Keep comments and original whitespace | compact is on | | --skeleton | Signatures only, bodies collapsed | off |

Development

npm run dev   # run via tsx without building
npm run build # compile to dist/
npm start     # run compiled version

Project structure:

• src/index.ts — CLI entry point: argument parsing, file walking, output writing.
• src/compact.ts — the comment-stripping, whitespace-collapsing, and skeleton transforms.

License

MIT