Skip to main content
Glama
stefanoshea

rlm-tools

by stefanoshea
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

RLM Tools

Your AI coding agent spends most of its token budget just reading your code — not reasoning about it. Every grep, file read, and glob result gets dumped into the conversation. On a large codebase, that's 25-35% of your context (and cost) burned on raw data the model never needed to see.

RLM Tools gives your agent a persistent sandbox to explore code in. Data stays server-side. Only the conclusions come back.

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

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

That's it. Your agent automatically uses the sandbox for exploration. No config, no prompting changes.

What Changes

Without RLM Tools — agent greps for import UIKit, gets 500 matches dumped into context. Reads 10 files, burns all their content as tokens. Context window fills up. Agent forgets what it was doing.

With RLM Tools — agent runs the same exploration in a server-side Python sandbox. Data stays in sandbox memory. Only the print() output enters context:

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")

500 lines of grep results become 5 lines of summary. The agent sees what it needs, nothing more.

Related MCP server: projscan

Real-World Impact

In typical coding workflows: 25-35% context reduction. That means your agent can explore roughly 40-50% more code before hitting context limits.

In heavy exploration tasks (reading many files, broad searches), savings go much further:

Scenario

Standard Tools

RLM Tools

Saved

Grep across full app

40,045 chars

1,644 chars

95.9%

Read 10 large files

1,493,720 chars

13,588 chars

99.1%

Multi-step exploration

136,102 chars

5,285 chars

96.1%

Grep then read matches

340,408 chars

6,022 chars

98.2%

Find all usages of a pattern

13,478 chars

3,691 chars

72.6%

Understand a module

94,745 chars

16,925 chars

82.1%

Full benchmark methodology and reproduction steps: docs/benchmarks.md

How It Works

Three MCP tools. That's the entire API:

Tool

Purpose

rlm_start(path, query)

Open a session on a directory

rlm_execute(session_id, code)

Run Python in the sandbox

rlm_end(session_id)

Close session, free resources

The sandbox 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. The agent can build up understanding incrementally — search, filter, read, analyze — without any intermediate data touching the context window.

Works With

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

JSON MCP config (Cursor, Windsurf, etc.)

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

Direct run

uvx rlm-tools

From source

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

Then point your MCP client to command: uv, args: ["--directory", "/path/to/rlm-tools", "run", "rlm-tools"].

Configuration

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

The core exploration features (read, grep, glob, tree) require no API key. The optional llm_query() helper calls the Anthropic API for semantic analysis within the sandbox — this is the only feature that requires a key.

Variable

Default

Description

ANTHROPIC_API_KEY

—

Required for llm_query() only. Uses Anthropic's API (Claude).

RLM_SUB_MODEL

claude-haiku-4-5-20251001

Claude model used for llm_query()

RLM_MAX_SESSIONS

5

Max concurrent sessions

RLM_SESSION_TIMEOUT

10

Session timeout in minutes

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: keep raw data in tool-side memory, send only compact outputs to the model. Built on the Model Context Protocol.

Development

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

Run comparative benchmarks (requires a local project checkout):

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

License

MIT

Available Tools

3 tools
rlm_endA

End an RLM exploration session and free resources.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesSession ID to end

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions 'free resources' which hints at cleanup, but does not disclose potential side effects, required permissions, or behavior if the session is already ended. Without annotations, more detail would be beneficial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one required parameter, output schema exists), the description is mostly complete. However, it could mention error conditions for invalid session IDs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a description for the only parameter ('Session ID to end'). The tool description adds no extra semantic value beyond that, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('End') and the resource ('RLM exploration session') with the additional benefit of freeing resources. It is distinct from siblings 'rlm_start' and 'rlm_execute'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when the session is no longer needed, but provides no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rlm_executeA

Execute Python in the session sandbox. detail_level controls response payload size (compact, usage, or full).

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesSession ID from rlm_start
codeYesPython code to execute. IMPORTANT: Batch multiple related operations into each call. A good call does: grep -> read top matches -> extract patterns -> print summary. A bad call does just one grep or one read_file. Variables persist between calls.
detail_levelNoResponse payload level: compact=stdout+error, usage=add usage metrics, full=add variable detailscompact
max_new_variablesNoWhen detail_level=full, cap returned new_variables list to this size

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. The main description only mentions execution and detail_level. The code parameter description adds that variables persist between calls, which is crucial. Still missing details like sandbox limitations, timeouts, or security restrictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is two concise sentences with no redundancy. Parameter descriptions are structured and informative. Every sentence serves a purpose, making the definition efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema existing and full parameter coverage, the description still lacks high-level context about the sandbox environment, Python version, allowed modules, and error handling. The usage advice in code parameter is good but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, giving a baseline of 3. The description adds value beyond schema by explaining the detail_level options and providing usage guidance in the code parameter (batching, persistence), enriching the agent's understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute Python in the session sandbox,' providing a specific verb and resource. It distinguishes from siblings (rlm_start, rlm_end) implicitly, but could be more explicit about the sandbox context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The main description lacks usage guidance, but the code parameter description offers explicit advice on batching operations and variable persistence, helping the agent use the tool effectively. No direct comparison to alternatives is given, but the sibling tools make the execution purpose clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rlm_startB

Start an RLM exploration session. Returns session_id, metadata, limits, and available functions. Set include_guidance=true to include strategy/example coaching text.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path to the directory to explore
queryYesWhat you want to find or analyze
max_output_charsNoMax characters per execute output
max_llm_callsNoMaximum llm_query/llm_query_batched calls for this session
max_execute_callsNoMaximum rlm_execute calls for this session
execution_timeout_secondsNoPer-rlm_execute timeout in seconds
include_guidanceNoInclude strategy/example guidance text in the response (larger payload)
include_metadataNoScan directory and include file counts/types in response (set false for faster startup)

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions return values (session_id, metadata, limits, functions) and the include_guidance flag, but does not disclose side effects, state creation, or access requirements for the directory path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: two sentences with the purpose front-loaded. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and 8 parameters (2 required), the description adequately outlines the tool's purpose and key returns. It could be slightly more complete by mentioning the include_metadata parameter's effect, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description only adds context for the include_guidance parameter, which is minimal. It does not meaningfully augment the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool starts an RLM exploration session. It identifies the resource and action, but does not explicitly differentiate from sibling tools rlm_end and rlm_execute, which are for ending and executing within sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies it's the first step in an RLM workflow, but it does not provide explicit guidance on when to use versus alternatives, nor does it mention prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedrlm_end
    • First observedrlm_execute
    • First observedrlm_start
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct purpose: starting, executing, and ending a session. No overlap.

Naming Consistency5/5

All tools share the 'rlm_' prefix followed by a clear verb (start, execute, end), forming a consistent pattern.

Tool Count5/5

Three tools cover the full session lifecycle efficiently without excess or deficiency.

Completeness5/5

The set provides complete lifecycle coverage for RLM sessions: start, execute, end. No obvious gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers