cltree 0.2.2

A TUI file explorer for Claude Code CLI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# cltree

[![GitHub Release](https://img.shields.io/github/v/release/jsleemaster/cltree)](https://github.com/jsleemaster/cltree/releases)
[![npm](https://img.shields.io/npm/v/cltree)](https://www.npmjs.com/package/cltree)
[![Crates.io Version](https://img.shields.io/crates/v/cltree)](https://crates.io/crates/cltree)
[![Crates.io Downloads](https://img.shields.io/crates/d/cltree)](https://crates.io/crates/cltree)
[![Homebrew](https://img.shields.io/badge/homebrew-available-blue)](https://github.com/jsleemaster/homebrew-tap)
[![GitHub Stars](https://img.shields.io/github/stars/jsleemaster/cltree)](https://github.com/jsleemaster/cltree/stargazers)
[![GitHub Issues](https://img.shields.io/github/issues/jsleemaster/cltree)](https://github.com/jsleemaster/cltree/issues)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

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

### Homebrew (macOS / Linux)

```bash
brew install jsleemaster/tap/cltree
```

### From crates.io

```bash
cargo install cltree
```

### From source

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

## Usage

```bash
# 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

| Key | Action |
|-----|--------|
| `Ctrl+Q` | Quit |

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

```bash
# 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](LICENSE) file for details.

## Acknowledgments

- [ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI framework
- [Claude Code](https://claude.com) - AI coding assistant by Anthropic
- Inspired by ranger, nnn, and other terminal file managers