code-to-llm

code-to-llm is a zero-dependency Node.js CLI that scans your project, filters noisy files, and generates a clean code report optimized for LLMs, GPT, Claude, and Copilot.

English (Primary)

Why this package exists

When you paste an entire repository into an AI tool, you waste context window on generated files, binaries, huge assets, and irrelevant folders.

code-to-llm creates a compact and structured prompt-ready report with:

• Directory tree
• Selected source files
• Optional comment stripping
• Optional stats (files, lines, size, by extension)

This improves answer quality and reduces token waste.

Features

• Interactive TUI (terminal UI) with project browser
• Auto project detection (Node, Python, Go, Rust, Web)
• Output formats: txt, md, json
• Tree-only export mode
• Watch mode (--watch) to regenerate on changes
• Config file support (--config, --save-config)
• Ignore folders + extension filters
• Zero dependencies (single executable JS file)

Installation

Use without install:

npx code-to-llm --dir . --preset node --format md --stats

Global install:

npm i -g code-to-llm
code-to-llm --dir . --preset all --format md

CLI usage

code-to-llm [flags]

Flags reference

| Flag | Description | Example | | --------------------------------------- | ---------------------------------- | ------------------------------ | | -h, --help | Show help | code-to-llm --help | | -v, --version | Show version | code-to-llm --version | | -l, --lang <pt\|en> | Language | --lang en | | -d, --dir <path> | Base directory to scan | --dir . | | -o, --output <file> | Output file path | --output ./report/project.md | | -f, --format <txt\|md\|json> | Output format | --format md | | -t, --tree-only | Export directory tree only | --tree-only | | -g, --gitignore | Add output pattern to .gitignore | --gitignore | | -i, --ignore <a,b,c> | Extra folders to ignore | --ignore .history,tmp | | -e, --ext <.a,.b> | Allowed extensions | --ext .js,.ts,.md | | --preset <node\|py\|go\|rs\|web\|all> | Extension preset | --preset node | | -s, --max-size <kb> | Max file size in KB | --max-size 300 | | --depth <n> | Max scan depth | --depth 5 | | --no-strip-comments | Keep comments | --no-strip-comments | | --stats | Include stats in output | --stats | | --watch | Regenerate report on file changes | --watch | | --config <file> | Load config from JSON | --config .reportrc.json | | --save-config <file> | Save current config to JSON | --save-config .reportrc.json |

Presets

• node: .js .ts .jsx .tsx .mjs .cjs .json
• py: .py .pyi .toml .cfg .ini
• go: .go .mod .sum
• rs: .rs .toml
• web: .html .css .scss .sass .less .js .ts .jsx .tsx .vue .svelte
• all: common extensions across multiple stacks

Practical examples

Generate markdown report for a Node project:

npx code-to-llm --dir . --preset node --format md --stats

Generate JSON report for automation pipelines:

npx code-to-llm --dir . --preset all --format json --output ./report/context.json

Tree-only snapshot for architecture overviews:

npx code-to-llm --dir . --tree-only --format txt

Save reusable config:

npx code-to-llm --dir . --preset node --stats --format md --save-config .reportrc.json
npx code-to-llm --config .reportrc.json

Output formats

• txt: plain text tree + source sections
• md: markdown report, ideal for ChatGPT/Copilot/Claude prompts
• json: structured output for scripts, pipelines, and post-processing

JSON output shape (simplified)

{
  "generator": "code-to-llm",
  "version": "3.0.0",
  "generatedAt": "2026-01-01T00:00:00.000Z",
  "base": "/path/to/project",
  "extensions": [".js", ".ts"],
  "tree": "...",
  "files": [
    {
      "path": "/path/to/file.ts",
      "ext": "ts",
      "content": "...",
      "lines": 120,
      "bytes": 3456
    }
  ]
}

How to customize the ASCII art banner

Open code-to-llm.js and edit:

• BANNER_LINES (full banner on wide terminals)
• BANNER_SMALL (compact banner on narrow terminals)
• renderBanner() (colors, spacing, fallback logic)

Tip: if your terminal width is less than ~84 columns, the script uses BANNER_SMALL.

Troubleshooting

• No files collected: check --ext, --preset, and ignored folders.
• Output too small: disable comment stripping with --no-strip-comments.
• Missing folders: verify defaults in ignored dirs and your --ignore list.
• Watch mode not working: recursive file watching may depend on OS/filesystem support.

Português (PT-BR)

O que é

code-to-llm é uma CLI em Node.js (sem dependências) para gerar relatórios de código prontos para uso com IA/LLMs, como GPT, Claude e Copilot.

Ela escaneia seu projeto, ignora ruído, e exporta uma visão estruturada com árvore + código.

Instalação rápida

Sem instalar:

npx code-to-llm --dir . --preset node --format md --stats

Instalação global:

npm i -g code-to-llm
code-to-llm --dir . --preset all --format md

Casos de uso

• Revisão de código
• Debug contextual
• Refatoração guiada por IA
• Geração de documentação
• Entendimento de projeto legado

Como mudar a ASCII art

No arquivo code-to-llm.js, altere:

• BANNER_LINES: arte grande
• BANNER_SMALL: arte compacta
• renderBanner(): regra de exibição e estilo

Apoie o projeto

Se a ferramenta te ajudou:

☕ Buy Me a Coffee

Licença

BSD 3-Clause License © Fausto Rodrigo Toloi