supercontext

supercontext converts any local project folder or git repository into an LLM-friendly context dump — a structured context/ folder with a file map, symbol index, and per-file markdown snapshots ready to paste into any AI tool.

Install

npm install -g @kamaravichow/supercontext

Usage

supercontext [target] [options]

Arguments:

Argument	Description
target	Local folder path or git URL (optional — prompted interactively if omitted)

Options:

Flag	Description
-h, --help	Show help
-v, --version	Show version
-o, --out <dir>	Output directory (default: <target>/context)
--types <csv>	Comma-separated extensions to include, e.g. .js,.ts,.py or *
--max-size <kb>	Per-file size cap in KB (default: 128)
--include-hidden	Include hidden files/folders
--no-interactive	Skip prompts; use defaults / flags

Examples

# Interactive mode — prompts for target and file types
supercontext

# Dump a local folder non-interactively
supercontext ./my-project --no-interactive

# Clone a git repo and dump it
supercontext https://github.com/user/repo --no-interactive

# Only include JS/TS files, cap at 64 KB per file
supercontext ./my-project --types .js,.ts --max-size 64

Output

Running supercontext produces a context/ folder (or the directory you specify with --out) containing:

File	Description
README.md	Summary: frameworks, file count, byte count, role breakdown, token estimate
map.md	File tree annotated with role tags + symbol counts
roles.md	Files grouped by inferred role (model, route, component, …)
mapping.json	Machine-readable file → symbols index, with per-file role
mapping.md	Human-readable version of the symbol index
byKeyword.json	Reverse index: symbol name → { file, role, kind, line, exported }
dump/	One .md per source file with role tag + extracted symbols + full source

Why the role tag matters. Every file is classified into a coarse role (model, schema, controller, route, service, repository, middleware, view, component, page, hook, store, type, migration, test, fixture, script, config, manifest, util, doc, generated, …) using path conventions, framework signatures, decorators/annotations, and base-class inheritance. LLMs and search agents can prefilter by role before any keyword search — so a "change the User model" request never has to scan the dependency manifest, route table, or test fixtures.

Supported Languages

JavaScript / TypeScript · Python · Dart · Go · Rust · Java · Kotlin · Swift · C / C++ · C# · Ruby · PHP · HTML / CSS / Vue / Svelte · Config files (JSON, YAML, TOML, Markdown) · Shell scripts

License

MIT © Aravind Chowdary Kamani