code-to-llm

The best possible context for any LLM — GPT, Claude, Gemini, DeepSeek, Qwen. Smart file selection, honest token counts, and an explicit Execution Report.

🇧🇷 🇺🇸 🇪🇸 🇫🇷 🇩🇪 🇮🇹 🇨🇳 — 7 languages out of the box

code-to-llm scans your codebase and produces one LLM-ready context document. It ranks files by architectural importance (Smart Context), estimates token cost per model family, and reports exactly what it did through an Execution Report — never a silent ok.

Why it's different

An LLM reading a codebase has no eyes. The report it receives is its reality. So the output is a feedback channel, not a log:

• Smart Context puts the core first. Entrypoints, configs, and the most-imported modules lead, so the model reconstructs the architecture top-down.
• Token counts don't lie. One tokenizer is real — o200k_base, exact for GPT-4o/5. Every other family is labelled an estimate (±10%). No fake precision.
• The Execution Report never hides. requested vs produced, plus warnings[]. Ask for preset py in a Node project and it tells you. Success is never silent.

Install & run

# run directly, no install
npx code-to-llm

# or install globally
npm i -g code-to-llm
code-to-llm --help

Run it inside any project:

# interactive TUI (when the terminal is interactive) — navigate your file tree,
# see what's excluded (✗) vs included (✓), open folders with →, mark files with
# space, and watch the live preview update. Tabs: Files · Settings · Preview.
code-to-llm

# force the TUI anywhere, or skip it for a headless run
code-to-llm --ui
code-to-llm --no-ui

# smart context (default), auto-detected project type, markdown output
code-to-llm --no-ui

# full export, Python preset, Portuguese interface
code-to-llm ./my-project --full --preset py --lang pt-BR

# keep the 30 most important files, strip comments to save tokens
code-to-llm --smart --limit 30 --strip -o context.md

The TUI launches automatically when the terminal is interactive and you pass no generation flag. Any generation flag (--smart, --full, --preset, …) or a non-TTY stdout (pipes, CI) runs headlessly.

Interactive 3-Column Dashboard & Quick Panel ([H])

The TUI features a 3-column IDE dashboard:

1. File Tree (Left Column): Navigate your project hierarchy, inspect importance gutters (█ ▋ ▎), and toggle individual files (Space, A, N, I).
2. Live Preview (Middle Column): Real-time report estimation showing included files, lines, bytes, and exact token counts per model family (GPT, Claude, Gemini).
3. Quick Options Panel (Right Column - Hotkey [H]):
   • Smart Presets: Switch instantly between auto, node, py, go, rs, web, php, java, all.
   • Export Format: Toggle between markdown, txt, and json.
   • Report Mode: Switch between smart context and full export.
   • ⚡ Save Tokens (Beta): Toggle stripping comments and docstrings in real time to minimize token cost.
   • Exclude Extensions Filter: Lists all extensions detected in your workspace with file counts (e.g., .ts, .json, .md, .css). Toggle exclusion of any extension globally with [Space] (e.g. instantly remove all .json or .md files when exporting in Node mode).

Press [H] anytime to switch focus into the Quick Options Panel ([H] lights up in yellow); press [H] again or Esc to return focus to the File Tree.

Auto Language Detection (Linux & WSL Ready)

The interface language is auto-detected across Linux (including WSL), macOS, and Windows. It checks:

1. CODE_TO_LLM_LANG env var or --lang flag
2. LANGUAGE (colon-separated lists), LANG, LC_ALL, LC_MESSAGES
3. System locale configs (/etc/default/locale, /etc/locale.conf, /etc/environment)
4. System TimeZone matching (e.g. America/Sao_Paulo → pt-BR on WSL when POSIX locale envs are empty)

Override anytime with --lang pt-BR, --lang en-US, --lang zh-CN, etc.

Options

| Flag | Description | |---|---| | --smart | Smart Context: prioritize architecturally important files (default) | | --full | Include every matching file | | --preset <name> | node|py|go|rs|web|php|java|all|auto (default: auto) | | --format <fmt> | markdown|txt|json (default: markdown) | | --limit <n> | Smart mode: keep only the top-N files by importance | | --max-size <kb> | Skip files larger than N KB (default: 200) | | --depth <n> | Max directory depth | | --strip | Strip comments to save tokens | | --no-prompt | Omit the generated prompt preamble | | --ui | Force the interactive TUI | | --no-ui | Skip the TUI, generate headlessly | | --lang <locale> | Interface language: pt-BR|en-US|es|fr|de|it|zh-CN | | -o, --output <file> | Output file (default: auto-named in ./reports/) | | -h, --help | Show help |

The interface language also resolves from CODE_TO_LLM_LANG, then LANG/LC_ALL.

What you get

Every report contains four sections:

1. Execution Report — status, detected preset, files included/skipped, total lines, and a per-model token table (GPT exact; others estimated).
2. Suggested prompt — an instruction preamble tuned to the report type: read everything first, reconstruct the architecture, then map dependencies.
3. Project structure — a directory tree of the selected files.
4. Files — each file in a fenced block with language hints.

How Smart Context ranks

Pure heuristics — fast and deterministic, no AI in the loop:

• Import in-degree — files imported by many others rank as core. Resolves TS/ESM .js→.ts specifiers, require, and Python from x import.
• Entrypoint bonus — index, main, app, server, cli, __main__, …
• Config/manifest bonus — package.json, tsconfig.json, pyproject.toml, go.mod, Dockerfiles, …
• Export density — files exposing a public surface rank higher.
• Shallowness — files near the root rank higher.
• Penalties — test/spec/story and generated/.d.ts/minified files rank lower.

Every ranked file carries reasons[] that explain its position.

Development

npm install
npm run dev -- --help     # run from source (tsx)
npm run typecheck         # tsc --noEmit
npm test                  # node:test suite
npm run build             # bundle to dist/ (tsup)

See docs/ARCHITECTURE.md and docs/I18N.md for architecture and contribution details. The pre-4.0 single-file implementation lives in legacy/.

License

BSD-3-Clause © Fausto Rodrigo Toloi

If this saves you time, consider supporting it:

Made with ☕ and ❤️ by Fausto Rodrigo Toloi