A versatile command-line tool for capturing and packaging project context, designed for developers, teams, and AI assistants.

Providing comprehensive project context to Large Language Models (LLMs), new team members, or for documentation can be a tedious process of copying and pasting files. recap automates this by intelligently traversing your project directory, filtering files, and consolidating their structure and content into a single, clean text output.

It's a powerful utility for anyone who needs to quickly package a project's source code for review, analysis, or as context for generative AI.

• Intelligent Filtering: Use powerful regular expressions (REGEX) to include or exclude specific files and directories.
• Git Integration: Automatically respects your .gitignore files to exclude irrelevant content, ensuring a clean output (--git).
• Precise Content Control: Decide exactly which files should have their content displayed (--include-content) and which should only be listed by path.
• Header Stripping: Automatically remove boilerplate like license headers or comment blocks from file content using regex, on a global (--strip) or per-file-type basis (--strip-scope).
• Content Compaction: Optionally removes comments and redundant whitespace from file content to create a denser, token‑efficient output for LLMs (--compact). Language‑aware behavior:
  • C/C++/Java/JS/TS/Go: removes // and /* ... */ comments; trims redundant spaces.
  • CSS: removes /* ... */ comments; trims redundant spaces.
  • Python/Shell/Ruby/Perl: removes # comments; preserves strings.
  • JSON: minifies by removing insignificant whitespace outside strings.
• Versatile Output Modes:
  • Print to stdout to pipe into other commands.
  • Save to a named file (--output).
  • Save to a timestamped file (--output-dir).
  • Copy directly to the system clipboard (--clipboard).
  • Upload to a private GitHub Gist in one command (--paste).
• Cross-Platform: Works on Linux, macOS, and Windows.

You need make and a C compiler, plus the development headers for the following libraries:

• pcre2 (for regular expressions)
• libcurl (for Gist uploads)
• jansson (for JSON parsing for Gist uploads)

On Debian / Ubuntu:

sudo apt-get install build-essential libpcre2-dev libcurl4-openssl-dev libjansson-dev

On macOS (using Homebrew):

brew install pcre2 curl jansson

For the clipboard feature (-c, --clipboard), recap relies on standard system utilities.

• Linux: xclip (for X11), xsel (alternative X11 tool), or wl-clipboard (for Wayland).

  # For X11-based systems
  sudo apt-get install xclip
  # Alternative X11 clipboard helper
  sudo apt-get install xsel
  # For Wayland-based systems
  sudo apt-get install wl-clipboard

• macOS / Windows: The necessary utilities (pbcopy and clip.exe) are pre-installed.

1. Clone the repository:

   git clone https://github.com/trethore/RECAP.git
   cd RECAP

2. Compile the project:

   make

   This will create the recap executable in the current directory. You can move this executable to a directory in your system's PATH (e.g., /usr/local/bin) for global access.

# Process src and docs, showing content for c, h, and md files
recap src docs --include-content '\.(c|h|md)$'

# Use gitignore rules but also explicitly exclude any 'test' directories
recap --git --exclude '/test/'

You can optionally point --git at a specific ignore file: recap --git .myignore.

This is perfect for quickly providing context to an AI.

# Find all Python files, respect .gitignore, and copy the result
recap --git --include-content '\.py$' --clipboard

A powerful one-liner to package and share code.

# 1. Target only .js files.
# 2. For those files, find and strip a leading JSDoc block.
# 3. Upload the final result to a private Gist (requires a token).
# Note: `--paste` without a KEY reads the `GITHUB_API_KEY` environment variable.
# Also: uploading requires writing to a file (i.e., not using stdout). Use `-o` or `-O` when uploading.
recap -I '\.js$' -S '\.js$' '^\s*/\*\*.*?\*/\s*' --paste

# Minify JSON and compact common source files, respecting .gitignore
recap --git --compact -I '\.(c|h|cpp|hpp|js|ts|go|json)$'

# Remove all recap-output-*.txt files from the current directory
# Note: this command is interactive and will prompt for confirmation.
# To script it, you can pipe a 'y' response: `printf "y\n" | recap --clear`
recap --clear

• Command: make test — Build and run the integration test suite.
• Alternative: bash test/run-integration-tests.sh — Run the test runner directly.

Notes:

• Build step: The test target will build the recap binary if it's missing; ensure the development headers for pcre2, libcurl, and jansson are installed.
• Environment: The test runner copies test/ into a temporary workspace and executes the repository recap binary. Set the RECAP_BIN environment variable to override the binary path if needed.

• Command: make bench — Build (if needed) and run the benchmark harness.
• Alternative: bash test/run-benchmarks.sh — Run the harness directly.

The benchmark runner executes recap test repeatedly in a temporary workspace and reports Criterion-style statistics (min/avg/max, median, and standard deviation). Use --runs N to control how many iterations are performed and --show-runs to print the duration of each individual run.

Examples:

# Default 100-run benchmark
make bench

# Twenty runs with per-run timings
bash test/run-benchmarks.sh --runs 20 --show-runs

• Gist uploads: private Gists via --paste use GITHUB_API_KEY by default; you can also pass a token directly: --paste <KEY>.
• File size caps: individual file content blocks are limited to 10 MB; files larger than this are not inlined in the output. Gist uploads also enforce a 10 MB limit.
• Output format: when only listing paths (e.g., using -i without -I), results are one path per line with no separators; when showing file contents via --include-content, --- lines separate content blocks and mark the boundary before any following path-only listings.

Contributions are welcome and greatly appreciated! Whether it's reporting a bug, proposing a new feature, or submitting a code change, your help is valuable.

The best way to report a bug or request a new feature is to open an issue on GitHub.

• For Bug Reports: Please include your operating system, the command you ran, the output you received, and what you expected to happen.
• For Feature Requests: Please provide a clear description of the feature you'd like to see and why it would be useful.

If you'd like to contribute code, please follow these steps:

1. Fork the repository on GitHub.
2. Create a new branch for your feature or bug fix:

   git checkout -b feature/my-new-feature

3. Make your changes. Please try to follow the existing coding style to maintain consistency.
4. Test your changes to ensure they work as expected and don't introduce new issues.
5. Commit your changes with a clear and descriptive commit message:

   git commit -m "feat: Add support for XYZ"

6. Push your branch to your fork:

   git push origin feature/my-new-feature

7. Open a Pull Request from your branch to the main branch of the original repository.

Thank you for your interest in improving recap