# TreeClip 🌳✨
*A delightfully fast CLI tool that bundles your code into a single, AI-friendly format*
---
## What's This All About? (◕‿◕✿)
Ever tried explaining your entire codebase to an AI assistant, only to spend 20 minutes copy-pasting files? Yeah, me
too. That's why TreeClip exists!
TreeClip traverses your project directory, gathers all your code files, and bundles them into one neat package with
proper headers showing where each piece came from. It's like creating a "highlight reel" of your project that AI models
can actually digest in one go.
**Think of it as:** *Your project, but as a single, well-organized document that preserves all the context.*
---
## Why I Built This 🛠️
Honestly? I was learning Rust and needed a practical project. But also, I was tired of the tedious workflow of sharing
code with AI assistants:
1. Copy file contents
2. Paste into chat
3. Explain the file structure
4. Repeat 47 times
5. Lose track of which files you've shared
6. Question your life choices
TreeClip turns that into: `treeclip run --clipboard` → done. One command, everything's ready to paste.
Plus, I wanted to practice Rust's error handling, understand the module system, work with the filesystem APIs, and build
something actually useful. Learning by building real tools just hits different, you know?
---
## Installation 🚀
### From Crates.io (Recommended)
You can install `treeclip` directly from crates.io using Cargo:
```bash
cargo install treeclip
```
This will install the binary on your system, making it available from anywhere!
### From Source
If you'd rather build it yourself from the source code:
```bash
git clone https://github.com/seyedali-dev/treeclip.v2.git
cd treeclip.v2
cargo build --release
```
The binary will be located at `target/release/treeclip`. You can also run `cargo install --path .` to install it locally from the repository folder.
---
## How to Use It ✨
The most common use case is bundling the current directory and copying it to your clipboard. It's as simple as this:
```bash
# Bundle the current directory and copy it to the clipboard
treeclip run --clipboard
```
Now you can paste the entire project structure into your favorite AI chat! Easy peasy. (づ｡◕‿‿◕｡)づ
### Common Usage Patterns
Here’s a quick guide to some of the most useful commands. The table below covers most scenarios you'll encounter!
| **1** | **Quick Clipboard Copy**<br>*(My Daily Driver)* | `treeclip run --clipboard` | • Scans current directory<br>• Creates `treeclip_temp.txt`<br>• Copies to clipboard<br>• Shows tree emojis 🌳 | Pasting code into ChatGPT/Claude/etc |
| **2** | **Specific Directory + Custom Output** | `treeclip run ./src -o ./docs/dump.txt` | • Scans `./src` only<br>• Saves to custom location<br>• Doesn't touch clipboard | Documenting parts of project, creating archives |
| **3** | **Exclude Build Artifacts** | `treeclip run -e node_modules -e target -e .git` | • Scans current directory<br>• Ignores specified patterns<br>• Can stack multiple `-e` flags | Projects with dependencies/build outputs |
| **4** | **Review Before Sharing** | `treeclip run --editor --delete` | • Creates temp file<br>• Opens in `$EDITOR`<br>• Deletes after closing | When you want to edit before sharing |
| **5** | **The Full Experience™** | `treeclip run ./my-project -o ./export/snapshot.txt -e node_modules -e "*.lock" --clipboard --stats --verbose` | • Everything at once<br>• Full control<br>• Maximum verbosity<br>• Statistics shown | When you want ALL the features |
| **6** | **Fast Mode (No Animations)** | `treeclip run --fast-mode --clipboard` | • Instant execution<br>• No progress bars<br>• No cute emojis 😢 | CI/CD, scripts, large projects, or when in a hurry |
| **7** | **Include Hidden Files** | `treeclip run --no-skip-hidden` | • Includes `.env.example`, `.editorconfig`, etc<br>• Normally skipped by default | When you need config files included |
| **8** | **Stats Without Clipboard** | `treeclip run --stats` | • Creates output file<br>• Shows lines/words/bytes<br>• Size emoji feedback 🐣🐘🐋 | Analyzing codebase size |
| **9** | **Just Save to File** | `treeclip run ./src -o output.txt --fast-mode` | • No clipboard<br>• No stats<br>• Just saves file quickly | Archiving, documentation generation |
| **10** | **Verbose Progress Tracking** | `treeclip run --verbose --clipboard` | • Shows every step<br>• File count updates<br>• Detailed logging | Debugging, understanding what's included |
### Pro-Tip: Use a `.treeclipignore` File!
For files and directories you *always* want to ignore (like `node_modules` or `target`), create a `.treeclipignore` file in your project's root directory. It works just like a `.gitignore` file!
Here's a great starting point:
```
# .treeclipignore
# Dependencies
node_modules/
target/
.git/
# Build artifacts & logs
dist/
build/
*.log
*.lock
```
With this file in place, you can just run `treeclip run --clipboard` without needing to add `--exclude` flags every time. So much easier!
---
## All Command Options
### Positional Arguments
| `INPUT_PATH` | Directory to traverse | `.` (current directory) |
### Optional Arguments
| `--output-path <PATH>` | `-o` | Where to save the output file | `./treeclip_temp.txt` |
| `--root <PATH>` | | Root directory for `.treeclipignore` | `.` |
| `--exclude <PATTERN>` | `-e` | Patterns to exclude (can repeat) | None |
| `--clipboard` | `-c` | Copy output to clipboard | Off |
| `--stats` | | Show content statistics | Off |
| `--editor` | | Open output in default editor | Off |
| `--delete` | | Delete output after closing editor | Off |
| `--verbose` | `-v` | Show detailed progress | Off |
| `--skip-hidden` | `-H` | Skip hidden files/folders | **On** |
| `--no-skip-hidden` | | Include hidden files | Off |
| `--raw` | `-r` | Extract raw content | **On** |
| `--fast-mode` | `-f` | Skip animations, instant execution | Off |
| `--help` | `-h` | Show help message | - |
| `--version` | `-V` | Show version | - |
---
## Output Format
TreeClip creates a clean, AI-friendly format:
```
==> src/main.rs
fn main() {
println!("Hello, world!");
}
==> src/lib.rs
pub fn add(left: usize, right: usize) -> usize {
left + right
}
==> tests/integration_test.rs
#[test]
fn it_works() {
assert_eq!(2 + 2, 4);
}
```
Each file is clearly separated with its path, making it easy for AI to understand your project structure. No confusion,
no missing context!
---
## Tips & Tricks 💡
### Combine with Other Tools
```bash
# Count total lines in your project
treeclip run --fast-mode && wc -l treeclip_temp.txt
# Compare two versions of your code
treeclip run ./v1 -o v1.txt --fast-mode
treeclip run ./v2 -o v2.txt --fast-mode
diff v1.txt v2.txt
```
### Create Aliases
Add to your `.bashrc` or `.zshrc`:
```bash
# Quick clipboard copy
alias clip='treeclip run --clipboard --fast-mode'
# Review before sharing
alias clipr='treeclip run --clipboard --editor --delete'
# Full verbose snapshot
alias clips='treeclip run --clipboard --stats --verbose'
```
### Project-Specific Configurations
Keep a `.treeclipignore` in your project root:
```
# Dependencies
node_modules
target
vendor
# Build outputs
dist
build
out
*.min.js
# Logs and temp files
*.log
*.tmp
.DS_Store
# Don't share secrets!
.env
secrets.json
```
---
## Examples from Real Projects
### React Project
```bash
treeclip run ./src \
--exclude node_modules \
--exclude "*.test.js" \
--clipboard
```
### Rust Project
```bash
treeclip run \
--exclude target \
--exclude Cargo.lock \
--clipboard \
--stats
```
### Python Project
```bash
treeclip run \
--exclude __pycache__ \
--exclude "*.pyc" \
--exclude venv \
--clipboard
```
---
## Future Plans 🚧
- [ ] Configuration file support (`.treecliprc`)
- [ ] Interactive mode for selecting files
- [ ] Multiple output format support (JSON, Markdown, HTML)
- [ ] Token counting for AI models
- [ ] Smart exclusion patterns (auto-detect `.gitignore`)
- [ ] Streaming for huge projects
- [ ] Plugin system for custom processors
But honestly? I built this to learn Rust and solve my immediate problem. If you find it useful, awesome! If you want to
contribute, even better! ♡
---
## Contributing
Found a bug? Have an idea? Want to make it cuter?
1. Fork the repo
2. Make your changes
3. Submit a PR with a description
I'm still learning Rust, so if you spot any anti-patterns or improvements, I'm all ears! (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧
---
## License
[MIT License](./LICENSE) - feel free to use this however you want!
---
## Credits
Built with:
- Rust 🦀
- Intention of becoming a rustacean
- A genuine desire to stop copy-pasting code files
---
**Happy clipping!** ✨
*Made with ♡ (and a lot of Stack Overflow) by someone who just wanted a better way to share code with AI*