rand avatar

rlm-claude-code

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

version
0.7.4
GitHub stars
106

Install

/plugin install rlm-claude-code@rlm-claude-code

Run it inside Claude Code after adding the marketplace with /plugin marketplace add rand/rlm-claude-code.

Contents

Discovered from source

Commands 8

Run performance benchmarks for RLM-Claude-Code.

Commands

# All benchmarks
uv run pytest tests/benchmarks/ --benchmark-only

# With comparison to baseline
uv run pytest tests/benchmarks/ --benchmark-only --benchmark-compare

# Save results
uv run pytest tests/benchmarks/ --benchmark-only --benchmark-json=results.json

# Specific benchmark
uv run pytest tests/benchmarks/test_performance.py::test_complexity_classifier_latency --benchmark-only

Performance Targets

ComponentTargetMeasurement
Complexity classifier<50mstest_complexity_classifier_latency
REPL execution<100mstest_repl_execution_latency
Trajectory render<10ms/eventtest_trajectory_render_latency
Context externalization<500mstest_context_externalization

Profiling

# CPU profiling
python -m cProfile -s cumulative -m src.orchestrator --query "test" 2>&1 | head -50

# Memory profiling
python -m memory_profiler src/orchestrator.py

# Line profiling
kernprof -l -v src/complexity_classifier.py

Cost Tracking

Track token usage:

uv run python -m src.tools.cost_tracker --trajectory /path/to/trajectory.json

Expected costs:

  • Simple query through RLM: ~$0.10-0.20
  • Complex multi-file task: ~$0.30-0.50
  • Deep verification (depth=2): ~$0.50-1.00

Review the current changes following docs/process/code-review.md.

Review Checklist

Correctness

  • Does the implementation match the spec section? (cite §X.Y)
  • Are edge cases handled (empty context, max depth, timeout)?
  • Do error states produce meaningful messages?

Type Safety

uv run ty check src/
  • All public functions have return type annotations?
  • No # type: ignore without justification?

Testing

  • Unit tests for new functions?
  • Property tests for data transformations?
  • Security tests for REPL operations?

Performance

  • Complexity classifier <50ms?
  • REPL execution <100ms?
  • No O(n²) on context size?

Security

  • No eval() on untrusted input?
  • Subprocess calls use allowlist?
  • API keys not logged?

Style

uv run ruff check src/
uv run ruff format src/ --check

Output Format

Provide specific, actionable feedback with file:line references.

Blocking issues: Must fix before commit Non-blocking: File as issues for later

RLM Orchestrator

Invoke the RLM orchestrator agent for complex context management tasks.

Usage

/rlm-orchestrator [task description]

When to Use

Use this when you need:

  • Multi-file context management across large codebases
  • Parallel tracking of multiple work streams
  • Complex reasoning with context externalization
  • REPL-based context decomposition

How It Works

This command launches the RLM orchestrator as a Task agent with full tool access. The agent:

  1. Externalizes conversation context to Python variables
  2. Uses REPL operations (peek, search, summarize) for efficient context access
  3. Can spawn recursive sub-queries for deep analysis
  4. Manages depth budgets and model cascades (Opus → Sonnet → Haiku)

Instructions

When this skill is invoked, use the Task tool to launch the RLM orchestrator agent:

Task(
  subagent_type="rlm-claude-code:rlm-orchestrator",
  prompt="[user's task description]",
  description="RLM orchestration"
)

The agent will receive the full conversation context and can use all available tools.

Related

  • /rlm - Configure RLM mode settings
  • /rlm status - Check current configuration
  • /simple - Bypass RLM for simple operations

Toggle or configure RLM (Recursive Language Model) mode.

Usage

  • /rlm-claude-code:rlm — Show current RLM status and configuration
  • /rlm-claude-code:rlm on — Force RLM mode for this session
  • /rlm-claude-code:rlm off — Disable RLM mode (use standard Claude Code)
  • /rlm-claude-code:rlm auto — Use complexity-based activation (default)
  • /rlm-claude-code:rlm verbose — Enable verbose trajectory output
  • /rlm-claude-code:rlm debug — Enable debug trajectory output with full content

Tip: You can create a shell alias: alias rlm='claude skill rlm-claude-code:rlm'

Current Configuration

Check ~/.claude/rlm-config.json for:

  • activation.mode: "complexity" | "always" | "manual"
  • depth.default: 2
  • trajectory.verbosity: "minimal" | "normal" | "verbose" | "debug"

When to Use

Force RLM on when:

  • Working with large codebases (>50 files in context)
  • Debugging complex multi-file issues
  • Refactoring across module boundaries
  • You want to see the reasoning trajectory

Force RLM off when:

  • Simple file operations
  • Quick questions about single files
  • You want faster responses for simple tasks

Trajectory Verbosity

LevelShows
minimalRECURSE, FINAL, ERROR only
normalAll events, truncated content
verboseAll events, full content
debugEverything + internal state

Related Commands

  • /rlm-claude-code:rlm-orchestrator — Launch RLM orchestrator agent for complex context tasks
  • /rlm-claude-code:simple — Bypass RLM for a single operation
  • /rlm-claude-code:trajectory <file> — Analyze a saved trajectory

Bypass RLM mode for a simple operation.

Usage

/rlm-claude-code:simple [command] — Execute command without RLM orchestration

When to Use

Use /rlm-claude-code:simple when you know the task doesn't need RLM's context decomposition:

  • Quick file reads: /rlm-claude-code:simple show package.json
  • Simple commands: /rlm-claude-code:simple run npm test
  • Git operations: /rlm-claude-code:simple git status
  • Acknowledgments: /rlm-claude-code:simple yes, continue

How It Works

The /simple prefix tells RLM to skip complexity analysis and execute directly through standard Claude Code. This:

  1. Avoids the ~50ms complexity classifier overhead
  2. Skips context externalization
  3. Uses direct model call without REPL
  4. Still maintains conversation history

Examples

/rlm-claude-code:simple cat README.md
/rlm-claude-code:simple git diff HEAD~1
/rlm-claude-code:simple npm install lodash
/rlm-claude-code:simple ls -la src/

When NOT to Use

Don't use /rlm-claude-code:simple for:

  • Multi-file operations
  • Debugging with large output
  • Refactoring tasks
  • Anything that says "find all" or "across"
  • Questions about code relationships

These benefit from RLM's context decomposition and recursive analysis.

Run the test suite for RLM-Claude-Code.

Commands

# All tests
uv run pytest tests/ -v

# By category
uv run pytest tests/unit/ -v
uv run pytest tests/integration/ -v
uv run pytest tests/property/ -v -m hypothesis
uv run pytest tests/security/ -v
uv run pytest tests/benchmarks/ --benchmark-only

# With coverage
uv run pytest tests/ -v --cov=src/ --cov-report=html

# Specific file
uv run pytest tests/unit/test_complexity_classifier.py -v

# Watch mode
uv run pytest-watch tests/ -v

Coverage Requirements

ComponentTarget
context_manager.py90%
repl_environment.py85%
recursive_handler.py90%
complexity_classifier.py95%
trajectory_renderer.py80%

Quick Checks

Before committing:

  1. uv run pytest tests/unit/ -v — Unit tests pass
  2. uv run pytest tests/security/ -v — Security tests pass
  3. uv run ty check src/ — Type check passes

Analyze an RLM trajectory file.

Usage

/rlm-claude-code:trajectory [path] — Analyze trajectory at path (default: last trajectory)

Analysis Output

Trajectory Analysis: /path/to/trajectory.json
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
  Total events: 23
  Max depth reached: 2
  Recursive calls: 4
  REPL executions: 8
  Tool uses: 3
  Duration: 34.2s
  Estimated cost: $0.47

Event Distribution:
  ANALYZE: 3
  REPL_EXEC: 8
  REASON: 6
  RECURSE_START: 4
  RECURSE_END: 4
  TOOL_USE: 3
  FINAL: 1

Slow Events (>5s):
  [12] RECURSE depth=1: 8.3s - "Analyze auth error handling..."
  [18] TOOL_USE: 5.1s - bash: npm test

Errors: None

Commands

# Pretty-print trajectory
uv run python -m src.tools.trajectory_viewer trajectory.json

# Filter by depth
uv run python -m src.tools.trajectory_viewer trajectory.json --depth 1

# Filter by type
uv run python -m src.tools.trajectory_viewer trajectory.json --type repl_exec

# Compare two trajectories
uv run python -m src.tools.trajectory_diff working.json failing.json

# Export to HTML
uv run python -m src.tools.trajectory_viewer trajectory.json --html > trajectory.html

Debugging with Trajectories

  1. Capture: Run with --verbosity debug --export-trajectory /tmp/debug.json
  2. Analyze: /trajectory /tmp/debug.json
  3. Identify: Find slow events, errors, or unexpected recursion
  4. Fix: See docs/process/debugging.md for issue-specific guidance

Control and view epistemic verification (hallucination detection).

Usage

  • /verify — Show current verification status and configuration
  • /verify on — Enable verification for this session
  • /verify off — Disable verification for this session
  • /verify report — Show the last verification report
  • /verify claim "..." — Verify a specific claim against context
  • /verify feedback <claim_id> correct|incorrect — Provide feedback on verification accuracy
  • /verify stats — Show verification feedback statistics
  • /verify mode <full|sample|critical> — Set verification mode

Verification Modes

ModeDescriptionCost
fullVerify all claimsHighest
sampleVerify critical + sample of claims (default)Medium
criticalOnly verify claims marked as criticalLowest

Configuration

Check ~/.claude/rlm-config.json for verification settings:

  • verification.enabled: true | false
  • verification.mode: "full" | "sample" | "critical_only"
  • verification.support_threshold: 0.0-1.0 (default 0.7)
  • verification.sample_rate: 0.0-1.0 (default 0.3)
  • verification.on_failure: "flag" | "retry" | "ask"

When to Use

Enable verification when:

  • Accuracy is critical (production documentation, code review)
  • Working with unfamiliar codebases
  • Generating technical specifications
  • Debugging claims that seem wrong

Disable verification when:

  • Quick iterations where speed matters more than precision
  • Creative/exploratory tasks
  • You're confident in the context

Feedback Loop

Use /verify feedback to improve verification accuracy:

/verify feedback c1 correct      # The claim was accurately verified
/verify feedback c2 incorrect    # The claim was incorrectly flagged (false positive)

This feedback is stored and used to calibrate verification thresholds over time.

Verification Report

The report shows:

  • Claims: Total claims extracted from response
  • Verified: Claims that passed verification
  • Flagged: Claims that failed (with reasons)
  • Gaps: Evidence gaps identified (unsupported, contradicted, phantom citations)
  • Confidence: Overall confidence score

Example Output

Verification Report
───────────────────
Response: resp-abc123
Mode: sample (30% sampling)

Claims: 5 total, 4 verified, 1 flagged
Confidence: 0.85

Flagged Claims:
  [c3] "The API returns XML data"
       Reason: unsupported
       Suggestion: Provide supporting evidence or remove claim

Evidence Gaps:
  - partial_support (c2): Claim goes beyond available evidence

Agents 1

RLM Orchestrator Agent

You are operating in RLM (Recursive Language Model) mode. Your conversation context is externalized as Python variables in a REPL environment.

Available Context Variables

  • conversation: List of messages (role, content)
  • files: Dict mapping file paths to contents
  • tool_outputs: List of recent tool execution results
  • working_memory: Dict for session state

Available Operations

Peek

View a portion of context without loading it all:

peek(conversation, 0, 5)  # First 5 messages
peek(files['main.py'], 0, 1000)  # First 1000 chars

Search

Find patterns in context:

search(files, 'def authenticate')  # Find in all files
search(tool_outputs[-1], r'ERROR|FAIL', regex=True)  # Regex search

Summarize

Get LLM summary of context portion:

summarize(files['large_file.py'], max_tokens=500)

Recursive Query

Spawn a sub-query over context:

recursive_query("What error handling exists here?", files['auth.py'])

Constraint Verification (CPMpy)

import cpmpy as cp
x = cp.intvar(0, 10, name="x")
model = cp.Model([x > 5])
model.solve()

Platform: Parallel Tool Execution

When you issue multiple tool calls in a single message, they run in parallel. If any one call fails (non-zero exit code), all sibling calls are cancelled with "Sibling tool call errored" — even if those siblings would have succeeded.

This matters for exploratory Bash calls: commands like ls, grep, and find return exit code 1 when they find no matches, which is semantically "no results" but triggers sibling cancellation.

When choosing between parallel and sequential tool calls:

  • Parallel: when you're confident all calls will succeed (e.g., reading known files, running tested commands)
  • Sequential: when calls are exploratory and may legitimately return no results
  • Guard with || true: when you want to parallelize uncertain commands without risking cascade failure

Prefer Glob and Grep tools over Bash find/grep for file discovery — they handle no-results gracefully without non-zero exit codes.

Rules

  1. Don't request full context dumps — Use programmatic access
  2. Partition large contexts — Chunk before analyzing
  3. Use recursive_query for semantics — When you need understanding, not just text
  4. Verify at depth=2 — Use CPMpy for safety verification

Output Protocol

When ready to answer:

  • FINAL(your answer here) — Direct answer
  • FINAL_VAR(variable_name) — Answer stored in variable

Depth Limits

  • Current depth: Shown in trajectory header
  • Max depth: 2 (configurable to 3)
  • At max depth: Simple completion, no REPL

Model Cascade

DepthModelPurpose
0Opus 4.5Complex orchestration
1Sonnet 4Analysis, summarization
2Haiku 4.5Verification, extraction

Sponsors

Details

Marketplace
rand/rlm-claude-code
Category
Community