Rlm Tools

🚀 RLM Tools

RLM Tools is an AI coding assistant that helps your AI coding agent make the most of its token budget. Instead of spending a large portion of tokens on simply reading code, it allows the agent to explore code in a persistent sandbox. Only the conclusions are sent back, significantly reducing the amount of data in the context window.

🚀 Quick Start

You can install RLM Tools in one line using either Claude Code or Codex:

# Install in one line (Claude Code)
claude mcp add rlm-tools -- uvx rlm-tools

# Or Codex
codex mcp add rlm-tools -- uvx rlm-tools

Once installed, your agent will automatically use the sandbox for exploration without any additional configuration or changes to prompts.

✨ Features

Reduced Context Usage

Without RLM Tools, an agent might grep for import UIKit and get 500 matches dumped into the context. It would then read 10 files, consuming a large number of tokens. This can quickly fill up the context window and cause the agent to forget what it was doing.

With RLM Tools, the agent runs the same exploration in a server-side Python sandbox. Only the print() output enters the context, reducing the amount of data significantly. For example:

matches = grep("import UIKit")
by_module = {}
for m in matches:
    module = m["file"].split("/")[0]
    by_module.setdefault(module, []).append(m)
for module, ms in sorted(by_module.items(), key=lambda x: -len(x[1]))[:5]:
    print(f"{module}: {len(ms)} files")

This turns 500 lines of grep results into 5 lines of summary, allowing the agent to see only what it needs.

Real-World Impact

In typical coding workflows, RLM Tools can reduce context usage by 25 - 35%. This means your agent can explore roughly 40 - 50% more code before hitting context limits. In heavy exploration tasks, the savings are even greater:

For full benchmark methodology and reproduction steps, see .

📦 Installation

One-Line Installation

# Install in one line (Claude Code)
claude mcp add rlm-tools -- uvx rlm-tools

# Or Codex
codex mcp add rlm-tools -- uvx rlm-tools

Other Installation Methods

{
  "mcpServers": {
    "rlm-tools": {
      "command": "uvx",
      "args": ["rlm-tools"]
    }
  }
}

uvx rlm-tools

git clone https://github.com/stefanoshea/rlm-tools.git
cd rlm-tools
uv sync
uv run rlm-tools

💻 Usage Examples

Basic Usage

The agent can use the sandbox to perform various operations. For example, to search for a pattern in files:

matches = grep("import UIKit")
by_module = {}
for m in matches:
    module = m["file"].split("/")[0]
    by_module.setdefault(module, []).append(m)
for module, ms in sorted(by_module.items(), key=lambda x: -len(x[1]))[:5]:
    print(f"{module}: {len(ms)} files")

📚 Documentation

How It Works

RLM Tools provides three MCP tools, which form the entire API:

The sandbox also provides built-in helpers:

• read_file(path) / read_files(paths) — Read files into variables (cached across calls)
• grep(pattern) / grep_summary(pattern) / grep_read(pattern) — Search
• glob_files(pattern) — Find files by pattern
• tree(path, max_depth) — Directory structure
• llm_query(prompt, context) — Sub-LLM analysis (optional, requires API key)

Variables persist across rlm_execute calls within a session, allowing the agent to build up understanding incrementally without intermediate data filling the context window.

Works With

RLM Tools is a standard MCP server and works with any MCP-compatible client, including Claude Code, Codex, Cursor, and others.

Configuration

Copy .env.example to .env to customize. All settings are optional, and RLM Tools works out of the box with zero config.

Security

The sandbox is read-only and restricted:

• Imports: Safe stdlib only (re, json, collections, math, etc.)
• Builtins: Blocks exec, eval, compile, __import__, breakpoint
• File access: Read-only, scoped to session directory, path traversal blocked
• Execution: Configurable per-call timeout (default 30s)
• Rate limits: Configurable max calls per session

Background

RLM Tools implements an RLM-style exploration loop, keeping raw data in tool-side memory and sending only compact outputs to the model. It is built on the Model Context Protocol.

Development

git clone https://github.com/stefanoshea/rlm-tools.git
cd rlm-tools
uv sync --dev
pytest tests

To run comparative benchmarks (requires a local project checkout):

RLM_EVAL_PROJECT_PATH=/path/to/project pytest evals -q -s

📄 License

This project is licensed under the MIT license.