peek

A powerful CLI tool to intelligently grab, format, and copy file and folder contents, specially designed for providing context to Large Language Models (LLMs).

The Problem

When working with LLMs like GPT-4, Claude, or Llama, you often need to provide a large amount of context from your codebase. Manually copying and pasting file contents is tedious, error-prone, and inefficient. You have to worry about:

• Ignoring irrelevant files like node_modules or .git.
• Picking the right files and folders.
• Formatting the output cleanly with file paths.
• Avoiding huge binary files.

peek solves this by automating the entire process.

Features

• Interactive Mode: A user-friendly, interactive file tree to visually select the exact files and folders you need.
• Powerful Filtering: Use glob patterns to precisely include or exclude files and directories.
• Clipboard Integration: Copy the entire formatted output directly to your clipboard with a single flag (-c).
• Structure and Content: Generates a clean project structure tree and concatenates file contents, ready to be pasted into any LLM prompt.
• Smart Defaults: Automatically ignores common nuisance directories like node_modules and .git.
• Zero Dependencies: Fully self-contained. No need to install external command-line tools.
• Cross-Platform: Works on macOS, Windows, and Linux.

Installation

You need Node.js (version 20 or higher) installed on your system.

Install peek globally using npm to make it available as a command-line utility everywhere on your system.

npm install -g peek-llm-context

Usage

The basic command structure is:

peek [options] [folder_path]

If folder_path is omitted, it defaults to the current directory (.).

Options

| Option | Alias | Description | Default | |------------------------|-------|---------------------------------------------------------------------------------------|---------------------------| | --include=<patterns> | | Comma-separated glob patterns for files/folders to include. | * (all files) | | --exclude=<patterns> | | Comma-separated glob patterns for files/folders to exclude. | node_modules/**,.git/** | | --interactive | -i | Show an interactive tree menu to select files and folders. | false | | --copy | -c | Copy the final output to the system clipboard instead of printing it to the console. | false | | --verbose | -v | Output detailed logging for debugging purposes. | false | | --version | | Show the version of the utility. | | | --help | -h | Show the help message. | |

Examples

1. Interactive Selection (Most Common Use Case)

Navigate to your project's root directory and run peek with the interactive and copy flags. This is the easiest way to get started.

# Go to your project folder
cd my-awesome-project

# Run interactively and copy the result to clipboard
peek -i -c

This will open a file tree where you can:

• Use Arrow Keys to navigate.
• Press Space to select/deselect a file or an entire directory.
• Press Enter to confirm your selection.

The formatted output will be instantly available on your clipboard.

2. Non-Interactive Filtering

Grab all TypeScript files from the src directory, excluding test and spec files, and print the output to the terminal.

peek --include="src/**/*.ts" --exclude="**/*.test.ts,**/*.spec.ts"

3. Combining Filters and Copying

Get all files from a components directory and all markdown files, then copy the result to the clipboard.

peek --include="components/**,*.md" --copy ./src

This command targets the ./src directory.

4. Verbose Mode for Debugging

If you're unsure why certain files are being included or excluded, use the --verbose (-v) flag to see what peek is doing under the hood.

peek --include="*.js" -v

License

This project is licensed under the MIT License.