supp

Structured code context for LLMs. Extracts files, diffs, symbols, and trees from your codebase and copies them to the clipboard — ready to paste into any chat.

Install

# From crates.io
cargo install supp

# Or via install script (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/AndrewPBerg/supp/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/AndrewPBerg/supp/main/install.ps1 -OutFile install.ps1
.\install.ps1
Remove-Item install.ps1

Binaries are available for Linux (x86_64, ARM64, musl), macOS (Intel, Apple Silicon), and Windows. See GitHub Releases for downloads.

Quick start

# Get context from files — copies to clipboard automatically
supp src/main.rs

# Multiple files and directories
supp src/ Cargo.toml

# See what changed on your branch
supp diff

# Show the project tree with git status
supp tree

# Search for a symbol by name
supp sym UserService

# Deep-dive a symbol — definition, call sites, dependencies
supp why handle_request

# Pick files interactively with fzf
supp pick

Add -n to any command to print output without copying to clipboard.

Commands

NOTE: supp pick requires fzf to be installed and available on your PATH. Install it via your package manager (e.g. brew install fzf, winget install fzf, pacman -S fzf, xbps-install fzf) before using this command. | supp completions <shell> | Generate shell completions (bash, zsh, fish) |

Useful flags

Docs

Detailed usage for each command:

• Context — bundling files into LLM context
• Diff — git diffs and comparison modes
• Sym — finding symbols by name
• Why — deep-diving a symbol
• Tree — directory tree
• Examples — workflows and multi-language demos
• Config — configuration
• Performance — performance modes for large codebases

Claude Code integration

supp ships with Claude Code skills that let Claude use supp directly. Once supp is installed, these slash commands are available in any Claude Code session inside a project:

Suggested prompts

These work well as starting points for Claude Code conversations:

# Orient yourself in an unfamiliar project
"Use /tree and /ctx --map . to map out this codebase, then summarize the architecture."

# Understand a specific function before changing it
"Use /why handle_request to explain how it works, then suggest how to add rate limiting."

# Review your own changes
"Use /diff to review my changes and suggest improvements."

# Explore a domain concept across languages
"Use /sym User to find all User-related types, then /why the most important one."

Performance modes

On large codebases, supp can use significant CPU and memory. Set a global mode with supp perf or override per-command with -p:

supp perf lite                      # set globally (persisted)
supp perf                           # check current mode
supp -p full sym handler            # override for one command

See Performance Modes for technical details on what each mode tunes.

Token estimation

supp shows an approximate token count for all output (≈ ~N tokens). This uses a fast heuristic — bytes / 3.5 — rather than running a full BPE tokenizer. For mixed code, this is typically accurate within ~10% of the true cl100k count. The tradeoff is speed: estimation is instant, while tokenization would add hundreds of milliseconds.

Symbol cache

supp sym, supp why, and supp <paths> build a symbol index using tree-sitter. The index is cached per project at .git/supp/sym-cache (or /tmp/supp-sym-<hash> for non-git directories).

On subsequent runs, supp checks file mtimes and sizes — only changed files are re-parsed. If nothing changed, the cached index is used as-is.

To force a full rebuild, delete the cache:

supp clean-cache          # current directory
supp clean-cache ~/myproj # specific project

The cache is scoped to each project root (the directory you pass to supp). Different projects maintain independent caches.

Shell completions

# Bash
echo 'eval "$(supp completions bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(supp completions zsh)"' >> ~/.zshrc

# Fish
supp completions fish > ~/.config/fish/completions/supp.fish

Managing supp

supp version    # check version (auto-checks for updates)
supp update     # update to latest release
supp uninstall  # remove from system