What is code-to-prompt?

A Node.js command-line utility to recursively gather files from specified paths, format their content, and output everything suitable for pasting into Large Language Model (LLM) prompts. Inspired by Simon Willison's Python-based files-to-prompt utility, but implemented in a Node.js/TypeScript environment.

Features

Recursive Scanning

Recursively scan directories and gather files based on your criteria.

Respect .gitignore

Automatically respects .gitignore patterns to exclude irrelevant files.

Filtering Options

Filter by extension, include hidden files, and use custom ignore patterns.

Multiple Output Formats

Output in plain text, Markdown with fenced code blocks, or Claude-XML format.

File Tree Overview

Optionally generate a file tree structure to provide context for your code.

Line Numbers

Optionally add line numbers to make referencing specific parts of code easier.

Default Configuration

Set persistent default options using a config.json file. Create a default config easily with the init command.

Installation

Install code-to-prompt globally:

npm install -g code-to-prompt

Basic Usage

code-to-prompt [command] [options] [paths...]

Commands

In addition to processing paths, code-to-prompt supports the following command:

  • init: Creates a default configuration file (config.json) in the standard XDG config location (e.g., ~/.config/code-to-prompt/config.json) if one doesn't already exist. This allows you to set persistent default options.

Options Table

Option Alias Description Default
paths... Input file or directory paths (reads from stdin if no paths given).
--config Path to configuration file. Defaults to ~/.config/code-to-prompt/config.json (or XDG equivalent). (See description)
--extension -e File extension(s) to include (e.g., -e .ts -e .js). Can be repeated. (Include all)
--include-hidden Include hidden files and folders (those starting with .). false
--include-binary Include binary files (images, executables, etc.). false
--ignore-files-only Makes --ignore patterns only apply to files, not directories. false
--ignore-gitignore Ignore .gitignore files and include all files found. false
--ignore Glob pattern(s) to ignore using minimatch. Can be repeated (e.g., --ignore "*.log"). []
--output -o Output to a specified file instead of standard output. stdout
--cxml -c Output in Claude-friendly XML format. Mutually exclusive with -m. false
--markdown -m Output in Markdown format with fenced code blocks. Mutually exclusive with -c. false
--line-numbers -n Add line numbers to the content of each file in the output. false
--clipboard -C Copy the output directly to the system clipboard. Conflicts with -o. false
--null -0 Use NUL (\0) character as separator when reading paths from stdin. false
--tree Prepend a file tree structure overview to the output. false
--verbose -V Enable verbose debug logging to stderr. false
--help -h Show help message.
--version -v Show version number.

Detailed Examples

Initialize the default configuration file

code-to-prompt init

Creates the default config.json in the XDG config directory if it doesn't exist.

1. Process all non-ignored files in the current directory

code-to-prompt .

2. Process only TypeScript and JavaScript files in the src directory

code-to-prompt -e .ts -e .js ./src

3. Process files in src and tests, ignoring .log files and node_modules, outputting as Markdown

# Assumes .gitignore includes node_modules/ and *.log
code-to-prompt ./src ./tests --markdown -o prompt.md

4. Explicitly ignore build artifacts and test snapshots

code-to-prompt . --ignore "dist/**" --ignore "**/*.snap"

5. Process specific files and add line numbers

code-to-prompt src/index.ts src/lib/printers.ts --line-numbers

6. Generate a file tree overview for the src directory

code-to-prompt --tree ./src

7. Output in Claude XML format, including hidden files

code-to-prompt --cxml --include-hidden .

8. Combine find with code-to-prompt using null separator

find ./src -type f \( -name "*.ts" -o -name "*.json" \) -print0 | code-to-prompt -0 --markdown

9. Include binary files in the output

code-to-prompt --include-binary . -o output-with-binaries.txt

10. Multi-line configuration for complex commands

code-to-prompt \
  --markdown \
  --line-numbers \
  --ignore "*.snap" \
  --ignore "dist/**" \
  -o specific-prompt.md \
  src/index.ts \
  src/lib/printers.ts \
  src/lib/fileTree.ts \
  tests/e2e/cli.test.ts \
  README.md \
  LICENSE \
  ./src/types \
  ./assets

11. Process files and copy the result directly to the clipboard

code-to-prompt ./src -e .ts --markdown -C

This processes TypeScript files in `src`, formats the output as Markdown, and copies the entire result to the system clipboard instead of printing it to standard output or a file.

Configuration File (config.json)

Customize default behavior using a config.json file in the standard XDG config directory (e.g., ~/.config/code-to-prompt/config.json on Linux/macOS, or respecting $XDG_CONFIG_HOME).

Create a default file using the init command:

code-to-prompt init

Options are prioritized: Command-line flags > config.json values > Built-in defaults.

If the default configuration file is found and loaded, an informational message will be printed to stderr, like:
ℹ️ Loaded configuration from default path: /path/to/.config/code-to-prompt/config.json

Example Default config.json:

{
  "ignore": [
    "**/node_modules/**",
    "*.log",
    "package-lock.json",
    "coverage/**",
    ".git/**",
    ".DS_Store"
  ],
  "include-hidden": false,
  "line-numbers": false,
  "markdown": false,
  "cxml": false,
  "include-binary": false,
  "tree": false
}

Edit this file to change your default settings (e.g., set "markdown": true).

You can also specify a custom configuration file path using the --config flag.

Contributing

Contributions are welcome! Follow these steps:

Check the GitHub README for more detailed contribution guidelines.