index.md

CopyTree Documentation

CopyTree is a powerful Node.js CLI tool that intelligently copies directory structures and file contents into AI-friendly formats. Perfect for sharing codebases with AI assistants, documentation generation, and code analysis.

Requirements: Node.js 20+ | ESM only | View on GitHub

🚀 Start Here

New to CopyTree? Follow this path to get productive in 10 minutes:

1. Quickstart Guide - Install and run your first copy
2. Create Your First Profile - Customize file selection for your needs
3. Basic Usage - Master common workflows and patterns

📚 Documentation by Section

Getting Started

Perfect for newcomers and quick reference:

• Quickstart Guide - Get up and running in 10 minutes
• Your First Custom Profile - Learn to create profiles step-by-step
• Installation Guide - Complete installation instructions
• Claude Code Integration - Use with Claude Code

User Guides

For day-to-day usage:

• Basic Usage - Common commands and workflows
• Troubleshooting - Solve common problems
• Secrets Guard - Prevent accidental secret exposure

Reference

Authoritative technical references:

• Configuration Reference - Complete config system with precedence rules
• CLI Reference - All commands and options

Developer Documentation

For contributors and extenders:

• Architecture Guide - Pipeline, stages, and event system
• Testing Strategy - Test infrastructure and patterns

✨ Key Features

1. Intelligent File Selection

• Profile System: Default profile automatically used; create custom profiles for project-specific needs
• Git Integration: Copy only modified or changed files
• Pattern Matching: Flexible include/exclude rules

2. Multiple Output Options

• Clipboard: Default output for easy pasting
• File Output: Save to file
• Streaming: Real-time output for large projects
• Multiple Formats: XML (default), Markdown, JSON, NDJSON, SARIF, or tree view

3. Developer-Friendly

• External Sources: Include files from GitHub or other directories
• Editor Integration: Works with VS Code, Cursor, and Claude Code
• Secrets Detection: Prevent accidental exposure of API keys and credentials

🎯 Common Use Cases

Share Code with AI

# Copy entire project (uses default profile)
copytree

# Copy with custom profile
copytree --profile myproject

Document Generation

# Generate project overview as Markdown
copytree --output project-overview.md

# Generate as XML (default format)
copytree --output project-overview.xml

Code Review

# Copy only git modified files
copytree --modified

# Copy files changed since a specific ref
copytree --changed HEAD~5

🔧 Configuration

CopyTree uses a two-level configuration system:

1. Default Configuration: Built-in defaults
2. User Configuration: ~/.copytree/config/ directory (.js or .json files)

Quick Configuration

# Validate configuration
copytree config:validate

# Inspect configuration with provenance
copytree config:inspect

# Clear cache
copytree cache:clear

📖 Learn More

• Basic Usage Guide - Complete usage documentation
• Troubleshooting Guide - Solve common issues
• Claude Code Integration - Use with Claude Code

🐛 Troubleshooting

Having issues? Check our comprehensive Troubleshooting Guide or run:

# Check system requirements
copytree config:validate

# View debug information
DEBUG=copytree:* copytree

📄 License

CopyTree is open-source software licensed under the MIT License.