cltree

A terminal-based file explorer designed to work alongside Claude Code CLI. View your project structure in a split-pane TUI while using Claude Code.

┌─────────────────────────────────────────────┬──────────────────────┐
│                                             │ 📂 my-project        │
│  Claude Code                                │ ├── 📁 src           │
│                                             │ │   ├── 🦀 main.rs   │
│  > Help me refactor this function           │ │   ├── 🦀 app.rs    │
│                                             │ │   └── 📁 ui        │
│  I'll analyze the code structure...         │ ├── 📋 Cargo.toml    │
│                                             │ ├── 📖 README.md     │
│                                             │ └── 📄 .gitignore    │
│                                             │                      │
│                                             │ ● src/ui             │
└─────────────────────────────────────────────┴──────────────────────┘

Features

• Split-pane TUI: File tree on the right, Claude Code on the left
• Passive file tree: Always-expanded, read-only project structure display
• CWD tracking: Highlights Claude Code's current working directory with a ● marker
• OSC 7 + vterm detection: Automatically detects directory changes via escape sequences
• gitignore support: Respects .gitignore patterns
• File icons: Visual indicators for different file types
• Zero interference: All keystrokes are forwarded directly to Claude Code

Installation

npm / bun

npm install -g cltree
# or
bun install -g cltree

Homebrew (macOS / Linux)

brew install jsleemaster/tap/cltree

From crates.io

cargo install cltree

From source

git clone https://github.com/jsleemaster/cltree.git
cd cltree
cargo install --path .

Usage

# Start in current directory
cltree

# Start in specific directory
cltree --path /path/to/project

# Adjust tree width (10-50%)
cltree --tree-width 25

# Show hidden files
cltree --show-hidden

Keyboard Shortcuts

All other keystrokes are passed directly to Claude Code.

Configuration

Command line options

Options:
  -p, --path <PATH>          Working directory [default: .]
  -w, --tree-width <WIDTH>   Tree panel width percentage (10-50) [default: 30]
  -a, --show-hidden          Show hidden files
  -d, --depth <DEPTH>        Max tree depth [default: 10]
  -h, --help                 Print help
  -V, --version              Print version

Development

# Clone
git clone https://github.com/jsleemaster/cltree.git
cd cltree

# Run in development
cargo run

# Run tests
cargo test

# Build release
cargo build --release

Requirements

• Rust 1.70+
• Claude Code CLI installed and in PATH
• Terminal with UTF-8 and true color support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• ratatui - Terminal UI framework
• Claude Code - AI coding assistant by Anthropic
• Inspired by ranger, nnn, and other terminal file managers