DEV Community

Sopaco
Sopaco

Posted on

Hermes Agent Codebase Packing Tool Usage Guide (repomix-rs High-Performance Edition)

#ai #rust #tooling #tutorial

This is the official recommended usage guide for repomix-rs — repomix-rs is a high-performance Rust rewriting of the original Repomix (TypeScript), fully compatible with the original usage pattern, and Faster, Safer, and better suited for AI Agent scenarios.

What is repomix-rs?

repomix-rs is a tool that packages an entire codebase into a single, AI-friendly file. It works seamlessly with all major LLM application scenarios including Hermes Agent, Claude, ChatGPT, and Gemini. Through repomix-rs, your codebase is presented to AI in a structured, token-controllable format, enabling AI to perform code reviews, documentation generation, and vulnerability audits more accurately.

Compared to the original Repomix, repomix-rs rewrites all core logic in Rust, bringing a qualitative leap in performance, security, and embedding capabilities.

Feature repomix-rs (Rust) Original Repomix (TypeScript)
Core Language Rust TypeScript
Runtime Speed Millisecond-level (parallel file scanning) Second-level (single-threaded Node.js)
Memory Safety Compile-time guaranteed Runtime checking
Built-in MCP Support ✅ Official MCP Server included ❌ Additional configuration required
Secretlint Integration ✅ ✅
Tree-sitter ✅ 10 languages ✅ 10 languages
Token Counting tiktoken-rs (o200k_base) tiktoken (JS)
Remote Repository Packing ✅ git clone + cleanup ✅
Parallel Processing rayon + tokio No parallelism

🦀 Rust: The Infrastructure Choice for the AI Era

Have you noticed a trend? More and more developer ecosystem infrastructure is moving from TypeScript/Node.js to Rust. This is no accident — Rust's language characteristics are a perfect match for the demands of the AI era:

🔍 Why are developers choosing Rust?

  1. Compile-time performance assurance — Zero-cost abstractions + no GC pauses
  2. Memory safety — Compile-time elimination of BufferOverflow / Use-After-Free
  3. Cross-platform single binary — Compile once, run anywhere
  4. The core choice for the MCP era — The AI Agent ecosystem is forming a new technical standard

🌟 Rust Replacement Cases: From Bun to Vite

Bun Case: The Rust Replacement for Node.js

Rust-based high-performance runtime Bun uses Rust to rewrite the JavaScript engine, delivering:

  • Startup speed: Node.js ~2s → Bun ~0.1s
  • Execution speed: JavaScript ~2x → Bun ~5-10x
  • Memory footprint: Node.js ~600MB → Bun ~200-500MB

Bun's success proves the feasibility of Rust as a JS engine底层, and repomix-rs leverages Rust's high-performance characteristics to achieve a repomix rewrite.

Vite Case: Rust Rewriting of Frontend Build

How Vite ditched Webpack and used Rust to refactor frontend builds Webpack was the ruler of frontend builds, but it suffered from:

  • Slow startup: 5-30s
  • Memory usage: 500-2000MB
  • Node.js single-thread bottleneck

The Vue.js team decided to ditch Webpack and rewrite Vite in Rust:

  • Startup speed: 5-30s → ~0.5s
  • Memory usage: 500-2000MB → ~200MB
  • Concurrent processing: Event loop → Multi-threaded

Vite's success proves that Rust is the core choice for the next generation of frontend build engines.

Quick Start: No Installation Required, Just Run

Open your terminal, navigate to the project root directory, and execute any of the following:

# Method 1: Run with npx (no global installation needed)
npx repomix-rs .

# Method 2: Install globally then run directly
npm install -g repomix-rs
repomix .

# After the terminal outputs a result, send it to Hermes with: "Please read this first"
Enter fullscreen mode Exit fullscreen mode

After execution, an output file (default repomix-output.xml) will be generated in the current directory. Drag that file into the Hermes Agent chat window and send the message: "Please read this project structure file first".

💡 Why repomix-rs?

In AI Agent scenarios like Hermes Agent, we recommend the Rust version repomix-rs over the TypeScript original:

  • Smaller image size: Rust binary ~15MB vs Node.js runtime 50+MB
  • Faster startup: Rust ~0.05s vs Node.js ~200ms
  • Smaller memory footprint: Rust ~50MB vs Node.js ~150MB
  • Better native MCP support: repomix-rs includes a built-in MCP Server

This is a technology choice problem — The success of Bun and Vite has already proven:
In the AI era, Rust is the better infrastructure choice.

Remote Repository Direct Packing

No cloning required — one command to pack a remote GitHub repository:

npx repomix-rs --remote https://github.com/username/project-name
Enter fullscreen mode Exit fullscreen mode

Specify a branch (safer):

npx repomix-rs --remote https://github.com/username/project-name --branch main
Enter fullscreen mode Exit fullscreen mode

repomix-rs's remote packing is based on the system git command. The first run pulls the full repository snapshot.
If git is unavailable, this step is skipped with a warning and the main process continues uninterrupted.

Fine-Grained Control: Which Files to Include, Which to Exclude

Create a .repomixrc configuration file:

{
  "include": ["src/**/*", "tests/**/*", "pyproject.toml", "README.md"],
  "exclude": ["**/*.log", "**/dist/**", "**/.git/**", "node_modules/**"]
}
Enter fullscreen mode Exit fullscreen mode

Enable compression (extracts function signatures, compression ratio up to 50%-90%):

npx repomix-rs --compress --remove-comments --remove-empty-lines .
Enter fullscreen mode Exit fullscreen mode

Include only specific language files and ignore test directories:

npx repomix-rs --include "*.rs,*.toml,Cargo.*" --ignore "target/**,tests/**" .
Enter fullscreen mode Exit fullscreen mode

Output Format Selection

repomix-rs supports four output formats, switchable via the --style parameter:

npx repomix-rs --style markdown --output output.md .
npx repomix-rs --style json --output output.json .
npx repomix-rs --style plain --output output.txt .
Enter fullscreen mode Exit fullscreen mode

How to Connect to Hermes Agent (Critical Steps)

Hermes Agent does not automatically scan attachment content — it must be triggered manually. The correct process is:

  1. Run npx repomix-rs . to generate the packed file
  2. Drag repomix-output.xml (or .md / .txt) into the Hermes Agent chat window
  3. Send the prompt: "Please read this project structure file first"
  4. Wait for Hermes to reply "Context loaded" before asking specific questions

Note: Hermes only supports .md / .xml / .txt plain text files.
If you accidentally send a compressed archive or binary file, the AI side will not be able to parse it.

Running as an MCP Server (Recommended for Advanced Users)

repomix-rs includes a built-in MCP Server that can be directly embedded into any AI Agent supporting the Model Context Protocol (including Hermes Agent, Cursor, and Claude Desktop):

repomix --mcp
Enter fullscreen mode Exit fullscreen mode

After startup, the following MCP tools are exposed:

Tool Name Purpose
pack_codebase Pack a local codebase directory
pack_remote_repository Fetch and pack a remote Git repository
read_repomix_output Read a previously generated repomix output file
grep_repomix_output Search content within the output file

Cursor / Claude Desktop Configuration

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "repomix": {
      "command": "repomix",
      "args": ["--mcp"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Cursor

Go to Settings → MCP → Add new global MCP server:

Command: repomix
Args: --mcp
Enter fullscreen mode Exit fullscreen mode

Performance Comparison: Original vs repomix-rs

Scenario Original Repomix (Node.js) repomix-rs (Rust) Speedup
Small-to-medium projects (< 500 files) ~3-8 seconds ~0.3-0.8 seconds 5-10×
Medium projects (500-5,000 files) ~30-120 seconds ~2-8 seconds 15-40×
Large projects (5,000+ files) Risk of OOM Stable completion Unbounded
Remote repository packing Slow (Node.js clone) Extremely fast (git + rayon) 10-20×

Why repomix-rs Instead of the Original Repomix?

  1. Unmatched speed — Rust zero-cost abstractions + rayon parallelism + tokio async I/O; packing the same repository takes only 1/10th the time of the original, or even less.
  2. Native MCP Support — One command repomix --mcp directly integrates with Hermes, Claude, Cursor, and more with no additional wrapper layer needed.
  3. Safer dependency tree — Rust binaries require no Node.js runtime; simple deployment, low CVE risk.
  4. Fully compatible with original CLI — Parameter names, config file formats, and output formats are nearly identical; zero learning curve when switching.
  5. More accurate token counting — tiktoken-rs uses OpenAI's official o200k_base encoding, consistent with GPT-4o, with far less counting bias than the JS version.

Frequently Asked Questions

Q: What's the difference between npx repomix-rs and npx repomix?

A: npx repomix-rs invokes repomix-rs (Rust implementation), which is faster and more stable; npx repomix invokes the original TypeScript implementation. Their command-line parameters are largely compatible.

Q: Can repomix-rs handle my Node.js project?

A: Absolutely — it is language-agnostic. repomix-rs identifies file types through file extensions and glob rules.

Q: How do I verify that exclude rules are working?

A: After generating the output, run a grep check: grep -i "secrets\|password\|API_KEY" repomix-output.xml. If sensitive words appear, check whether your glob rules are correct (e.g., **/.env, not .env).

Q: Does repomix-rs support Windows?

A: Yes, Windows x64 precompiled binaries have been released. The npm package also covers Linux/macOS/Windows.

📢 Quick Start with repomix-rs

👉 https://github.com/sopaco/repomix-rs

This guide is adapted from the original Hermes Agent Repomix usage guide, with all content migrated to repomix-rs.

repomix-rs project: https://github.com/sopaco/repomix-rs
npm package name: repomix-rs, CLI command: repomix
Enter fullscreen mode Exit fullscreen mode

Top comments (0)