repOx

High-performance CLI & TUI repository packer for LLM context prompts. Sub-30ms execution, zero runtime dependencies.

---

The Problem

You want Claude Fable, GPT-6 Luna, Gemini 3, or DeepSeek R1 to refactor a subsystem across your codebase. You run a quick script to dump your files, paste the output into the prompt, and realize:

1. Context window pollution: 40,000 tokens were burned on Cargo.lock, package-lock.json, minified bundles, SVG graphics, and binary artifacts.
2. Sluggish tooling: Existing Node.js/Python packers take 2–5 seconds, allocate 200MB of RAM, and still don't let you pick what to exclude.
3. No tactile control: You either pack everything or spend ten minutes crafting custom exclude flags.

repOx solves this. It scans multi-thousand-file repositories in milliseconds, strips noise with Git heuristics, provides a lazygit-style terminal UI for instant pruning, and copies clean, model-optimized prompts straight to your clipboard.

---

Benchmarks

Measured using hyperfine on Apple Silicon (M-series) traversing a 3,000+ file repository (15 runs, 3 warmups):

---

Comparison Matrix

---

Installation

One-Line Installer (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/WVDYC/repOx/main/install.sh | sh

Homebrew (macOS & Linux)

brew tap WVDYC/tap https://github.com/WVDYC/repOx
brew install repox

Cargo (From Source)

Requires Rust 1.85+ (2024 edition):

cargo install --git https://github.com/WVDYC/repOx.git

Or build locally:

git clone https://github.com/WVDYC/repOx.git
cd repOx
cargo build --release
# Binary: ./target/release/repox

Shell Completions

repOx generates native completions for all major shells:

# Zsh
repox --completions zsh > ~/.zsh/completion/_repox

# Bash
repox --completions bash > ~/.local/share/bash-completion/completions/repox

# Fish
repox --completions fish > ~/.config/fish/completions/repox.fish

---

Interactive TUI (lazygit for Prompts)

Launch the terminal interface with repox -i or repox --tui.

┌── Files ──────────────────────────────────┐┌── Preview: src/main.rs ──────────────┐
│ ▸ [x] crates/                             ││ 1 │ use clap::Parser;                 │
│ ▾ [x] src/                                ││ 2 │ use color_eyre::eyre::Result;     │
│   [x] cli.rs                     7.1 KB   ││ 3 │                                   │
│   [x] main.rs                    3.8 KB   ││ 4 │ fn main() -> Result<()> {         │
│   [x] Cargo.toml                 1.4 KB   ││ 5 │     // fast parallel walk...      │
└───────────────────────────────────────────┘└───────────────────────────────────────┘
  [Claude Fable 5.1 (1M)] 26/26 files | 45,260 / 1,000,000 tokens (4.5%) [■░░░░░░░░░] 166.0 KB
  [↑/↓] Move  [Space] Toggle  [/] Search  [a] Invert  [c] Copy  [Enter] Dump  [q] Quit

Keybindings

---

Quickstart & Common Workflows

1. Interactive selection with live token budgeting

repox -i -p fable
# Also supports: -p luna, -p gemini, -p deepseek, -p o1, -p claude

Launches the TUI calibrated against the target model's context window (e.g. 1,000,000 tokens for Fable/Gemini, 1.05M for Luna).

2. Copy entire codebase to clipboard (headless)

repox -c

Copies Claude-formatted XML prompt directly to your system clipboard:

✓ Copied to clipboard: 42 files (142.6 KB) in 4.12ms

3. Include accurate offline token counts

repox -c -t -p claude

✓ Copied to clipboard: 42 files (142.6 KB, 38,120 tokens) in 38.50ms

4. Save formatted Markdown to file

repox -f md -o context.md

5. Filter by subfolder, max file size, and depth

repox src/ -s 500KB -d 3 -o prompt.xml

6. Pipe clean prompt into another tool

repox -q | pbcopy

---

Output Formats

Claude XML Output (-f xml, Default)

Includes an ASCII directory tree followed by cleanly tagged file blocks:

<repository_structure>
.
├── Cargo.toml
├── crates
│   └── repox-core
│       └── src
│           └── lib.rs
└── src
    └── main.rs
</repository_structure>

<file path="Cargo.toml">
[workspace]
members = ["crates/*"]
</file>

<file path="src/main.rs">
fn main() { ... }
</file>

Markdown Output (-f md)

Uses collision-safe backtick fencing (automatically escapes nested backticks):

# Repository Structure

```
.
├── Cargo.toml
└── src
    └── main.rs
```

# Repository Files

## File: Cargo.toml

```toml
[workspace]
...
```

## File: src/main.rs

```rust
fn main() { ... }
```

---

Architecture & Internals

repOx is engineered around three core principles: zero-allocation rendering, deterministic output, and fail-safe ergonomics.

1. Contiguous FlatTree Arena (crates/repox-tui/src/tree.rs)

Recursive tree widgets frequently allocate on every frame and suffer from cache thrashing. repOx flattens the file hierarchy into a single contiguous pre-order Vec<Node>:

• Subtrees occupy contiguous slices [start..end].
• Expanding or collapsing is an $O(1)$ slice mask.
• Toggling selection recalculates folder aggregates in a single reverse-slice sweep with zero allocations in the render loop.

2. Multi-Threaded Work-Stealing Traversal (crates/repox-core/src/scanner.rs)

• Uses ignore::WalkBuilder with lock-free channel batching.
• Automatically respects .gitignore, .ignore, and .repoxignore.
• Evaluates binary content via Git's 8KB NUL-byte heuristic and drops lockfiles, minified bundles, SVGs, and secret keys (.env*, *pem, *id_rsa*) before reading full payloads into memory.

3. TUI via stderr for Clean Unix Pipelines

The interactive TUI renders exclusively to stderr. This means stdout is never corrupted by escape codes, allowing clean composition:

repox -i | llm prompt "explain the architecture"

4. Terminal Safety

Uses an RAII TerminalGuard with a panic hook to guarantee that raw mode is disabled and the alternate screen is exited even if an abnormal termination occurs.

---

CLI Reference

repox [OPTIONS] [PATH]

Arguments:
  [PATH]                     Target repository directory [default: .]

Options:
  -i, --interactive          Launch interactive terminal UI file picker (alias: --tui)
  -f, --format <FORMAT>      Format template: 'xml' (Claude-optimized) or 'markdown' / 'md' [default: xml]
  -c, --copy                 Copy output context directly to system clipboard
  -o, --output <FILE>        Write formatted context to an output file instead of stdout
  -t, --tokens               Calculate total token count using multi-threaded tiktoken tokenizer
  -p, --token-profile <PROF> Tokenizer profile: 'fable' (Claude Fable 5.1, 1M), 'luna' (GPT-6 Luna, 1.05M), 'claude', 'o1', 'deepseek', 'gemini', 'cl100k' [default: cl100k]
  -s, --max-file-size <SIZE> Skip files exceeding size threshold (e.g. 500KB, 1.5MB) [default: 1MB]
  -d, --max-depth <DEPTH>    Maximum directory nesting depth to traverse
      --no-gitignore         Disable respecting .gitignore files
      --no-repoxignore       Disable respecting .repoxignore files
      --include-hidden       Include hidden files and folders
  -e, --exclude <GLOB>       Glob pattern to exclude (can be specified multiple times)
  -I, --include <GLOB>       Glob pattern to include exclusively (can be specified multiple times)
  -j, --threads <N>          Worker threads count (defaults to logical CPU core count)
      --completions <SHELL>  Generate shell completions (bash, zsh, fish, powershell, elvish)
  -q, --quiet                Silence informational statistics on stderr
  -v, --verbose              Enable verbose debug logs
  -h, --help                 Print help
  -V, --version              Print version

---

Testing

cargo test --workspace

---

License

Dual-licensed under either:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.