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.

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

Note

Performance is better when installing directly with Python (pipx or pip)

The binary installation might take a second or two longer to start up (not a huge deal — just something to note)

Usage

Run gptree in your project directory:

gptree

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

Options

Flag	Description
--interactive, -i	Enable interactive file selection
--copy, -c	Copy result directly to clipboard
--include-file-types	Comma-separated list of file types to include (e.g., .py,.js or py,js). Use * for all types
--exclude-file-types	Comma-separated list of file types to exclude (e.g., .log,.tmp or log,tmp)
--output-file	Specify the name of the output file
--output-file-locally	Save the output file in the current working directory
--no-config, -nc	Disable creation or use of configuration files
--ignore-gitignore	Ignore .gitignore patterns
--disable-safe-mode, -dsm	Disable safe mode checks for file count or size
--previous, -p	Use the previously saved file selection
--save, -s	Save the selected files to the configuration
--version	Display the current version of GPTree
path	(Optional) Root directory of your project. Defaults to .

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: 1
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
storeFilesChosen: true

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: 1
useGitIgnore: false
includeFileTypes: *  # Include all file types
excludeFileTypes: .test  # Exclude test files
outputFile: gptree_output.txt
outputFileLocally: false
copyToClipboard: true
safeMode: false
storeFilesChosen: false

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:

Key	Action
↑/↓	Navigate the file list
SPACE	Toggle selection of the current file
a	Select or deselect all files
ENTER	Confirm the selection and proceed
ESC	Quit the process immediately

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).