code-to-llm

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.

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.

Ships in 6 languages: (pt-BR, en-US, es, fr, de, it).

---

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

The TUI is file-first, not form-first. The left sidebar is your project tree; the right panel is a live preview of what the report will contain.

• The preset seeds the view: junk (node_modules, .git, lockfiles, binaries, OS cruft) is already marked ✗ excluded the moment you open it. Nothing is hidden silently — you see exactly what's out.
• Everything readable starts ✓ included. You narrow it down.
• ↑/↓ move through the tree · → opens a folder into the detail panel · Space toggles include/exclude · A mark all · N mark none · I invert · ←/Backspace go up · Tab switches Files / Settings / Preview · Enter on a file toggles it · q quits.
• The Settings tab holds report type, preset, format, language and prompt.
• The Preview tab (and the right panel) shows included/ignored counts, lines, size and a per-model token estimate that updates as you mark files.
• A live help bar at the bottom shows the shortcuts for the current view (tree / folder detail / settings), and a rotating tip line shares a context trick every couple of seconds.

The interface language is auto-detected from your system: it reads CODE_TO_LLM_LANG, then LANGUAGE, LANG and LC_ALL (Linux/WSL/macOS), and on Windows falls back to the OS locale — so on a Portuguese WSL shell it opens in pt-BR without any flag. Override any time with --lang.

The "looking" half of the loop is real: the preview is recomputed from your selection, so you reconstruct the output before generating — no blind writes.

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
-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, buy me a coffee.