gptree 🌳

A CLI tool to provide LLM context for coding projects by combining project files into a single text file with a directory tree structure.

What is gptree?

When working with Large Language Models (LLMs) to continue or debug your coding projects, providing the right context is key. gptree simplifies this by:

1. Generating a clear directory tree structure of your project.
2. Combining the contents of relevant files into a single output text file.
3. Allowing you to select files interactively to fine-tune which files are included.

The resulting file can easily be copied and pasted into LLM prompts to provide the model with the necessary context to assist you effectively.

Features

• 🗂 Tree Structure: Includes a visual directory tree of your project.
• ✅ Smart File Selection: Automatically excludes ignored files using .gitignore and common directories like .git, __pycache__, and .vscode.
• 🎛 Interactive Mode: Select or deselect files interactively using arrow keys, with the ability to quit immediately by pressing ESC.
• 🌍 Global Config Support: Define default settings in a ~/.gptreerc file.
• 🔧 Directory-Specific Config: Customize behavior for each project via a .gptree_config file.
• 🎛 CLI Overrides: Fine-tune settings directly in the CLI for maximum control.
• 📜 Safe Mode: Prevent overly large files from being combined by limiting file count and total size.
• 📋 Clipboard Support: Automatically copy output to clipboard if desired.
• 🛠 Custom Configuration Management: Define configurations that are auto-detected per project or globally.

🆕 GPTree GUI - Now Available! 🎉

Experience gptree with a beautiful and efficient graphical interface!

• Lightweight & Fast: Built with Rust for optimal performance.
• Cross-Platform: Available on macOS, Windows, and Linux
• Learn More & Download: Visit gptree.dev
• Open Source: Check out the code on GitHub

Installation

Install via pipx 📦 (Recommended)

pipx install gptree-cli

How to setup pipx

Install via Homebrew 🍺

brew tap travisvn/tap
brew install gptree

Homebrew will attempt to install gptree using pip3 and will fall back to binary installation otherwise

Install via pip 🐍

Alternatively, install gptree (gptree-cli) directly via pip:

pip install gptree-cli

Usage

Run gptree in your project directory:

gptree

Or run it anywhere and define the relative path to your project

Options

Examples

Interactive file selection with custom file types:

gptree --interactive --include-file-types '.py,.js'

Save current selection to config:

gptree --interactive --save

Re-use previously saved file selections and copy to clipboard:

gptree --previous --copy

Configuration

Global Config (~/.gptreerc)

Define your global defaults in ~/.gptreerc to avoid repetitive setup across projects. Example:

# ~/.gptreerc
version: 2
useGitIgnore: true
includeFileTypes: .py,.js # Include only Python and JavaScript files
excludeFileTypes: .log,.tmp # Exclude log and temporary files
outputFile: gptree_output.txt
outputFileLocally: true
copyToClipboard: false
safeMode: true
lineNumbers: false
storeFilesChosen: true
showIgnoredInTree: false
showDefaultIgnoredInTree: false

This file is automatically created with default settings if it doesn't exist.

Directory Config (.gptree_config)

Customize settings for a specific project by adding a .gptree_config file to your project root. Example:

# .gptree_config
version: 2
useGitIgnore: false
includeFileTypes: *  # Include all file types
excludeFileTypes: .test  # Exclude test files
outputFile: gptree_output.txt
outputFileLocally: false
copyToClipboard: true
safeMode: false
lineNumbers: false
storeFilesChosen: false
showIgnoredInTree: false
showDefaultIgnoredInTree: true  # Show default ignored files while still respecting gitignore

Configuration Precedence

Settings are applied in the following order (highest to lowest precedence):

1. CLI Arguments: Always override other settings.
2. Global Config: User-defined defaults in ~/.gptreerc.
3. Directory Config: Project-specific settings in .gptree_config.
4. Programmed Defaults: Built-in defaults used if no other settings are provided.

Safe Mode

To prevent overly large files from being combined, Safe Mode restricts:

• The total number of files (default: 30).
• The combined file size (default: ~25k tokens, ~100,000 bytes).

Override Safe Mode with --disable-safe-mode.

Interactive Mode

In interactive mode, use the following controls:

Contributing

Contributions are welcome! Please fork the repository and create a pull request for any improvements.

License

This project is licensed under GNU General Public License v3.0 (GPL-3.0).