RLM Code

Run LLM-powered agents in a REPL loop, benchmark them, and compare results.

RLM Code implements the Recursive Language Models (RLM) approach from the 2025 paper release. Instead of stuffing your entire document into the LLM's context window, RLM stores it as a Python variable and lets the LLM write code to analyze it, chunk by chunk, iteration by iteration. This is dramatically more token-efficient for large inputs.

RLM Code wraps this algorithm in an interactive terminal UI with built-in benchmarks, trajectory replay, and observability.

Release v0.1.13

This release expands the experimental native coding agent with live recursive agents. The root agent can start multiple children concurrently, exchange messages with them, collect their results, apply the solution, and run verification under the configured sandbox and approval policy.

• Run concurrent child agents from the persistent Python workspace
• Message, steer, wait for, cancel, and delete child agents
• See the live agent hierarchy and activity in the terminal
• Preserve the complete root-and-child trajectory with stable ancestry
• Replay a hierarchy with rlm-code agent replay <session-id>
• Resume saved sessions with child records, results, supported Python state, and undelivered messages

The native runtime remains experimental. Active children are settled when the RLM Code process exits; background continuation, daemon supervision, and crash recovery are planned for a later release.

Release v0.1.12

This release introduces an experimental native coding-agent workflow for working on a repository from the command line. Give the agent a task and it can inspect the project, edit files, run checks, and show its activity as it works.

• Start coding tasks with rlm-code agent run
• Keep Python variables and working context available between model turns
• Search, read, and update repository files under the selected approval policy
• Run project commands and tests through the configured sandbox
• See Python activity, approvals, effects, usage, and the final result in the terminal
• Cancel long-running work or constrain it with turn and time limits
• Resume a saved root-agent session, including supported Python state

The native coding agent is experimental in v0.1.12. It currently runs one root agent. Concurrent child agents, parent/child messaging, an agent-tree view, and replay or resume of a complete multi-agent hierarchy are not included yet.

Release v0.1.11

This release adds a locally in-distribution harness profile based on the RLM authors' harness generalization work and brings the AI Engineer World's Fair 2026 live probe into the main repository.

• New reference, repo_evidence, and lid Pure RLM profiles
• Repository context selection through mini, evidence, full, and explicit caller contexts
• Opaque root observations, structural-history offloading, decomposition guidance, and sanitized fallback synthesis
• Root/submodel usage attribution and trajectory generalization metrics
• Family/domain/split/length metadata for benchmark cases
• Maintained conference live probe plus an API-key-free 8× length-generalization proof

Example:

/rlm run "Validate pure_rlm_environment.py and cite context, REPL, llm_query, and FINAL evidence" env=pure_rlm steps=6

Locally in-distribution harness generalization

The opt-in lid Pure RLM profile implements the harness pattern from the RLM authors' harness generalization post:

• repository context profiles (mini, evidence, full, or explicit caller context);
• semantic subcall outputs retained in REPL variables instead of root history;
• opaque, constant-shape REPL observations for the root model;
• structural history with automatic offloading to history_N variables;
• a decomposition hint that discourages a single monolithic subcall;
• root/submodel usage attribution; and
• trajectory similarity metrics for cross-family and length-extrapolation evaluation.

Run the offline, API-key-free proof (including a cross-domain 8× length test):

uv run python examples/harness_generalization/demo.py

Use the same profile with a connected model:

/rlm run env=pure_rlm profile=lid context_profile=evidence steps=12 <your task>

See the demo guide for its claims, checks, and limitations.

The maintained AI Engineer World's Fair 2026 talk probe reproduces the live one-root/one-subcall demonstration against the current checkout.

Documentation

Open the full documentation

Install

uv tool install "rlm-code[tui,llm-all]"

This installs rlm-code as a globally available command with its own isolated environment. You get the TUI and all LLM provider clients (OpenAI, Anthropic, Gemini).

Requirements:

• Python 3.11+
• uv (recommended) or pip
• one model route (BYOK API key or local server like Ollama)
• one secure execution backend (Docker recommended; Monty optional)

Don't have uv? Install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Alternative: install with pip

pip install rlm-code[tui,llm-all]

Quick Start

1. Launch

mkdir -p ~/my-project && cd ~/my-project
rlm-code

This opens the terminal UI. You'll see a chat input at the bottom and tabs across the top.

2. Connect to an LLM

Type one of these in the chat input:

/connect anthropic claude-opus-4-6

or

/connect openai gpt-5.3-codex

or

/connect gemini gemini-2.5-flash

or for a free local model via Ollama:

/connect ollama llama3.2

You need the matching API key in your environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) or in a .env file in your project directory. Ollama needs no key, just a running Ollama server.

Follow the interactive path with just /connect command instead: Check it worked:

/status

3. Run your first RLM task

/rlm run "Write a Python function that finds the longest common subsequence of two strings"

This starts the RLM loop: the LLM writes code in a sandboxed REPL, executes it, sees the output, writes more code, and iterates until it calls FINAL(answer) with the result.

4. Run a benchmark

Benchmarks let you measure how well a model performs on a set of tasks:

/rlm bench preset=pure_rlm_smoke

This runs 3 test cases through the RLM loop and scores the results.

See all available benchmarks:

/rlm bench list

5. View results

Use the Research tab (Ctrl+5) for live benchmark and trajectory views. After at least two benchmark runs, export a compare report:

/rlm bench report candidate=latest baseline=previous format=markdown

6. Replay a session step-by-step

/rlm status
/rlm replay <run_id>

Walk through the last run one step at a time, see what code the LLM wrote, what output it got, and what it did next.

7. Use the native coding agent (experimental)

Run the command from the repository you want the agent to work on:

rlm-code agent run "fix the failing tests and add a regression test" \
  --repository . \
  --sandbox docker \
  --approval confirm-high

Pass --model provider/model to select a model explicitly, or omit it to use the default model in your project configuration. The terminal displays the session ID, Python activity, repository and command actions, approvals, usage, and the final response.

To continue a saved root-agent session, use the session ID shown by the earlier run:

rlm-code agent run "continue the task and rerun verification" \
  --repository . \
  --sandbox docker \
  --resume <session-id>

Docker is the recommended sandbox. Apple Container is also suitable when configured. The local runtime is intended only for development and does not provide a container isolation boundary. Use --approval confirm-high (the default) or --approval confirm-all for interactive control. Use --approval auto only in a trusted repository and environment.

The agent can now run concurrent children, communicate with them, and preserve their hierarchy in the session trajectory. Replay a complete saved hierarchy with:

rlm-code agent replay <session-id> --repository .

Active children do not continue running after the RLM Code process exits. Background continuation and automatic crash recovery remain future work.

Existing TUI coding harness

RLM Code can also be used as a coding-agent harness in the TUI. It provides a minimal workflow for steering a model to inspect and update code.

/harness tools
/harness run "fix failing tests and add regression test" steps=8 mcp=on

ACP is supported too:

/connect acp
/harness run "implement feature X with tests" steps=8 mcp=on

Notes:

• In Local/BYOK connection modes, likely coding prompts in chat can auto-route to harness.
• In ACP mode, auto-routing is intentionally off; use /harness run ... explicitly.

8. CodeMode with UTCP and Cloudflare MCP

Use these server entries in your project rlm_config.yaml:

mcp_servers:
  utcp-codemode:
    name: utcp-codemode
    description: "Local CodeMode MCP bridge"
    enabled: true
    auto_connect: false
    timeout_seconds: 30
    retry_attempts: 3
    transport:
      type: stdio
      command: npx
      args:
        - "@utcp/code-mode-mcp"

  cloudflare-codemode:
    name: cloudflare-codemode
    description: "Cloudflare MCP via remote bridge"
    enabled: true
    auto_connect: false
    timeout_seconds: 30
    retry_attempts: 3
    transport:
      type: stdio
      command: npx
      args:
        - "mcp-remote"
        - "https://mcp.cloudflare.com/mcp"

UTCP path (native CodeMode in current release):

/mcp-connect utcp-codemode
/mcp-tools utcp-codemode
/harness run "analyze this repo, find TODO/FIXME, and create report.json" steps=3 mcp=on strategy=codemode mcp_server=utcp-codemode

Cloudflare path (recommended strategy today):

/mcp-connect cloudflare-codemode
/mcp-tools cloudflare-codemode
/harness run "list available tools and run one safe read-only action, then summarize in 3 bullets" steps=3 mcp=on strategy=tool_call mcp_server=cloudflare-codemode

Notes:

• On first Cloudflare connect, mcp-remote may ask for interactive authentication.
• In this release, strategy=codemode expects the search_tools + call_tool_chain bridge contract.
• If a remote MCP server exposes a different tool contract, use strategy=tool_call.

How the RLM Loop Works

Traditional LLM usage: paste your document into the prompt, ask a question, hope the model doesn't lose details in the middle.

RLM approach:

1. Your document is stored as a Python variable context in a REPL
2. The LLM writes code to process it (e.g., len(context), context[:5000], context.split('\n'))
3. The code runs, and the LLM sees the output
4. The LLM writes more code based on what it learned
5. Repeat until the LLM calls FINAL("here is my answer")

This means the LLM can handle documents much larger than its context window, because it reads them in chunks through code rather than all at once through the prompt.

What This Is (and Is Not)

RLM Code is:

• a research playground for recursive/model-assisted coding workflows
• a benchmarking and replay tool for reproducible experiments

RLM Code is not:

• a no-config consumer chat app
• guaranteed cheap (recursive runs can be expensive)
• safe to run with unrestricted execution settings

Use secure backend defaults (/sandbox profile secure) for normal use.

Key Commands

Command	What it does
/connect <provider> <model>	Connect to an LLM
/model	Interactive model picker
/status	Show connection status
/sandbox profile secure	Apply secure sandbox defaults (Docker-first + strict pure RLM)
/rlm run "<task>"	Run a task through the RLM loop
/rlm bench preset=<name>	Run a benchmark preset
/rlm bench list	List available benchmarks
/rlm bench compare	Compare latest benchmark run with previous run
/rlm abort [run_id|all]	Cancel active run(s) cooperatively
/harness run "<task>"	Run tool-using coding harness loop
/rlm replay	Step through the last run
/rlm chat "<question>"	Ask the LLM a question about your project
/help	Show all available commands

Cost and Safety Guardrails

Start bounded:

/rlm run "small scoped task" steps=4 timeout=30 budget=60

For benchmarks, start with small limits:

/rlm bench preset=dspy_quick limit=1

If a run is going out of hand:

/rlm abort all

What You Can Do With It

• Analyze large documents: Feed in a 500-page PDF and ask questions, then the LLM reads it in chunks via code
• Compare models: Run the same benchmark with different providers and see who scores higher
• Compare paradigms: Test Pure RLM vs CodeAct vs Traditional approaches on the same task
• Debug agent behavior: Replay any run step-by-step to see exactly what the agent did
• Track experiments: Every run is logged with metrics, tokens used, and trajectory

Supported LLM Providers

Provider	Latest Models	Setup
Anthropic	claude-opus-4-6, claude-sonnet-4-5-20250929	ANTHROPIC_API_KEY env var
OpenAI	gpt-5.3-codex, gpt-5.2-pro	OPENAI_API_KEY env var
Google	gemini-2.5-pro, gemini-2.5-flash	GEMINI_API_KEY or GOOGLE_API_KEY env var
Ollama	llama3.2, qwen2.5-coder:7b	Running Ollama server at localhost:11434

Configuration

Create an rlm_config.yaml in your project directory to customize settings:

name: my-project

models:
  openai_api_key: null
  openai_model: gpt-5.3-codex

default_model: gpt-5.3-codex

sandbox:
  runtime: docker
  superbox_profile: secure
  superbox_auto_fallback: true
  superbox_fallback_runtimes: [docker, daytona, e2b]
  pure_rlm_backend: docker
  pure_rlm_strict: true
  pure_rlm_allow_unsafe_exec: false

rlm:
  default_benchmark_preset: dspy_quick
  benchmark_pack_paths: []

Or generate a full sample config:

/init

Development Setup

git clone https://github.com/SuperagenticAI/rlm-code.git
cd rlm-code
uv sync --all-extras
uv run pytest

Project Structure

rlm_code/
  rlm/              # Core RLM engine (runner, environments, policies)
  ui/               # Terminal UI (Textual-based TUI)
  mcp/              # MCP server for tool integration
  models/           # LLM provider adapters
  sandbox/          # Sandboxed code execution
  harness/          # Tool-using coding harness (/harness)

Resources

Full docs: https://superagenticai.github.io/rlm-code/

Contributing

See CONTRIBUTING.md.

License

Apache-2.0

---

Brought to You by Superagentic AI