Skip to content
Back to search

rlm-claude-code

MarketplaceWorks with Claude CodeGitHub

Marketplace for RLM-Claude-Code: Recursive Language Model with Go hook binaries, cross-plugin event system, and intelligent multi-provider routing

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rand--rlm-claude-code/badge.svg)](/listings/rand--rlm-claude-code)

HTML

<a href="/listings/rand--rlm-claude-code"><img src="/api/listings/rand--rlm-claude-code/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

- **Python 3.12+**: `brew install python@3.12` or [python.org](https://python.org) - **uv** (Python package manager): `curl -LsSf https://astral.sh/uv/install.sh | sh` - **Rust 1.75+** (for dev builds): `rustup update stable` — not needed if installing from pre-built wheels

Installation (from pre-built wheel)

Download the wheel for your platform from [GitHub Releases](https://github.com/rand/rlm-claude-code/releases), then:

pip install rlm_claude_code-*.whl

Installation (from source, requires Rust)

# Clone with submodules (rlm-core is bundled)
git clone --recurse-submodules https://github.com/rand/rlm-claude-code.git
cd rlm-claude-code

# Build and install (compiles rlm-core Rust library)
maturin develop --release

# Install Python dependencies
uv sync --all-extras

# Verify
python -c "import rlm_core; print(rlm_core.version())"
uv run pytest tests/ -v

As a Claude Code Plugin

Step 1: Install the Plugin

# Add the marketplace (one-time setup)
claude plugin marketplace add github:rand/rlm-claude-code

# Install the plugin
claude plugin install rlm-claude-code@rlm-claude-code

Step 2: Set Up the Plugin Environment

The plugin includes rlm-core (bundled via maturin). After installation:

# Navigate to the plugin directory (adjust version number as needed)
PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
cd "$PLUGIN_DIR"

# Create venv and install (includes rlm-core)
uv venv && uv sync

# Verify rlm-core is available
"$PLUGIN_DIR/.venv/bin/python" -c "import rlm_core; print('rlm_core OK:', rlm_core.version())"

Step 3: Verify Installation

Restart Claude Code. You should see "RLM initialized" on startup.

Test the hooks manually:

PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
"$PLUGIN_DIR/.venv/bin/python" "$PLUGIN_DIR/scripts/init_rlm.py"
# Should print: RLM initialized

Updating the Plugin

When updating, you'll need to re-create the venv:

claude plugin update rlm-claude-code@rlm-claude-code

# Re-setup the new version
PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
cd "$PLUGIN_DIR" && uv venv && uv sync

# rlm-core is bundled — no extra linking needed

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "rlm-claude-code",
  3. "description": "Marketplace for RLM-Claude-Code: Recursive Language Model with Go hook binaries, cross-plugin event system, and intelligent multi-provider routing",
  4. "owner": {
  5. "name": "rand",
  6. "url": "https://github.com/rand"
  7. },
  8. "plugins": [
  9. {
  10. "name": "rlm-claude-code",
  11. "source": "./",
  12. "description": "Recursive Language Model integration for Claude Code - Go binary hooks (~5ms startup), cross-plugin event coordination (DP/RLM), version-aware config migration, and intelligent multi-provider routing",
  13. "version": "0.7.4"
  14. }
  15. ]
  16. }
README.md · README · 700 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # RLM-Claude-Code
  2. Transform Claude Code into a Recursive Language Model (RLM) agent with intelligent orchestration, unbounded context handling, persistent memory, and REPL-based decomposition.
  3. **rlm-core integration**: This project bundles [rlm-core](https://github.com/rand/loop) as a required dependency, providing shared Rust-based implementations with [recurse](https://github.com/rand/recurse). rlm-core provides 10-50x faster pattern classification via PyO3 bindings. Pre-built wheels are available for common platforms.
  4. ## What is RLM?
  5. RLM (Recursive Language Model) enables Claude to handle arbitrarily large contexts by decomposing complex tasks into smaller sub-queries. Instead of processing 500K tokens at once, RLM lets Claude:
  6. - **Peek** at context structure before deep analysis
  7. - **Search** using patterns to narrow focus
  8. - **Partition** large contexts and process in parallel via map-reduce
  9. - **Recurse** with sub-queries for verification
  10. - **Remember** facts and experiences across sessions
  11. This results in better accuracy on complex tasks while optimizing cost through intelligent model selection.
  12. ---
  13. ## Quick Start
  14. ### Prerequisites
  15. - **Python 3.12+**: `brew install python@3.12` or [python.org](https://python.org)
  16. - **uv** (Python package manager): `curl -LsSf https://astral.sh/uv/install.sh | sh`
  17. - **Rust 1.75+** (for dev builds): `rustup update stable` — not needed if installing from pre-built wheels
  18. ### Installation (from pre-built wheel)
  19. Download the wheel for your platform from [GitHub Releases](https://github.com/rand/rlm-claude-code/releases), then:
  20. ```bash
  21. pip install rlm_claude_code-*.whl
  22. ```
  23. ### Installation (from source, requires Rust)
  24. ```bash
  25. # Clone with submodules (rlm-core is bundled)
  26. git clone --recurse-submodules https://github.com/rand/rlm-claude-code.git
  27. cd rlm-claude-code
  28. # Build and install (compiles rlm-core Rust library)
  29. maturin develop --release
  30. # Install Python dependencies
  31. uv sync --all-extras
  32. # Verify
  33. python -c "import rlm_core; print(rlm_core.version())"
  34. uv run pytest tests/ -v
  35. ```
  36. ### As a Claude Code Plugin
  37. #### Step 1: Install the Plugin
  38. ```bash
  39. # Add the marketplace (one-time setup)
  40. claude plugin marketplace add github:rand/rlm-claude-code
  41. # Install the plugin
  42. claude plugin install rlm-claude-code@rlm-claude-code
  43. ```
  44. #### Step 2: Set Up the Plugin Environment
  45. The plugin includes rlm-core (bundled via maturin). After installation:
  46. ```bash
  47. # Navigate to the plugin directory (adjust version number as needed)
  48. PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
  49. cd "$PLUGIN_DIR"
  50. # Create venv and install (includes rlm-core)
  51. uv venv && uv sync
  52. # Verify rlm-core is available
  53. "$PLUGIN_DIR/.venv/bin/python" -c "import rlm_core; print('rlm_core OK:', rlm_core.version())"
  54. ```
  55. #### Step 3: Verify Installation
  56. Restart Claude Code. You should see "RLM initialized" on startup.
  57. Test the hooks manually:
  58. ```bash
  59. PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
  60. "$PLUGIN_DIR/.venv/bin/python" "$PLUGIN_DIR/scripts/init_rlm.py"
  61. # Should print: RLM initialized
  62. ```
  63. #### Updating the Plugin
  64. When updating, you'll need to re-create the venv:
  65. ```bash
  66. claude plugin update rlm-claude-code@rlm-claude-code
  67. # Re-setup the new version
  68. PLUGIN_DIR=~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/$(ls ~/.claude/plugins/cache/rlm-claude-code/rlm-claude-code/ | sort -V | tail -1)
  69. cd "$PLUGIN_DIR" && uv venv && uv sync
  70. # rlm-core is bundled — no extra linking needed
  71. ```
  72. ---
  73. ## Architecture
  74. ```
  75. User Query
  76. │
  77. ▼
  78. ┌─────────────────────────────────────────────────────────┐
  79. │ INTELLIGENT ORCHESTRATOR │
  80. │ ┌───────────────────┐ ┌───────────────────────────┐ │
  81. │ │ Complexity │ │ Orchestration Decision │ │
  82. │ │ Classifier │ │ • Activate RLM? │ │
  83. │ │ • Token count │──►│ • Which model tier? │ │
  84. │ │ • Cross-file refs │ │ • Depth budget (0-3)? │ │
  85. │ │ • Query patterns │ │ • Tool access level? │ │
  86. │ └───────────────────┘ └───────────────────────────┘ │
  87. └─────────────────────────────────────────────────────────┘
  88. │
  89. ▼ (if RLM activated)
  90. ┌─────────────────────────────────────────────────────────┐
  91. │ RLM EXECUTION ENGINE │
  92. │ │
  93. │ ┌──────────────────┐ ┌──────────────────────────┐ │
  94. │ │ Context Manager │ │ REPL Sandbox │ │
  95. │ │ • Externalize │───►│ • peek(), search() │ │
  96. │ │ conversation │ │ • llm(), llm_batch() │ │
  97. │ │ • files, tools │ │ • map_reduce() │ │
  98. │ └──────────────────┘ │ • find_relevant() │ │
  99. │ │ • memory_*() functions │ │
  100. │ └──────────────────────────┘ │
  101. │ │ │
  102. │ ▼ │
  103. │ ┌──────────────────┐ ┌──────────────────────────┐ │
  104. │ │ Recursive Handler│ │ Tool Bridge │ │
  105. │ │ • Depth ≤ 3 │ │ • bash, read, grep │ │
  106. │ │ • Model cascade │ │ • Permission control │ │
  107. │ │ • Sub-query spawn│ │ • Blocked commands │ │
  108. │ └──────────────────┘ └──────────────────────────┘ │
  109. └─────────────────────────────────────────────────────────┘
  110. │
  111. ▼
  112. ┌─────────────────────────────────────────────────────────┐
  113. │ PERSISTENCE LAYER │
  114. │ │
  115. │ ┌──────────────────┐ ┌──────────────────────────┐ │
  116. │ │ Memory Store │ │ Reasoning Traces │ │
  117. │ │ • Facts, exps │ │ • Goals, decisions │ │
  118. │ │ • Hyperedges │ │ • Options, outcomes │ │
  119. │ │ • SQLite + WAL │ │ • Decision trees │ │
  120. │ └──────────────────┘ └──────────────────────────┘ │
  121. │ │ │ │
  122. │ ▼ ▼ │
  123. │ ┌──────────────────┐ ┌──────────────────────────┐ │
  124. │ │ Memory Evolution │ │ Strategy Cache │ │
  125. │ │ task → session │ │ • Learn from success │ │
  126. │ │ session → long │ │ • Similarity matching │ │
  127. │ │ decay → archive │ │ • Suggest strategies │ │
  128. │ └──────────────────┘ └──────────────────────────┘ │
  129. └─────────────────────────────────────────────────────────┘
  130. │
  131. ▼
  132. ┌─────────────────────────────────────────────────────────┐
  133. │ BUDGET & TRAJECTORY │
  134. │ • Token tracking per component │
  135. │ • Cost limits with alerts │
  136. │ • Streaming trajectory output │
  137. │ • JSON export for analysis │
  138. └─────────────────────────────────────────────────────────┘
  139. │
  140. ▼
  141. Final Answer
  142. ```
  143. ---
  144. ## rlm-core Integration
  145. RLM-Claude-Code bundles [rlm-core](https://github.com/rand/loop), a Rust library providing high-performance pattern classification, memory storage, and trajectory tracking via PyO3 bindings.
  146. rlm-core is a required dependency — there is no Python fallback mode.
  147. ### Configuration
  148. | Setting | Behavior |
  149. |---------|----------|
  150. | `activation.mode` | `"complexity"` (default), `"always"`, `"never"` |
  151. | `depth.default` | Default recursion depth (default: 2) |
  152. | `depth.max` | Maximum recursion depth (default: 3) |
  153. ### Performance
  154. | Component | Implementation |
  155. |-----------|---------------|
  156. | Pattern Classifier | Rust via PyO3 |
  157. | Trajectory Events | Rust types via PyO3 |
  158. | Memory Store | rlm_core SQLite (nodes/edges) + Python SQLite (auxiliary tables) |
  159. ### Benefits
  160. - **Consistency**: Same classification logic as recurse TUI
  161. - **Performance**: Rust pattern matching is significantly faster
  162. - **Shared Codebase**: Bug fixes benefit both projects
  163. ### Python Bindings Usage
  164. ```python
  165. from src.complexity_classifier import should_activate_rlm, extract_complexity_signals
  166. from src.types import SessionContext, Message, MessageRole
  167. # Delegates to rlm_core.PatternClassifier
  168. ctx = SessionContext(messages=[Message(role=MessageRole.USER, content="test")])
  169. signals = extract_complexity_signals("Find security vulnerabilities", ctx)
  170. activate, reason = should_activate_rlm("Find security vulnerabilities", ctx)
  171. ```
  172. ---
  173. ## Core Components
  174. ### REPL Environment
  175. The REPL provides a sandboxed Python environment for context manipulation:
  176. **Context Variables:**
  177. - `conversation` - List of message dicts with role and content
  178. - `files` - Dict mapping filenames to content
  179. - `tool_outputs` - List of tool execution results
  180. - `working_memory` - Scratchpad for intermediate results
  181. **Helper Functions:**
  182. | Function | Description |
  183. |----------|-------------|
  184. | `peek(var, start, end)` | View a slice of any context variable |
  185. | `search(var, pattern, regex=False)` | Find patterns in context |
  186. | `summarize(var, max_tokens)` | LLM-powered summarization |
  187. | `llm(query, context, spawn_repl)` | Spawn recursive sub-query |
  188. | `llm_batch([(q1,c1), (q2,c2), ...])` | Parallel LLM calls |
  189. | `map_reduce(content, map_prompt, reduce_prompt, n_chunks)` | Partition and aggregate |
  190. | `find_relevant(content, query, top_k)` | Find most relevant sections |
  191. | `extract_functions(content)` | Parse function definitions |
  192. | `run_tool(tool, *args)` | Safe subprocess (uv, ty, ruff) |
  193. **Memory Functions** (when enabled):
  194. | Function | Description |
  195. |----------|-------------|
  196. | `memory_query(query, limit)` | Search stored knowledge |
  197. | `memory_add_fact(content, confidence)` | Store a fact |
  198. | `memory_add_experience(content, outcome, success)` | Store an experience |
  199. | `memory_get_context(limit)` | Retrieve relevant context |
  200. | `memory_relate(node1, node2, relation)` | Create relationships |
  201. **Available Libraries:**
  202. | Library | Alias | Description |
  203. |---------|-------|-------------|
  204. | `re` | - | Regular expressions |
  205. | `json` | - | JSON encoding/decoding |
  206. | `pydantic` | `BaseModel`, `Field` | Data validation |
  207. | `hypothesis` | `given`, `st` | Property-based testing |
  208. | `cpmpy` | `cp` | Constraint programming |
  209. | `numpy` | `np` | Numerical computing |
  210. | `pandas` | `pd` | DataFrames and analysis |
  211. | `polars` | `pl` | Fast DataFrames |
  212. | `seaborn` | `sns` | Statistical visualization |
  213. ### Memory System
  214. Persistent storage for cross-session learning:
  215. - **Node Types**: facts, experiences, procedures, goals
  216. - **Memory Tiers**: task → session → longterm → archive
  217. - **Session Isolation**: task/session tiers are isolated per terminal; longterm/archive shared (see [docs/session-isolation.md](docs/session-isolation.md))
  218. - **Hyperedges**: N-ary relationships with typed roles
  219. - **Storage**: SQLite with WAL mode for concurrent access
  220. ```python
  221. from src import MemoryStore, MemoryEvolution
  222. # Create and use memory
  223. store = MemoryStore(db_path="~/.claude/rlm-memory.db")
  224. fact_id = store.create_node(
  225. node_type="fact",
  226. content="This project uses FastAPI",
  227. confidence=0.9,
  228. )
  229. # Evolve memory through tiers
  230. evolution = MemoryEvolution(store)
  231. evolution.consolidate(task_id="current-task") # task → session
  232. evolution.promote(session_id="current-session") # session → longterm
  233. evolution.decay(days_threshold=30) # longterm → archive
  234. ```
  235. ### Reasoning Traces
  236. Track decision-making for transparency and debugging:
  237. ```python
  238. from src import ReasoningTraces
  239. traces = ReasoningTraces(store)
  240. # Create goal and decision tree
  241. goal_id = traces.create_goal("Implement user authentication")
  242. decision_id = traces.create_decision(goal_id, "Choose auth strategy")
  243. # Track options considered
  244. jwt_option = traces.add_option(decision_id, "Use JWT tokens")
  245. session_option = traces.add_option(decision_id, "Use session cookies")
  246. # Record choice and reasoning
  247. traces.choose_option(decision_id, jwt_option)
  248. traces.reject_option(decision_id, session_option, "JWT better for API")
  249. # Get full decision tree
  250. tree = traces.get_decision_tree(goal_id)
  251. ```
  252. ### Budget Tracking
  253. Granular cost control with configurable limits:
  254. ```python
  255. from src import EnhancedBudgetTracker, BudgetLimits
  256. tracker = EnhancedBudgetTracker()
  257. tracker.set_limits(BudgetLimits(
  258. max_cost_per_task=5.0,
  259. max_recursive_calls=10,
  260. max_depth=3,
  261. ))
  262. # Check before expensive operations
  263. allowed, reason = tracker.can_make_llm_call()
  264. if not allowed:
  265. print(f"Budget exceeded: {reason}")
  266. # Get detailed metrics
  267. metrics = tracker.get_metrics()
  268. print(f"Cost: ${metrics.total_cost_usd:.2f}")
  269. print(f"Depth: {metrics.max_depth_reached}")
  270. print(f"Calls: {metrics.sub_call_count}")
  271. ```
  272. ---
  273. ## Using RLM
  274. ### Slash Commands
  275. | Command | Description |
  276. |---------|-------------|
  277. | `/rlm` | Show current status |
  278. | `/rlm on` | Enable RLM for this session |
  279. | `/rlm off` | Disable RLM mode |
  280. | `/rlm status` | Full configuration display |
  281. | `/rlm mode <fast\|balanced\|thorough>` | Set execution mode |
  282. | `/rlm depth <0-3>` | Set max recursion depth |
  283. | `/rlm budget $X` | Set session cost limit |
  284. | `/rlm model <opus\|sonnet\|haiku\|auto>` | Force model selection |
  285. | `/rlm tools <none\|repl\|read\|full>` | Set sub-LLM tool access |
  286. | `/rlm verbosity <minimal\|normal\|verbose\|debug>` | Set output detail |
  287. | `/rlm reset` | Reset to defaults |
  288. | `/rlm save` | Save preferences to disk |
  289. | `/simple` | Bypass RLM for current query |
  290. | `/trajectory <file>` | Analyze a trajectory file |
  291. | `/test` | Run test suite |
  292. | `/bench` | Run benchmarks |
  293. | `/code-review` | Review code changes |
  294. ### Execution Modes
  295. | Mode | Depth | Model | Tools | Best For |
  296. |------|-------|-------|-------|----------|
  297. | `fast` | 1 | Haiku | REPL only | Quick questions, iteration |
  298. | `balanced` | 2 | Sonnet | Read-only | Most tasks (default) |
  299. | `thorough` | 3 | Opus | Full access | Complex debugging, architecture |
  300. ### Auto-Activation
  301. RLM automatically activates when it detects:
  302. - **Large context**: >80K tokens in conversation
  303. - **Cross-file reasoning**: Questions spanning multiple files
  304. - **Complex debugging**: Stack traces, error analysis
  305. - **Architecture questions**: System design, refactoring patterns
  306. Force activation with `/rlm on` or bypass with `/simple`.
  307. ---
  308. ## Configuration
  309. ### Config File
  310. RLM stores configuration at `~/.claude/rlm-config.json`:
  311. ```json
  312. {
  313. "activation": {
  314. "mode": "complexity",
  315. "fallback_token_threshold": 80000
  316. },
  317. "depth": {
  318. "default": 2,
  319. "max": 3
  320. },
  321. "trajectory": {
  322. "verbosity": "normal",
  323. "streaming": true
  324. }
  325. }
  326. ```
  327. | Key | Type | Description |
  328. |-----|------|-------------|
  329. | `activation.mode` | string | `"micro"`, `"complexity"`, `"always"`, `"manual"` |
  330. | `depth.default` | int | Default recursion depth (1-3) |
  331. | `trajectory.verbosity` | string | `"minimal"`, `"normal"`, `"verbose"`, `"debug"` |
  332. ### Environment Variables
  333. | Variable | Purpose |
  334. |----------|---------|
  335. | `ANTHROPIC_API_KEY` | Anthropic API access (uses Claude Code's key) |
  336. | `OPENAI_API_KEY` | OpenAI API access (optional, for GPT models) |
  337. | `RLM_CONFIG_PATH` | Custom config file location |
  338. | `RLM_DEBUG` | Enable debug logging |
  339. ---
  340. ## Hooks
  341. ### Go Binary Hooks (v0.6.0+)
  342. As of v0.6.0, RLM uses compiled Go binaries for hook execution, reducing startup latency from ~500ms (Python) to ~5ms. The three primary hooks are:
  343. | Hook | Binary | Purpose |
  344. |------|--------|---------|
  345. | `SessionStart` | `session-init` | Initialize RLM environment, emit `session.started` event |
  346. | `UserPromptSubmit` | `complexity-check` | Decide if RLM should activate, responds to DP phases |
  347. | `Stop` | `trajectory-save` | Save trajectory and emit `session.ended` event |
  348. Prompt-based hooks (no binary needed) handle context sync, output capture, and pre-compaction.
  349. #### Cross-Plugin Event System
  350. Hooks emit and consume events via `~/.claude/events/`, enabling coordination between plugins (e.g., DP and RLM). All event types have JSON Schema definitions. Python helpers in `src/events/` provide emit/consume APIs.
  351. #### Config Migration
  352. v0.6.0 introduces a V2 config format. Existing V1 configs are automatically migrated on first run, preserving user customizations.
  353. #### Legacy Fallback
  354. To use the original Python hook scripts:
  355. ```bash
  356. export RLM_USE_LEGACY_HOOKS=1
  357. ```
  358. Legacy scripts are located in `scripts/legacy/`.
  359. ### Legacy Hook Reference
  360. The original Python hooks (now in `scripts/legacy/`):
  361. | Hook | Script | Purpose |
  362. |------|--------|---------|
  363. | `SessionStart` | `init_rlm.py` | Initialize RLM environment |
  364. | `UserPromptSubmit` | `check_complexity.py` | Decide if RLM should activate |
  365. | `PreToolUse` | `sync_context.py` | Sync tool context with RLM state |
  366. | `PostToolUse` | `capture_output.py` | Capture tool output for context |
  367. | `PreCompact` | `externalize_context.py` | Externalize before compaction |
  368. | `Stop` | `save_trajectory.py` | Save trajectory on session end |
  369. ### Hook Setup (Important!)
  370. Claude Code plugins register hooks in `hooks/hooks.json`, but these need to be merged into your global `~/.claude/settings.json` to take effect.
  371. **After installing or updating this plugin, run:**
  372. ```bash
  373. python3 ~/.claude/scripts/merge-plugin-hooks.py
  374. ```
  375. If you don't have the merge script, create it:
  376. ```bash
  377. mkdir -p ~/.claude/scripts
  378. curl -o ~/.claude/scripts/merge-plugin-hooks.py \
  379. https://raw.githubusercontent.com/rand/rlm-claude-code/main/scripts/merge-plugin-hooks.py
  380. ```
  381. ### Hook Path Design
  382. This plugin uses `${CLAUDE_PLUGIN_ROOT}` variable and `.venv/bin/python` (not `uv run`) to ensure hooks work correctly:
  383. - **`${CLAUDE_PLUGIN_ROOT}`** - Expands to the plugin's install path, ensuring hooks work after updates
  384. - **`.venv/bin/python`** - Direct venv Python, avoiding `uv run` sandbox issues on macOS
  385. ### Verifying Hooks
  386. Check hooks are correctly registered:
  387. ```bash
  388. # See which hooks are active
  389. cat ~/.claude/settings.json | jq '.hooks.SessionStart'
  390. # Verify paths point to current version
  391. cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["rlm-claude-code@rlm-claude-code"][0].version'
  392. ```
  393. If hook paths don't match the installed version, re-run the merge script.
  394. ### Troubleshooting Hooks
  395. **"RLM not initializing"**
  396. 1. Run `python3 ~/.claude/scripts/merge-plugin-hooks.py`
  397. 2. Restart Claude Code
  398. 3. Check: `cat ~/.claude/settings.json | jq '.hooks.SessionStart'`
  399. **Hooks pointing to old version**
  400. - This happens after plugin updates
  401. - Run `python3 ~/.claude/scripts/merge-plugin-hooks.py` after each update
  402. **macOS sandbox errors with uv**
  403. - This plugin already uses `.venv/bin/python` to avoid this issue
  404. - If you see `SCDynamicStore` errors, verify hooks don't use `uv run`
  405. ---
  406. ## Development
  407. ### Setup
  408. ```bash
  409. git clone https://github.com/rand/rlm-claude-code.git
  410. cd rlm-claude-code
  411. # Install all dependencies
  412. uv sync --all-extras
  413. # Run tests (3000+ tests)
  414. uv run pytest tests/ -v
  415. # Type check
  416. uv run ty check src/
  417. # Lint and format
  418. uv run ruff check src/ --fix
  419. uv run ruff format src/
  420. ```
  421. ### Project Structure
  422. ```
  423. rlm-claude-code/
  424. ├── src/
  425. │ ├── orchestrator.py # Main RLM loop
  426. │ ├── intelligent_orchestrator.py # Claude-powered decisions
  427. │ ├── auto_activation.py # Complexity-based activation
  428. │ ├── context_manager.py # Context externalization
  429. │ ├── repl_environment.py # Sandboxed Python REPL
  430. │ ├── recursive_handler.py # Sub-query management
  431. │ ├── memory_store.py # Persistent memory (SQLite)
  432. │ ├── memory_evolution.py # Memory tier management
  433. │ ├── reasoning_traces.py # Decision tree tracking
  434. │ ├── enhanced_budget.py # Cost tracking and limits
  435. │ ├── trajectory.py # Event logging
  436. │ ├── trajectory_analysis.py # Strategy extraction
  437. │ ├── strategy_cache.py # Learn from success
  438. │ ├── tool_bridge.py # Controlled tool access
  439. │ └── ...
  440. ├── tests/
  441. │ ├── unit/ # Unit tests
  442. │ ├── integration/ # Integration tests
  443. │ ├── property/ # Hypothesis property tests
  444. │ └── security/ # Security tests
  445. ├── scripts/ # Hook scripts
  446. ├── hooks/ # hooks.json
  447. ├── commands/ # Slash command definitions
  448. └── docs/ # Documentation
  449. ```
  450. ### Running Tests
  451. The test suite has 3,200+ tests including property-based tests (Hypothesis) and benchmarks.
  452. **Quick iteration** (~30 seconds):
  453. ```bash
  454. # Fast mode - 10 examples per property test
  455. HYPOTHESIS_PROFILE=fast uv run pytest tests/unit/ -v
  456. ```
  457. **Standard development** (default, ~2-3 minutes):
  458. ```bash
  459. # Dev mode - 50 examples per property test
  460. uv run pytest tests/ -v
  461. ```
  462. **Full CI run** (~5+ minutes):
  463. ```bash
  464. # CI mode - 100 examples, all phases
  465. HYPOTHESIS_PROFILE=ci uv run pytest tests/ -v
  466. ```
  467. **Benchmarks** (run separately, ~1-2 minutes):
  468. ```bash
  469. # Performance benchmarks
  470. uv run pytest tests/benchmarks/ --benchmark-only
  471. ```
  472. ### Hypothesis Profiles
  473. | Profile | Examples | Use Case |
  474. |---------|----------|----------|
  475. | `fast` | 10 | Quick iteration, TDD |
  476. | `dev` | 50 | Local development (default) |
  477. | `ci` | 100 | CI/CD, thorough testing |
  478. Set via environment: `HYPOTHESIS_PROFILE=fast pytest ...`
  479. ### Test Categories
  480. ```bash
  481. # Unit tests only (fastest)
  482. uv run pytest tests/unit/ -v
  483. # Integration tests
  484. uv run pytest tests/integration/ -v
  485. # Property-based tests
  486. uv run pytest tests/property/ -v
  487. # Security tests
  488. uv run pytest tests/security/ -v
  489. # Include benchmarks (excluded by default)
  490. uv run pytest tests/ tests/benchmarks/ --benchmark-only
  491. ```
  492. ---
  493. ## Troubleshooting
  494. ### RLM Not Initializing
  495. 1. Check plugin installation: `claude plugin list`
  496. 2. Check hooks: `ls hooks/hooks.json`
  497. 3. Test init script: `uv run python scripts/init_rlm.py`
  498. ### Module Import Errors
  499. Install dependencies:
  500. ```bash
  501. uv sync --all-extras
  502. ```
  503. ### Reset Everything
  504. ```bash
  505. rm ~/.claude/rlm-config.json
  506. rm ~/.claude/rlm-memory.db
  507. ```
  508. ---
  509. ## Documentation
  510. | Document | Description |
  511. |----------|-------------|
  512. | [Getting Started](./docs/getting-started.md) | Installation and first steps |
  513. | [User Guide](./docs/user-guide.md) | Complete usage documentation |
  514. | [Specification](./rlm-claude-code-spec.md) | Technical specification |
  515. | [Architecture](./docs/process/architecture.md) | ADRs and design decisions |
  516. | [SPEC Overview](./docs/spec/00-overview.md) | Capability specifications |
  517. ---
  518. ## References
  519. - [RLM Paper](https://arxiv.org/abs/2512.24601v1) - Zhang, Kraska, Khattab
  520. - [Alex Zhang's RLM Blog](https://alexzhang13.github.io/blog/2025/rlm/)
  521. - [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code)
  522. ---
  523. ## License
  524. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.