Repo2Txt

Turn your codebase into clean, LLM-ready context.

Repo2Txt is a fast, interactive terminal UI (TUI) for exploring a repository, selecting the files you want, and generating a single repo.txt containing the project's source code and structure.

Instead of asking an LLM to inspect dozens of files one by one, give it the context in a single, organized document.

Repository
    │
    ▼
┌─────────────────────┐
│   Interactive TUI   │
│                     │
│  Browse             │
│  Search             │
│  Include / Exclude  │
│  Gitignore          │
└──────────┬──────────┘
           │
           ▼
      repo.txt
           │
           ▼
        LLM / AI

✨ Features

• 🌳 Interactive file tree — browse your repository directly from the terminal.
• 🎯 File and directory selection — include or exclude individual files or entire directories.
• 🔍 Search — quickly find files and directories by path.
• 📂 Collapse directories — navigate large repositories without losing context.
• 🚫 Gitignore-aware — respects .gitignore and excludes ignored files by default.
• 👁️ Gitignored toggle — optionally include ignored and hidden files.
• ⚡ Fast scanning — designed to remain responsive on large repositories.
• 🛑 Hard exclusions — .git and node_modules are never traversed.
• 📦 Binary detection — binary files are automatically skipped.
• ✂️ Large-file protection — files larger than 1 MiB are truncated.
• 🏷️ Language detection — generated sections include language metadata.
• 🔐 Deterministic markers — every generated file has clear start/end boundaries and a content-based marker.
• 🦀 Built with Rust — fast, self-contained and easy to install with Cargo.
• 📄 Simple output — generates a single repo.txt that can be uploaded or pasted into an LLM.

Why?

Modern AI coding assistants can work with entire repositories, but providing that context is often unnecessarily expensive or cumbersome.

A typical workflow might require:

List directory
    ↓
Read file
    ↓
Read another file
    ↓
List another directory
    ↓
Read more files
    ↓
Repeat...

Repo2Txt turns that into:

Select context
    ↓
Generate repo.txt
    ↓
Give it to the LLM

This makes it especially useful when you want to ask an LLM to:

• Understand an unfamiliar codebase.
• Review an architecture.
• Debug a feature spanning multiple files.
• Refactor a module.
• Implement a new feature.
• Explain how different parts of a project interact.
• Analyze a repository without manually collecting every relevant file.

🚀 Installation

Requirements

You need Rust and Cargo installed.

From crates.io

Simply run:

cargo install repo2txt

Install from source

Clone the repository:

git clone https://github.com/EuSouVoce/repo2txt-cli.git
cd repo2txt-cli

Install the binary:

cargo install --path . --locked

Cargo'll build and install it!

Usage

Run Repo2Txt in the current directory:

repo2txt

Or specify a repository:

repo2txt /path/to/your/project

The application opens an interactive terminal interface.

When you're ready, press w or ⇧G (Shift+G) to generate the output.

The generated file will be:

/path/to/your/project/repo.txt

🖥️ Interface

The TUI (powered by ratatui) provides a tree view of the repository:

 repo2txt  repo2txt-cli │ selected files: 9 │ filters: all │ gitignored: excluded
┌ File tree ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│   [~] .gitignore (gitignore)  (7 B)                                                                                                 │
│   [x] Cargo.lock  (25570 B)                                                                                                         │
│   [x] Cargo.toml  (485 B)                                                                                                           │
│   [x] README.md  (14199 B)                                                                                                          │
│▸  [x] src                                                                                                                           │
│     [x] app.rs  (5856 B)                                                                                                            │
│     [x] generate.rs  (4004 B)                                                                                                       │
│     [x] main.rs  (4082 B)                                                                                                           │
│     [x] repo.rs  (6167 B)                                                                                                           │
│     [x] tests.rs  (714 B)                                                                                                           │
│     [x] ui.rs  (4703 B)                                                                                                             │
│▸  [~] target (gitignore)                                                                                                            │
│                                                                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ↑/↓ browse  │ Enter/Space toggle include/exclude  │ g toggle gitignored  │ / search  │ ⇧G / w generate repo.txt  │ r clear  │ q exit│
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

⌨️ Keyboard Shortcuts

Key	Action
↑ / k	Move up
↓ / j	Move down
Enter / Space	Include / exclude
Tab / →	Collapse / expand directory
g	Toggle gitignored files
/	Search
Enter	Confirm search
Esc	Cancel search
w	Generate repo.txt
Shift+G	Generate repo.txt
r	Clear selections
q	Quit
Ctrl+C	Quit

🎯 File Selection

Each file or directory has a selection state.

[x] file.rs
[+] explicitly included
[-] explicitly excluded
[~] gitignored / currently excluded

Default

Files are included unless they are gitignored or explicitly excluded.

Include

Press Enter or Space on a file to explicitly include it.

Exclude

Press Enter or Space again to exclude it.

Directory selection

Selecting a directory applies the selection recursively to all entries beneath it.

This makes it easy to create focused contexts such as:

src/
├── api/
├── database/
├── models/
└── services/

For example, you can include src/services/ while excluding unrelated parts of the repository.

🔍 Search

Press / to enter search mode.

Search is performed against repository paths, so you can quickly find things like:

/api
/auth
test
config
README
.rs

Press Enter to keep the search active or Esc to cancel it.

🚫 Gitignore

Repo2Txt is aware of .gitignore.

Gitignored and hidden files are excluded by default:

[x] src
[x] Cargo.toml
[~] .env
[~] dist/

Press g to toggle inclusion of gitignored files.

This is useful when you deliberately want to provide files that normally aren't tracked, such as generated configuration or local project metadata.

Always excluded!

Some directories are intentionally never traversed:

.git/
node_modules/

These directories can contain enormous amounts of data and generally provide little value as LLM context.

They are pruned during repository traversal rather than merely filtered after scanning.

📦 Binary Files

Repo2Txt automatically detects and skips binary files.

A file is considered binary when a null byte is found within its first 8 KiB.

Binary files are not written to repo.txt.

This prevents things such as:

• images
• executables
• compiled assets
• archives
• databases

from polluting the generated context.

✂️ Large Files

Individual files larger than 1 MiB are truncated.

The generated output contains:

... [truncated]

This prevents a single large file from consuming an excessive amount of LLM context.

The generator still reports how many files were truncated after generation.

🏷️ Language Detection

Generated files include language metadata based on their filename or extension.

For example:

===== FILE_START: src/main.rs [Rust] (1234 bytes) =====

Commonly recognized formats include:

• Rust
• TypeScript
• JavaScript
• Python
• Ruby
• Go
• Java
• Kotlin
• Swift
• C
• C++
• C#
• PHP
• SQL
• Prisma
• JSON
• YAML
• TOML
• Markdown
• Shell
• HTML
• CSS
• SCSS
• Vue
• Svelte
• Terraform
• XML
• Gradle
• INI
• Dockerfile
• Makefile
• Lockfiles

Unknown extensions are represented using their uppercase extension.

📄 Output Format

Repo2Txt intentionally produces a simple, predictable text format.

A generated repo.txt looks like:

Repository: my-project
Files: 3

===== FILE_START: src/main.rs [Rust] (1234 bytes) =====
fn main() {
    println!("Hello, world!");
}
===== FILE_END: src/main.rs [a1b2c3d4e5f6...] =====

===== FILE_START: src/lib.rs [Rust] (856 bytes) =====
pub fn hello() {
    println!("Hello!");
}
===== FILE_END: src/lib.rs [9f8e7d6c5b4a...] =====

===== FILE_START: Cargo.toml [TOML] (456 bytes) =====
[package]
name = "my-project"
version = "1.0.0"
===== FILE_END: Cargo.toml [f6e5d4c3b2a1...] =====

Each file is surrounded by explicit delimiters.

The end marker contains a deterministic FNV-1a hash based on the file path and generated content, making file boundaries easier to identify and validate.

🤖 Using Repo2Txt with LLMs

After generating repo.txt, simply upload it to your preferred AI assistant.

For example:

Here is the complete repository context/digest.

Please analyze the architecture and explain how authentication
works across the project.

Or:

Review this codebase and identify the most important technical
debt. Prioritize issues that would make future development harder.

Or:

I want to add feature X.

First, understand the existing architecture from the repository,
then propose which files should be changed and why. Or give me an applicable .patch file.

Repo2Txt works particularly well when the relationship between files matters.

⚡ Performance

Repo2Txt is designed with large repositories in mind.

The scanner:

• Prunes .git and node_modules before descending.
• Uses a compiled gitignore matcher.
• Avoids repeatedly evaluating ignore rules for every file.
• Uses efficient directory traversal.
• Keeps the selection model separate from repository scanning.
• Uses Rust for low-overhead filesystem processing.

The goal is not to blindly process everything, but to make the process of selecting useful context fast.

🦀 Development

Clone the project:

git clone https://github.com/EuSouVoce/repo2txt-cli.git
cd repo2txt-cli

Run directly with Cargo:

cargo run -- .

Run the tests:

cargo test

Build an optimized release:

cargo build --release

The release profile enables:

[profile.release]
lto = true
strip = true

🧪 Tests

The project currently includes tests covering repository scanning behavior, including:

• .git exclusion.
• node_modules exclusion.
• .gitignore detection.
• Non-ignored files remaining available for selection.

Run them with:

cargo test

🏗️ Architecture

The project is intentionally small and split into a few focused modules:

src/
├── main.rs       # CLI entry point and event loop
├── app.rs        # Application state and user interactions
├── repo.rs       # Repository scanning and selection logic
├── generate.rs   # repo.txt generation
├── ui.rs         # Ratatui terminal interface
└── tests.rs      # Tests

repo.rs Responsible for:

• Repository traversal.
• .gitignore matching.
• Hard exclusions.
• File metadata.
• Selection state.

app.rs Contains the application state and user actions:

• Navigation.
• Searching.
• Selection.
• Directory collapsing.
• Gitignored toggle.
• Generation.

generate.rs Responsible for:

• Reading selected files.
• Binary detection.
• Large-file truncation.
• Language detection.
• File markers.
• Writing repo.txt.

ui.rs Renders the terminal interface using Ratatui.

💡 Inspiration & Prior Art

Repo2Txt is part of a broader ecosystem of tools built around the idea of turning source repositories into AI/LLM-friendly context.

The project was particularly inspired by CodeTxt and its approach of converting repositories into a single textual representation suitable for LLM workflows.

Other projects that helped shape the problem space and influenced the design include:

• CodeTxt - one of the main inspirations for Repo2Txt's core concept of converting repository contents into a clean text representation for LLMs.
• Code2Prompt - a Rust-based tool focused on transforming codebases into structured prompts, with features around filtering, .gitignore, selection and LLM context.
• Repomix - a well-known tool for packaging repositories into AI-friendly files, with extensive filtering and configuration capabilities.
• repo2txt - an earlier project exploring the general concept of representing repository contents as a single text file.

These projects demonstrate the value of treating a repository as a coherent unit of context rather than forcing an AI assistant to inspect files individually.

What Repo2Txt aims to do differently

Repo2Txt is deliberately focused on a simple workflow:

Open repository ↓ Browse visually ↓ Select what matters ↓ Generate repo.txt ↓ Give it to your LLM

It aims to provide a lightweight, terminal-first experience without requiring users to configure complex prompt templates, tokenization pipelines, or external services.

Repo2Txt is an independent implementation inspired by these projects and the broader LLM/codebase tooling ecosystem. It is not intended to be a fork or a direct port of CodeTxt, Code2Prompt, Repomix, or any other project.

🛣️ Roadmap

Potential future improvements include:

• Configurable output path.
• Configurable maximum file size.
• Token estimation.
• Token/context budget visualization.
• Additional output formats.
• Custom ignore patterns.
• .git/info/exclude support.
• Git status integration.
• Better selection indicators.
• Configurable keyboard shortcuts.
• Clipboard integration.
• Optional output compression.
• More extensive test coverage.
• Cross-platform release binaries.

🤝 Contributing

Contributions are welcome.

A good place to start is:

cargo test
cargo run -- .

Before submitting a pull request:

1. Keep the implementation focused.
2. Add or update tests when behavior changes.
3. Keep the TUI responsive.
4. Avoid unnecessary dependencies.
5. Preserve the simple repo.txt output format unless there is a strong reason to change it.

📜 License

This project is licensed under the MIT License.

See the LICENSE file for details.

🙏 Thanks

Thanks to the developers of the projects that helped establish and explore this workflow, especially CodeTxt, as well as Code2Prompt, Repomix, and other tools in the LLM code-context ecosystem.

Repo2Txt builds on the same fundamental insight:

The better the context, the better the AI can understand your code.