- PromptPrep
Hey there! PromptPrep is a handy command-line tool I built to help you bundle your code from multiple files into one neat, well-organized output file. It creates a visual map of your project structure and brings together all your selected files, making it perfect for:
-
Working with AI models: Need to give GPT-4 or other LLMs context about your codebase for help with debugging or generating new code? PromptPrep packages everything they need to understand your project.
-
Creating documentation snapshots: Capture your entire project's structure and code in one file for easy sharing or archiving.
-
Analyzing your project: Get useful stats about your code (like line counts and comment ratios) to better understand your codebase.
-
Code reviews: Share a consolidated view of specific parts of your project to make reviews more efficient.
The tool gives you full control over which files to include, how to process their content, and how you want the final output to look.
Here's what PromptPrep can do for you:
- Bundle Your Code: Combine multiple source files into one organized output file.
- Visualize Project Structure: See your directory structure in a clean ASCII tree format.
- Smart File Selection:
- Cherry-pick specific files or exclude directories you don't need
- Focus on just the file types that matter with extension filtering
- Skip those massive files that would bloat your output
- Automatically exclude common directories like
node_modulesand__pycache__
- Interactive Selection: Browse and pick files with a simple terminal interface - no more typing long paths!
- Content Processing:
- Summary Mode: Just want the function/class signatures and docstrings? No problem!
- Comment Control: Keep or strip comments from the output
- Line Numbers: Add them when they help with readability and references
- Multiple Output Formats:
plain: Clean text output (default and simplest)markdown: GitHub-friendly Markdown with code blockshtml: Complete webpage with basic stylinghighlighted: Syntax-highlighted code (needspygmentspackage)custom: Design your own output format with templates
- Codebase Analytics: Get stats about your files, lines of code, and comment ratios
- Token Counting: See how many tokens your code will use when sent to AI models like GPT-4
- Incremental Processing: Only process files that have changed since your last run
- Diff Generation: Compare versions to see what changed between runs
- Save Your Settings: Store your favorite command options for quick reuse
- Clipboard Integration: Send output directly to your clipboard, ready to paste
You'll need:
- Python 3.10 or higher
- pip (the Python package installer)
The easiest way to install promptprep is from PyPI using pip:
pip install promptprepThis will install the latest stable version of promptprep and its required dependencies.
You can install promptprep from conda-forge:
conda install -c conda-forge promptprepFor syntax highlighting features:
conda install -c conda-forge promptprep-highlightingFor all optional features:
conda install -c conda-forge promptprep-allIf you are on macOS, you can install promptprep using Homebrew:
- Tap the custom repository (only needs to be done once):
brew tap kartikmandar/promptprep- Install promptprep:
brew install promptprep-
Get the code:
git clone https://github.com/kartikmandar/promptprep cd promptprep -
Install it:
pip install . -
For developers: If you want to tinker with the code, use the editable install:
pip install -e .This way your changes take effect immediately without reinstalling.
promptprep has optional features that require additional dependencies:
-
Syntax Highlighting:
pip install promptprep[highlighting]
Or if installing from source:
pip install .[highlighting]
-
Development Tools:
pip install promptprep[dev]
Or if installing from source:
pip install .[dev]
-
Documentation Tools:
pip install promptprep[docs]
Or if installing from source:
pip install .[docs]
-
All Optional Dependencies:
pip install promptprep[all]
Or if installing from source:
pip install .[all]
It's super simple to get started:
promptprep [options]If you run it without options, it'll process all code files in your current directory and save them to full_code.txt.
Here are the options you'll probably use most often:
-d, --directory DIR: Which directory should I scan? (defaults to current)-o, --output-file FILE: Where should I save the output? (defaults tofull_code.txt)-c, --clipboard: Send straight to clipboard instead of creating a file-i, --include-files LIST: Only include these specific files (comma-separated)-e, --exclude-dirs LIST: Skip these directories (comma-separated, likenode_modules,venv)-x, --extensions LIST: Only include these file types (comma-separated, like.py,.js)--format FORMAT: Choose your output style (plain,markdown,html,highlighted,custom)--interactive: Launch the visual file picker in your terminal
Here are some real-world examples to get you going:
-
Basic use - current folder to output.txt:
promptprep -o output.txt
-
Process a specific project:
promptprep -d ./my_project -o project_code.md --format markdown
-
Get a high-level overview with stats:
promptprep -d ./src --summary-mode --metadata --no-include-comments -o summary.txt
-
Just Python and JavaScript files, skip build folders:
promptprep -d . -x ".py,.js" -e "dist,.cache" -o web_code.txt
-
Pick files interactively and copy to clipboard:
promptprep -d ./my_app --interactive -c
-
Create a pretty HTML report with syntax highlighting:
promptprep -d . --format highlighted -o report.html -
See what changed since last time:
# First run (or save previous state) promptprep -d . -o project_v1.txt # After making code changes... promptprep --diff project_v1.txt -o project_v2.txt
Here's the complete toolkit of options you can use with PromptPrep:
-d, --directory DIR: Where should I look for code? (default: your current directory)-o, --output-file FILE: What should I name the output file? (default:full_code.txt)-c, --clipboard: Skip the file and copy directly to your clipboard instead
-i, --include-files LIST: Only process these specific files (comma-separated relative paths)-e, --exclude-dirs LIST: Skip these directories (likevenv,node_modules) - overrides defaults-x, --extensions LIST: Only include these file types (like.py,.js) - overrides defaults-m, --max-file-size MB: Skip files larger than this size in MB (default: 100.0)--interactive: Launch the visual file picker to select what you want
--summary-mode: Just extract function/class signatures and docstrings - perfect for getting the big picture--include-comments: Keep comments in the output (this is the default)--no-include-comments: Strip out all comments (takes priority over--include-comments)--metadata: Add stats about your codebase at the beginning--count-tokens: Count how many tokens your code uses (needs--metadata)--token-model MODEL: Pick which tokenizer to use (default:cl100k_basefor GPT-4)
--format FORMAT: How should the output look? Options:plain,markdown,html,highlighted, orcustom--line-numbers: Add line numbers to make referencing code easier--template-file FILE: Your custom template file (required if using--format custom)
--incremental: Only process files that have changed since last run
This is the heart of PromptPrep: it gathers code from multiple files and combines them into one neat package. Think of it like stapling all your important papers together, but smarter - it adds headers and formats everything nicely.
Ever tried to explain your project structure to someone? The ASCII directory tree gives you a visual map showing folders and files, making it easy to understand how everything fits together. It looks something like this:
project/
├── src/
│ ├── main.py
│ └── utils.py
└── tests/
└── test_main.py
Typing long paths is no fun. The interactive Terminal User Interface lets you browse and select files visually:
- Use arrow keys to navigate folders
- Press Enter/Space to select or deselect files
- Press t to show/hide hidden files
- Press a to select everything in a directory
- Press s to save your selection and continue
- Press q to quit
Sometimes you just want the big picture. Summary mode gives you just function and class definitions along with their docstrings - perfect for understanding a codebase's structure without diving into implementation details.
The --diff option lets you compare different versions of your codebase. It highlights lines that were added, removed, or changed, making it easy to track what's new or different between versions.
- Metadata gives you useful stats about your code: how many files, total lines, code vs. comments ratio, etc.
- Token Counting estimates how many tokens your code will use when sent to AI models like GPT-4, helping you stay within context limits.
You can choose how your output looks with the --format option:
-
plain(Default): Simple text format with clear file headers. Clean, straightforward, and works everywhere. -
markdown: Perfect for GitHub or documentation sites. Your code gets proper syntax highlighting in Markdown code blocks (like ````python`), and metadata appears in a nice table. -
html: Creates a complete webpage with your code. The HTML file is self-contained with CSS styling, so you can open it directly in any browser. -
highlighted: The prettiest option! Adds full syntax highlighting with colors to make your code more readable. Needs the optionalpygmentspackage (pip install .[highlighting]). -
custom: Ultimate flexibility - design your own output format using a template file. See Custom Templates below.
promptprep --format markdown -o output.md
promptprep --format html -o output.html
promptprep --format highlighted -o output_highlighted.html
promptprep --format custom --template-file my_template.txt -o custom_output.txtDon't worry about file extensions - PromptPrep automatically adjusts them to match the format (e.g., .md for markdown, .html for HTML formats).
Want total control over how your output looks? The custom template feature has you covered!
It's easy to get started:
- Create a template file (like
my_template.txt) - Add placeholders (special tags) where you want different parts of your code to appear
- Run PromptPrep with:
promptprep -d . --format custom --template-file my_template.txt -o my_output.txt
Drop these special tags into your template file and PromptPrep will replace them with the actual content:
${TITLE}: The project title (e.g., "Code Aggregation - MyProject")${DIRECTORY_TREE}: Your ASCII directory structure visualization${METADATA}: Stats about your code (only if you use--metadata)${SKIPPED_FILES}: List of any files that were too large to include${FILES}: All your code files with their headers${FILE_HEADER:path/to/file.py}: Header for a specific file${FILE_CONTENT:path/to/file.py}: Content of a specific file
This lets you create highly customized reports with exactly the information you want in the order you want it.
Here's a simple template to get you started:
# Project Aggregation: ${TITLE}
## Directory Structure
${DIRECTORY_TREE}
## Code Files
### Main Application File
${FILE_HEADER:src/app.py}
${FILE_CONTENT:src/app.py}
### Utility Functions
${FILE_HEADER:src/utils.py}
${FILE_CONTENT:src/utils.py}
## Project Statistics
${METADATA}
## Skipped Files (Too Large)
${SKIPPED_FILES}
--- End of Report ---
Feel free to modify this to suit your specific needs!
Tired of typing the same options every time? Save your favorite settings for quick reuse!
Just add the --save-config flag to any command:
-
Save to the default location:
promptprep -d ./my_project --summary-mode --metadata --save-config
This stores your settings in
~/.promptprep/config.json -
Save to a custom file:
promptprep -d ./my_project --format markdown --save-config my_settings.json
When you use --save-config on its own, PromptPrep will save your settings and then exit.
Use the --load-config flag to apply saved settings. You can still add new options to override specific settings:
-
Load from the default location:
promptprep --load-config -o new_output.txt
This loads from
~/.promptprep/config.jsonbut uses a different output file -
Load from a custom file:
promptprep --load-config my_settings.json
PromptPrep stores configurations in ~/.promptprep/config.json unless you specify another path.
Comprehensive documentation is available at promptprep.readthedocs.io. The documentation includes:
- Quickstart Guide
- Detailed Usage Instructions
- Command Reference
- Output Formats
- API Reference
- Tips and Tricks
The project includes a comprehensive test suite using pytest.
-
Make sure you have installed the development dependencies.
-
Navigate to the project's root directory.
-
Run the tests:
pytest
I'd love your help making PromptPrep even better! Here's how you can contribute:
- Fork the repository on GitHub
- Clone your fork and create a new branch for your feature (
git checkout -b cool-new-feature) - Code your improvements or fixes
- Add tests to make sure your code works as expected
- Run tests to make sure everything passes (
pytest) - Format your code with Black (
black .) - Commit your changes with a descriptive message
- Push to your branch
- Create a Pull Request so I can review your changes
Your code should follow the project's style and include proper documentation and tests. If you're not sure where to start, check out the open issues!
For more detailed information on contributing, see the Contributing Guide.
PromptPrep is licensed under the MIT License, so you can freely use, modify, and distribute it. See the LICENSE file for the complete legal text.