Claude code setup as an RLM scaffhold Implemented by Brainqub3
Claude code setup as an RLM scaffhold Implemented by Brainqub3
A minimal implementation of Recursive Language Models (RLM) using Claude Code as the scaffold. Implemented by Brainqub3.
This repository provides a basic RLM setup that enables Claude to process documents and contexts that exceed typical context window limits. It implements the core RLM pattern where a root language model orchestrates sub-LLM calls over chunks of a large document.
This is a basic implementation of the RLM paper. For the full research, see:
Recursive Language Models Alex L. Zhang, Tim Kraska, Omar Khattab MIT CSAIL arXiv:2512.24601
Abstract: RLMs treat long prompts as part of an external environment and allow the LLM to programmatically examine, decompose, and recursively call itself over snippets of the prompt. RLMs can handle inputs up to two orders of magnitude beyond model context windows.
This implementation follows the paper's Algorithm 1 and maps it onto Claude Code's primitives as follows:
| RLM Concept | Implementation | Model |
|---|---|---|
| Root LLM | Main Claude Code conversation (never reads the full context) | your session model (e.g. Opus) |
| External environment | Persistent Python REPL (rlm_repl.py) holding the context as a variable |
Python |
Sub-LM llm_query (leaf) |
Nested headless Claude Code (claude -p, tools off), called programmatically from REPL code |
Haiku (default) |
Recursive rlm_query (depth>1) |
Nested headless Claude Code with bash + this skill on (its own REPL) | configurable |
The key fidelity point from the paper: the root model does not read the context
into its window. It only sees metadata and truncated stdout, and answers by
writing REPL code that programmatically sub-queries the context in chunks
(llm_query / llm_query_map), aggregates with plain Python, and returns the
answer via FINAL(...) / FINAL_VAR(...). The sub-LM is a nested claude -p
process that reuses your existing login — no Anthropic API key or SDK. The split
that makes it work: the LLM does the semantics (classify/extract/summarise) and
Python does the arithmetic (count/aggregate/format).
This repo includes a root-level helper that lets Claude Code, another Codex session, or any other CLI agent call non-interactive Codex from the repository root:
./codex-headless "summarize this repo and identify the next implementation step"On Windows:
.\codex-headless.ps1 "summarize this repo and identify the next implementation step"
.\codex-headless.cmd "summarize this repo and identify the next implementation step"The helper runs codex exec with gpt-5.5, extra-high reasoning
(model_reasoning_effort="xhigh"), workspace-write sandboxing,
approval_policy=never, and ephemeral session storage. It also accepts normal
codex exec flags, for example:
./codex-headless --json "inspect the git diff and return a risk summary"Clone this repository
git clone https://github.com/Brainqub3/claude_code_RLM.git
cd claude_code_RLMStart Claude Code in the repository directory
claudeRun the RLM skill
/rlmFollow the prompts - The skill will ask for:
The RLM workflow will then:
llm_queryFINAL / FINAL_VARexec block as a standalone Python replay step under
.claude/rlm_runs//By default, rlm_repl.py init creates an audit replay package:
.claude/rlm_runs//
|-- manifest.json
|-- replay_all.py
|-- runtime/
`-- steps/
|-- step_0001.py
|-- step_0001.json
|-- step_0001.stdout.txt
`-- step_0001.stderr.txtRun all saved steps from a clean replay checkpoint:
python .claude/rlm_runs//replay_all.pyThe generated scripts recreate the REPL globals (content, grep,
llm_query_map, FINAL_VAR, persisted variables, etc.) and write replay state to
replay_state.pkl, separate from the live .claude/rlm_state/state.pkl. They call
llm_query live, so LLM outputs are not guaranteed to match the original run.
Useful knobs:
python .claude/skills/rlm/scripts/rlm_repl.py init context.txt --audit-run-id my_run
python .claude/skills/rlm/scripts/rlm_repl.py init context.txt --audit-dir audit_runs
python .claude/skills/rlm/scripts/rlm_repl.py init context.txt --no-auditWhen using RLM to process large context files, it is recommended to save them in a dedicated context/ folder within this project directory. This keeps your working files organized and separate from the RLM implementation code.
mkdir context
# Place your large documents here, e.g.:
# context/my_large_document.txt
# context/codebase_dump.pyThis project is not intended for production use.
If you plan to run Claude Code in --dangerously-skip-permissions mode:
Recommended: Create a dedicated, isolated working directory specifically for RLM tasks when using dangerous mode:
# Example: Create an isolated workspace
mkdir ~/rlm-workspace
cd ~/rlm-workspace
git clone https://github.com/Brainqub3/claude_code_RLM.git
cd claude_code_RLM.
├── CLAUDE.md # Project instructions for Claude Code
├── .claude/
│ └── skills/
│ └── rlm/
│ ├── SKILL.md # RLM skill definition (the root's procedure)
│ ├── scripts/
│ │ └── rlm_repl.py # Persistent Python REPL + llm_query/rlm_query
│ └── eval/ # OOLONG long-context eval (score vs. the paper)
├── context/ # Recommended location for large context files
└── README.mdNote: earlier versions used a
.claude/agents/rlm-subcall.mdTask subagent as the sub-LM. The faithful implementation calls the sub-LM programmatically from REPL code (claude -p), so that subagent is no longer used.
See LICENSE for details.
No open issues yet, or sync has not completed.