rlm-tools 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
rlm_tools/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """RLM Tools - Persistent Python REPL for MCP-based codebase exploration."""
rlm_tools/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ from .server import main
2
+
3
+
4
+ if __name__ == "__main__":
5
+ main()
rlm_tools/helpers.py ADDED
@@ -0,0 +1,212 @@
1
+ import os
2
+ import pathlib
3
+ import re
4
+
5
+
6
+ _SKIP_DIRS = {
7
+ ".git", ".build", ".swiftpm", "DerivedData", "Build", "Pods",
8
+ "node_modules", ".venv", "venv", "__pycache__", ".tox", ".mypy_cache",
9
+ "Carthage", ".cache", "xcuserdata",
10
+ }
11
+
12
+ _BINARY_EXTENSIONS = {
13
+ ".png", ".jpg", ".jpeg", ".gif", ".ico", ".pdf", ".zip", ".tar", ".gz",
14
+ ".xz", ".bz2", ".o", ".a", ".dylib", ".framework", ".xcassets",
15
+ ".car", ".nib", ".storyboardc", ".momd", ".sqlite", ".db",
16
+ }
17
+
18
+
19
+ def _walk_files(root: pathlib.Path):
20
+ for dirpath, dirnames, filenames in os.walk(root):
21
+ dirnames[:] = [
22
+ d for d in dirnames
23
+ if d not in _SKIP_DIRS and not d.startswith(".")
24
+ ]
25
+ for fname in filenames:
26
+ if fname.startswith("."):
27
+ continue
28
+ yield pathlib.Path(dirpath) / fname
29
+
30
+
31
+ def make_helpers(base_path: str) -> tuple[dict, callable]:
32
+ base = pathlib.Path(base_path).resolve()
33
+ _file_cache: dict[str, str] = {}
34
+
35
+ def _resolve_safe(path: str) -> pathlib.Path:
36
+ resolved = (base / path).resolve()
37
+ try:
38
+ resolved.relative_to(base)
39
+ except ValueError:
40
+ raise PermissionError(f"Access denied: path '{path}' escapes sandbox root")
41
+ return resolved
42
+
43
+ def read_file(path: str) -> str:
44
+ target = _resolve_safe(path)
45
+ cache_key = str(target)
46
+ if cache_key in _file_cache:
47
+ return _file_cache[cache_key]
48
+ content = target.read_text(errors="replace")
49
+ _file_cache[cache_key] = content
50
+ return content
51
+
52
+ def read_files(paths: list[str]) -> dict[str, str]:
53
+ """Read multiple files at once. Returns {path: content} dict."""
54
+ result = {}
55
+ for path in paths:
56
+ try:
57
+ result[path] = read_file(path)
58
+ except (OSError, PermissionError) as e:
59
+ result[path] = f"[error: {e}]"
60
+ return result
61
+
62
+ def grep(pattern: str, path: str = ".") -> list[dict]:
63
+ target = _resolve_safe(path)
64
+ compiled = re.compile(pattern)
65
+ results = []
66
+
67
+ if target.is_file():
68
+ search_paths = [target]
69
+ else:
70
+ search_paths = _walk_files(target)
71
+
72
+ for file_path in search_paths:
73
+ if not file_path.is_file():
74
+ continue
75
+ ext = file_path.suffix.lower()
76
+ if ext in _BINARY_EXTENSIONS:
77
+ continue
78
+ try:
79
+ for i, line in enumerate(file_path.read_text(errors="replace").splitlines(), 1):
80
+ if compiled.search(line):
81
+ results.append({
82
+ "file": str(file_path.relative_to(base)),
83
+ "line_number": i,
84
+ "line": line.strip(),
85
+ })
86
+ except (OSError, UnicodeDecodeError):
87
+ continue
88
+ return results
89
+
90
+ def grep_summary(pattern: str, path: str = ".") -> str:
91
+ """Grep with compact output grouped by file. Returns a formatted string."""
92
+ results = grep(pattern, path)
93
+ if not results:
94
+ return "No matches found."
95
+
96
+ grouped: dict[str, list[dict]] = {}
97
+ for r in results:
98
+ grouped.setdefault(r["file"], []).append(r)
99
+
100
+ lines = [f"{len(results)} matches in {len(grouped)} files:"]
101
+ for file, matches in grouped.items():
102
+ lines.append(f"\n {file} ({len(matches)} matches):")
103
+ for m in matches:
104
+ lines.append(f" L{m['line_number']}: {m['line']}")
105
+ return "\n".join(lines)
106
+
107
+ def grep_read(
108
+ pattern: str,
109
+ path: str = ".",
110
+ max_files: int = 10,
111
+ context_lines: int = 0,
112
+ ) -> dict:
113
+ """Grep then auto-read matching files. Returns match info + file contents.
114
+
115
+ Args:
116
+ pattern: Regex pattern to search for.
117
+ path: Directory or file to search in.
118
+ max_files: Maximum number of matching files to read (default 10).
119
+ context_lines: Lines of context around each match (default 0).
120
+
121
+ Returns:
122
+ Dict with 'matches' (grouped by file) and 'files' (full contents).
123
+ """
124
+ results = grep(pattern, path)
125
+ if not results:
126
+ return {"matches": {}, "files": {}, "summary": "No matches found."}
127
+
128
+ grouped: dict[str, list[dict]] = {}
129
+ for r in results:
130
+ grouped.setdefault(r["file"], []).append(r)
131
+
132
+ file_paths = list(grouped.keys())[:max_files]
133
+ file_contents = {}
134
+ for fp in file_paths:
135
+ try:
136
+ content = read_file(fp)
137
+ if context_lines > 0:
138
+ content_lines = content.splitlines()
139
+ relevant = set()
140
+ for m in grouped[fp]:
141
+ line_idx = m["line_number"] - 1
142
+ start = max(0, line_idx - context_lines)
143
+ end = min(len(content_lines), line_idx + context_lines + 1)
144
+ for i in range(start, end):
145
+ relevant.add(i)
146
+ excerpts = []
147
+ for i in sorted(relevant):
148
+ excerpts.append(f"L{i+1}: {content_lines[i]}")
149
+ file_contents[fp] = "\n".join(excerpts)
150
+ else:
151
+ file_contents[fp] = content
152
+ except (OSError, PermissionError) as e:
153
+ file_contents[fp] = f"[error: {e}]"
154
+
155
+ truncated = len(grouped) - len(file_paths) if len(grouped) > max_files else 0
156
+ summary = f"{len(results)} matches in {len(grouped)} files"
157
+ if truncated:
158
+ summary += f" (showing {max_files}, {truncated} more)"
159
+
160
+ return {
161
+ "matches": {fp: grouped[fp] for fp in file_paths},
162
+ "files": file_contents,
163
+ "summary": summary,
164
+ }
165
+
166
+ def glob_files(pattern: str) -> list[str]:
167
+ matches = list(base.glob(pattern))
168
+ safe_matches: list[str] = []
169
+ for match in matches:
170
+ if not match.is_file():
171
+ continue
172
+ parts = match.relative_to(base).parts
173
+ if any(part in _SKIP_DIRS or part.startswith(".") for part in parts[:-1]):
174
+ continue
175
+ try:
176
+ safe_matches.append(str(match.resolve().relative_to(base)))
177
+ except ValueError:
178
+ continue
179
+ return safe_matches
180
+
181
+ def tree(path: str = ".", max_depth: int = 3) -> str:
182
+ target = _resolve_safe(path)
183
+ lines = []
184
+
185
+ def _walk(dir_path: pathlib.Path, prefix: str, depth: int):
186
+ if depth > max_depth:
187
+ return
188
+ try:
189
+ entries = sorted(dir_path.iterdir(), key=lambda e: (not e.is_dir(), e.name))
190
+ except PermissionError:
191
+ return
192
+ visible = [e for e in entries if not e.name.startswith(".") and e.name not in _SKIP_DIRS]
193
+ for i, entry in enumerate(visible):
194
+ connector = "└── " if i == len(visible) - 1 else "├── "
195
+ lines.append(f"{prefix}{connector}{entry.name}")
196
+ if entry.is_dir():
197
+ extension = " " if i == len(visible) - 1 else "│ "
198
+ _walk(entry, prefix + extension, depth + 1)
199
+
200
+ lines.append(str(target.relative_to(base)) if target != base else ".")
201
+ _walk(target, "", 0)
202
+ return "\n".join(lines)
203
+
204
+ return {
205
+ "read_file": read_file,
206
+ "read_files": read_files,
207
+ "grep": grep,
208
+ "grep_summary": grep_summary,
209
+ "grep_read": grep_read,
210
+ "glob_files": glob_files,
211
+ "tree": tree,
212
+ }, _resolve_safe
@@ -0,0 +1,69 @@
1
+ import os
2
+ import logging
3
+ from concurrent.futures import ThreadPoolExecutor, as_completed
4
+ from anthropic import Anthropic
5
+
6
+ logger = logging.getLogger(__name__)
7
+
8
+ DEFAULT_MODEL = "claude-haiku-4-5-20251001"
9
+
10
+
11
+ def get_client() -> Anthropic:
12
+ api_key = os.environ.get("ANTHROPIC_API_KEY")
13
+ if not api_key:
14
+ raise RuntimeError(
15
+ "ANTHROPIC_API_KEY environment variable is required for llm_query()"
16
+ )
17
+ return Anthropic(api_key=api_key)
18
+
19
+
20
+ def make_llm_query(
21
+ client: Anthropic | None = None,
22
+ model: str | None = None,
23
+ ):
24
+ _client = client or get_client()
25
+ _model = model or os.environ.get("RLM_SUB_MODEL", DEFAULT_MODEL)
26
+
27
+ def llm_query(prompt: str, context: str = "") -> str:
28
+ if not prompt:
29
+ raise ValueError("prompt cannot be empty")
30
+
31
+ messages = []
32
+ if context:
33
+ messages.append({"role": "user", "content": f"Context:\n{context}\n\nQuestion: {prompt}"})
34
+ else:
35
+ messages.append({"role": "user", "content": prompt})
36
+
37
+ response = _client.messages.create(
38
+ model=_model,
39
+ max_tokens=1024,
40
+ messages=messages,
41
+ )
42
+ if not response.content:
43
+ return ""
44
+ first = response.content[0]
45
+ return getattr(first, "text", str(first))
46
+
47
+ return llm_query
48
+
49
+
50
+ def make_llm_query_batched(llm_query_fn, max_workers: int = 8):
51
+ def llm_query_batched(prompts: list[str], context: str = "") -> list[str]:
52
+ if not prompts:
53
+ return []
54
+
55
+ results: dict[int, str] = {}
56
+ with ThreadPoolExecutor(max_workers=max_workers) as executor:
57
+ future_to_idx = {
58
+ executor.submit(llm_query_fn, prompt, context): i
59
+ for i, prompt in enumerate(prompts)
60
+ }
61
+ for future in as_completed(future_to_idx):
62
+ i = future_to_idx[future]
63
+ try:
64
+ results[i] = future.result()
65
+ except Exception as e:
66
+ results[i] = f"[ERROR] {type(e).__name__}: {e}"
67
+ return [results[i] for i in range(len(prompts))]
68
+
69
+ return llm_query_batched
rlm_tools/sandbox.py ADDED
@@ -0,0 +1,136 @@
1
+ import io
2
+ import contextlib
3
+ import builtins
4
+ import pathlib
5
+ import signal
6
+ import threading
7
+ from contextlib import contextmanager
8
+ from dataclasses import dataclass
9
+
10
+ from rlm_tools.helpers import make_helpers
11
+
12
+
13
+ ALLOWED_MODULES = frozenset({
14
+ "re", "json", "collections", "math",
15
+ "fnmatch", "itertools", "functools", "operator", "string",
16
+ "textwrap", "difflib", "statistics",
17
+ })
18
+
19
+ BLOCKED_BUILTINS = frozenset({
20
+ "exec", "eval", "compile", "__import__", "breakpoint",
21
+ "exit", "quit", "input",
22
+ })
23
+
24
+
25
+ @dataclass
26
+ class ExecutionResult:
27
+ stdout: str
28
+ error: str | None
29
+ variables: list[str]
30
+
31
+
32
+ def _make_restricted_import(allowed: frozenset[str]):
33
+ original_import = builtins.__import__
34
+
35
+ def restricted_import(name, *args, **kwargs):
36
+ if name not in allowed and name.split(".")[0] not in allowed:
37
+ raise ImportError(f"Import of '{name}' is not allowed in the sandbox")
38
+ return original_import(name, *args, **kwargs)
39
+
40
+ return restricted_import
41
+
42
+
43
+ class Sandbox:
44
+ def __init__(
45
+ self,
46
+ base_path: str,
47
+ max_output_chars: int = 15_000,
48
+ execution_timeout_seconds: int = 30,
49
+ ):
50
+ self._base_path = base_path
51
+ self._max_output_chars = max_output_chars
52
+ self._execution_timeout_seconds = execution_timeout_seconds
53
+ self._namespace: dict = {}
54
+ self._resolve_safe = None
55
+ self._setup_namespace()
56
+
57
+ def _setup_namespace(self) -> None:
58
+ safe_builtins = {
59
+ k: v for k, v in builtins.__dict__.items()
60
+ if k not in BLOCKED_BUILTINS
61
+ }
62
+ safe_builtins["__import__"] = _make_restricted_import(ALLOWED_MODULES)
63
+
64
+ original_open = builtins.open
65
+
66
+ def restricted_open(file, mode="r", *args, **kwargs):
67
+ if any(c in mode for c in "wxa+"):
68
+ raise PermissionError(f"Write access denied in sandbox (mode='{mode}')")
69
+
70
+ if self._resolve_safe is None:
71
+ raise RuntimeError("Sandbox path resolver was not initialized")
72
+
73
+ if isinstance(file, int):
74
+ raise PermissionError("File descriptor access is not allowed in sandbox")
75
+
76
+ # Keep read access scoped to the sandbox root.
77
+ safe_path = self._resolve_safe(str(pathlib.Path(file)))
78
+ return original_open(safe_path, mode, *args, **kwargs)
79
+
80
+ safe_builtins["open"] = restricted_open
81
+
82
+ self._namespace["__builtins__"] = safe_builtins
83
+
84
+ helpers, self._resolve_safe = make_helpers(self._base_path)
85
+ self._namespace.update(helpers)
86
+
87
+ @contextmanager
88
+ def _execution_timeout(self):
89
+ if (
90
+ self._execution_timeout_seconds <= 0
91
+ or threading.current_thread() is not threading.main_thread()
92
+ or not hasattr(signal, "SIGALRM")
93
+ ):
94
+ yield
95
+ return
96
+
97
+ def _raise_timeout(_signum, _frame):
98
+ raise TimeoutError(
99
+ f"Execution timed out after {self._execution_timeout_seconds} seconds"
100
+ )
101
+
102
+ previous_handler = signal.getsignal(signal.SIGALRM)
103
+ signal.signal(signal.SIGALRM, _raise_timeout)
104
+ signal.setitimer(signal.ITIMER_REAL, self._execution_timeout_seconds)
105
+ try:
106
+ yield
107
+ finally:
108
+ signal.setitimer(signal.ITIMER_REAL, 0)
109
+ signal.signal(signal.SIGALRM, previous_handler)
110
+
111
+ def execute(self, code: str) -> ExecutionResult:
112
+ stdout_capture = io.StringIO()
113
+ error = None
114
+
115
+ try:
116
+ with contextlib.redirect_stdout(stdout_capture):
117
+ with self._execution_timeout():
118
+ exec(code, self._namespace)
119
+ except Exception as e:
120
+ error = f"{type(e).__name__}: {e}"
121
+
122
+ stdout = stdout_capture.getvalue()
123
+ if len(stdout) > self._max_output_chars:
124
+ stdout = stdout[:self._max_output_chars] + "\n... [output truncated]"
125
+
126
+ return ExecutionResult(
127
+ stdout=stdout,
128
+ error=error,
129
+ variables=self.list_variables(),
130
+ )
131
+
132
+ def list_variables(self) -> list[str]:
133
+ return [
134
+ k for k in self._namespace
135
+ if not k.startswith("_") and k != "__builtins__"
136
+ ]
rlm_tools/server.py ADDED
@@ -0,0 +1,331 @@
1
+ import json
2
+ import logging
3
+ import os
4
+ import pathlib
5
+ import threading
6
+ from typing import Annotated, Literal
7
+
8
+ from mcp.server.fastmcp import FastMCP
9
+ from pydantic import Field
10
+
11
+ from rlm_tools.session import SessionManager
12
+ from rlm_tools.sandbox import Sandbox
13
+ from rlm_tools.llm_bridge import make_llm_query, make_llm_query_batched
14
+
15
+ logging.basicConfig(level=logging.INFO)
16
+ logger = logging.getLogger(__name__)
17
+
18
+ mcp = FastMCP("rlm-tools")
19
+
20
+ session_manager = SessionManager(
21
+ max_sessions=int(os.environ.get("RLM_MAX_SESSIONS", "5")),
22
+ timeout_minutes=int(os.environ.get("RLM_SESSION_TIMEOUT", "10")),
23
+ )
24
+
25
+ _sandboxes: dict[str, Sandbox] = {}
26
+
27
+
28
+ from rlm_tools.helpers import _SKIP_DIRS, _BINARY_EXTENSIONS
29
+
30
+
31
+ def _scan_metadata(path: str) -> dict:
32
+ extensions: dict[str, int] = {}
33
+ total_files = 0
34
+ total_lines = 0
35
+ sampled_lines = 0
36
+ sampled_files = 0
37
+ sample_budget = 500
38
+
39
+ for dirpath, dirnames, filenames in os.walk(path):
40
+ dirnames[:] = [
41
+ d for d in dirnames
42
+ if d not in _SKIP_DIRS and not d.startswith(".")
43
+ ]
44
+
45
+ for fname in filenames:
46
+ if fname.startswith("."):
47
+ continue
48
+ ext = os.path.splitext(fname)[1] or "(no ext)"
49
+ extensions[ext] = extensions.get(ext, 0) + 1
50
+ total_files += 1
51
+
52
+ if ext not in _BINARY_EXTENSIONS:
53
+ try:
54
+ fpath = os.path.join(dirpath, fname)
55
+ with open(fpath, errors="replace") as f:
56
+ file_line_count = sum(1 for _ in f)
57
+ total_lines += file_line_count
58
+
59
+ if sampled_files < sample_budget:
60
+ sampled_lines += file_line_count
61
+ sampled_files += 1
62
+ except OSError:
63
+ pass
64
+
65
+ return {
66
+ "total_files": total_files,
67
+ "total_lines": total_lines,
68
+ "sampled_lines": sampled_lines,
69
+ "sampled_files": sampled_files,
70
+ "file_types": dict(sorted(extensions.items(), key=lambda x: -x[1])[:10]),
71
+ }
72
+
73
+
74
+ def _cleanup_expired_resources() -> None:
75
+ expired_session_ids = session_manager.cleanup_expired()
76
+ for session_id in expired_session_ids:
77
+ _sandboxes.pop(session_id, None)
78
+
79
+
80
+ def _install_session_llm_tools(session, sandbox: Sandbox) -> bool:
81
+ api_key = os.environ.get("ANTHROPIC_API_KEY")
82
+ if not api_key:
83
+ return False
84
+
85
+ try:
86
+ base_llm_query = make_llm_query()
87
+ base_llm_query_batched = make_llm_query_batched(base_llm_query)
88
+ lock = threading.Lock()
89
+
90
+ def _reserve_llm_calls(count: int) -> None:
91
+ if count < 1:
92
+ raise ValueError("count must be >= 1")
93
+ with lock:
94
+ if session.llm_calls_used + count > session.max_llm_calls:
95
+ raise RuntimeError(
96
+ "LLM call limit exceeded: "
97
+ f"{session.llm_calls_used} + {count} > {session.max_llm_calls}"
98
+ )
99
+ session.llm_calls_used += count
100
+
101
+ def llm_query(prompt: str, context: str = "") -> str:
102
+ _reserve_llm_calls(1)
103
+ return base_llm_query(prompt, context)
104
+
105
+ def llm_query_batched(prompts: list[str], context: str = "") -> list[str]:
106
+ if not prompts:
107
+ return []
108
+ _reserve_llm_calls(len(prompts))
109
+ return base_llm_query_batched(prompts, context)
110
+
111
+ sandbox._namespace["llm_query"] = llm_query
112
+ sandbox._namespace["llm_query_batched"] = llm_query_batched
113
+ return True
114
+ except Exception as e:
115
+ logger.warning(f"Could not initialize llm_query: {e}")
116
+ return False
117
+
118
+
119
+ def _rlm_start(
120
+ path: str,
121
+ query: str,
122
+ max_output_chars: int = 15_000,
123
+ max_llm_calls: int = 50,
124
+ max_execute_calls: int = 50,
125
+ execution_timeout_seconds: int = 30,
126
+ include_guidance: bool = False,
127
+ include_metadata: bool = True,
128
+ ) -> str:
129
+ _cleanup_expired_resources()
130
+
131
+ resolved = str(pathlib.Path(path).resolve())
132
+ if not os.path.isdir(resolved):
133
+ return json.dumps({"error": f"Directory not found: {path}"})
134
+
135
+ try:
136
+ session_id = session_manager.create(
137
+ path=resolved,
138
+ query=query,
139
+ max_output_chars=max_output_chars,
140
+ max_llm_calls=max_llm_calls,
141
+ max_execute_calls=max_execute_calls,
142
+ )
143
+ except RuntimeError as e:
144
+ return json.dumps({"error": str(e)})
145
+
146
+ session = session_manager.get(session_id)
147
+ if not session:
148
+ return json.dumps({"error": f"Failed to create session for path: {path}"})
149
+
150
+ metadata = _scan_metadata(resolved) if include_metadata else {}
151
+
152
+ sandbox = Sandbox(
153
+ base_path=resolved,
154
+ max_output_chars=max_output_chars,
155
+ execution_timeout_seconds=execution_timeout_seconds,
156
+ )
157
+ has_llm_tools = _install_session_llm_tools(session, sandbox)
158
+
159
+ _sandboxes[session_id] = sandbox
160
+
161
+ available_functions = [
162
+ "read_file(path)",
163
+ "read_files(paths) -> dict[path, content]",
164
+ "grep(pattern, path='.')",
165
+ "grep_summary(pattern, path='.') -> compact grouped string",
166
+ "grep_read(pattern, path='.', max_files=10, context_lines=0) -> {matches, files, summary}",
167
+ "glob_files(pattern)",
168
+ "tree(path='.', max_depth=3)",
169
+ ]
170
+ if has_llm_tools:
171
+ available_functions.extend([
172
+ "llm_query(prompt, context='')",
173
+ "llm_query_batched(prompts, context='')",
174
+ ])
175
+
176
+ response: dict = {
177
+ "session_id": session_id,
178
+ "metadata": metadata,
179
+ "limits": {
180
+ "max_llm_calls": session.max_llm_calls,
181
+ "max_execute_calls": session.max_execute_calls,
182
+ "execution_timeout_seconds": execution_timeout_seconds,
183
+ },
184
+ "available_functions": available_functions,
185
+ }
186
+ if include_guidance:
187
+ response["strategy"] = (
188
+ "You are exploring a codebase through code. "
189
+ "Each rlm_execute call should batch 3-5+ operations into a single Python script. "
190
+ "Pattern: grep/glob to find targets -> read relevant files -> extract/analyze -> store in variables. "
191
+ "Aim for ~5-15 rlm_execute calls total, not 50+. "
192
+ "Use llm_query() for semantic analysis on extracted snippets. "
193
+ "Use llm_query_batched() when analyzing multiple snippets concurrently. "
194
+ "Variables persist between calls — build on previous results."
195
+ )
196
+ response["example"] = (
197
+ "# Good: batch multiple operations in ONE call\n"
198
+ "matches = grep('Reducer', '.')\n"
199
+ "files = list(set(m['file'] for m in matches))[:5]\n"
200
+ "for f in files:\n"
201
+ " content = read_file(f)\n"
202
+ " lines = content.split('\\n')\n"
203
+ " structs = [l.strip() for l in lines if 'struct ' in l or 'class ' in l]\n"
204
+ " print(f'{f}: {structs}')\n"
205
+ )
206
+ return json.dumps(response)
207
+
208
+
209
+ def _rlm_execute(
210
+ session_id: str,
211
+ code: str,
212
+ detail_level: Literal["compact", "usage", "full"] = "compact",
213
+ max_new_variables: int = 20,
214
+ ) -> str:
215
+ _cleanup_expired_resources()
216
+ session = session_manager.get(session_id)
217
+ if not session:
218
+ return json.dumps({"error": f"Session '{session_id}' not found or expired"})
219
+
220
+ sandbox = _sandboxes.get(session_id)
221
+ if not sandbox:
222
+ return json.dumps({"error": f"Sandbox not found for session '{session_id}'"})
223
+
224
+ if session.execute_calls >= session.max_execute_calls:
225
+ return json.dumps({
226
+ "error": (
227
+ "Execution call limit exceeded: "
228
+ f"{session.execute_calls} >= {session.max_execute_calls}"
229
+ )
230
+ })
231
+
232
+ session.execute_calls += 1
233
+ result = sandbox.execute(code)
234
+
235
+ response: dict = {
236
+ "stdout": result.stdout,
237
+ "error": result.error,
238
+ }
239
+
240
+ if detail_level in {"usage", "full"}:
241
+ response["usage"] = {
242
+ "execute_calls_used": session.execute_calls,
243
+ "execute_calls_remaining": session.max_execute_calls - session.execute_calls,
244
+ "llm_calls_used": session.llm_calls_used,
245
+ }
246
+
247
+ if detail_level == "full":
248
+ current_vars = set(result.variables)
249
+ previous_vars = getattr(session, "_last_reported_vars", set())
250
+ excluded_vars = {
251
+ "read_file", "read_files",
252
+ "grep", "grep_summary", "grep_read",
253
+ "glob_files", "tree",
254
+ "llm_query", "llm_query_batched",
255
+ }
256
+ new_vars = sorted(
257
+ v for v in (current_vars - previous_vars)
258
+ if v not in excluded_vars
259
+ )
260
+ session._last_reported_vars = current_vars
261
+
262
+ response["variables"] = sorted(v for v in current_vars if v not in excluded_vars)
263
+ response["total_variables"] = len(response["variables"])
264
+ response["new_variables"] = new_vars[:max_new_variables]
265
+ if len(new_vars) > max_new_variables:
266
+ response["new_variables_truncated_count"] = len(new_vars) - max_new_variables
267
+
268
+ return json.dumps(response)
269
+
270
+
271
+ def _rlm_end(session_id: str) -> str:
272
+ session_manager.end(session_id)
273
+ _sandboxes.pop(session_id, None)
274
+ return json.dumps({"success": True})
275
+
276
+
277
+ @mcp.tool()
278
+ async def rlm_start(
279
+ path: Annotated[str, Field(description="Absolute path to the directory to explore")],
280
+ query: Annotated[str, Field(description="What you want to find or analyze")],
281
+ max_output_chars: Annotated[int, Field(description="Max characters per execute output", ge=100, le=100_000)] = 15_000,
282
+ max_llm_calls: Annotated[int, Field(description="Maximum llm_query/llm_query_batched calls for this session", ge=1, le=10_000)] = 50,
283
+ max_execute_calls: Annotated[int, Field(description="Maximum rlm_execute calls for this session", ge=1, le=10_000)] = 50,
284
+ execution_timeout_seconds: Annotated[int, Field(description="Per-rlm_execute timeout in seconds", ge=1, le=300)] = 30,
285
+ include_guidance: Annotated[bool, Field(description="Include strategy/example guidance text in the response (larger payload)")] = False,
286
+ include_metadata: Annotated[bool, Field(description="Scan directory and include file counts/types in response (set false for faster startup)")] = True,
287
+ ) -> str:
288
+ """Start an RLM exploration session. Returns session_id, metadata, limits, and available functions. Set include_guidance=true to include strategy/example coaching text."""
289
+ return _rlm_start(
290
+ path=path,
291
+ query=query,
292
+ max_output_chars=max_output_chars,
293
+ max_llm_calls=max_llm_calls,
294
+ max_execute_calls=max_execute_calls,
295
+ execution_timeout_seconds=execution_timeout_seconds,
296
+ include_guidance=include_guidance,
297
+ include_metadata=include_metadata,
298
+ )
299
+
300
+
301
+ @mcp.tool()
302
+ async def rlm_execute(
303
+ session_id: Annotated[str, Field(description="Session ID from rlm_start")],
304
+ code: Annotated[str, Field(description=(
305
+ "Python code to execute. IMPORTANT: Batch multiple related operations into each call. "
306
+ "A good call does: grep -> read top matches -> extract patterns -> print summary. "
307
+ "A bad call does just one grep or one read_file. Variables persist between calls."
308
+ ))],
309
+ detail_level: Annotated[Literal["compact", "usage", "full"], Field(
310
+ description="Response payload level: compact=stdout+error, usage=add usage metrics, full=add variable details"
311
+ )] = "compact",
312
+ max_new_variables: Annotated[int, Field(
313
+ description="When detail_level=full, cap returned new_variables list to this size",
314
+ ge=1,
315
+ le=200,
316
+ )] = 20,
317
+ ) -> str:
318
+ """Execute Python in the session sandbox. detail_level controls response payload size (compact, usage, or full)."""
319
+ return _rlm_execute(session_id, code, detail_level, max_new_variables)
320
+
321
+
322
+ @mcp.tool()
323
+ async def rlm_end(
324
+ session_id: Annotated[str, Field(description="Session ID to end")],
325
+ ) -> str:
326
+ """End an RLM exploration session and free resources."""
327
+ return _rlm_end(session_id)
328
+
329
+
330
+ def main():
331
+ mcp.run(transport="stdio")
rlm_tools/session.py ADDED
@@ -0,0 +1,78 @@
1
+ import uuid
2
+ import time
3
+ import threading
4
+ from dataclasses import dataclass, field
5
+
6
+
7
+ @dataclass
8
+ class Session:
9
+ session_id: str
10
+ path: str
11
+ query: str
12
+ _last_reported_vars: set = field(default_factory=set)
13
+ created_at: float = field(default_factory=time.time)
14
+ last_used: float = field(default_factory=time.time)
15
+ max_output_chars: int = 15_000
16
+ max_llm_calls: int = 50
17
+ llm_calls_used: int = 0
18
+ max_execute_calls: int = 50
19
+ execute_calls: int = 0
20
+
21
+
22
+ class SessionManager:
23
+ def __init__(self, max_sessions: int = 5, timeout_minutes: int = 10):
24
+ self._sessions: dict[str, Session] = {}
25
+ self._max_sessions = max_sessions
26
+ self._timeout_seconds = timeout_minutes * 60
27
+ self._lock = threading.Lock()
28
+
29
+ def create(
30
+ self,
31
+ path: str,
32
+ query: str,
33
+ max_output_chars: int = 15_000,
34
+ max_llm_calls: int = 50,
35
+ max_execute_calls: int = 50,
36
+ ) -> str:
37
+ with self._lock:
38
+ self._cleanup_expired_locked()
39
+ if len(self._sessions) >= self._max_sessions:
40
+ raise RuntimeError(
41
+ f"Cannot create session: max sessions ({self._max_sessions}) reached"
42
+ )
43
+ session_id = uuid.uuid4().hex[:12]
44
+ self._sessions[session_id] = Session(
45
+ session_id=session_id,
46
+ path=path,
47
+ query=query,
48
+ max_output_chars=max_output_chars,
49
+ max_llm_calls=max_llm_calls,
50
+ max_execute_calls=max_execute_calls,
51
+ )
52
+ return session_id
53
+
54
+ def get(self, session_id: str) -> Session | None:
55
+ with self._lock:
56
+ self._cleanup_expired_locked()
57
+ session = self._sessions.get(session_id)
58
+ if session:
59
+ session.last_used = time.time()
60
+ return session
61
+
62
+ def end(self, session_id: str) -> None:
63
+ with self._lock:
64
+ self._sessions.pop(session_id, None)
65
+
66
+ def cleanup_expired(self) -> list[str]:
67
+ with self._lock:
68
+ return self._cleanup_expired_locked()
69
+
70
+ def _cleanup_expired_locked(self) -> list[str]:
71
+ now = time.time()
72
+ expired = [
73
+ sid for sid, s in self._sessions.items()
74
+ if now - s.last_used > self._timeout_seconds
75
+ ]
76
+ for sid in expired:
77
+ self._sessions.pop(sid, None)
78
+ return expired
rlm_tools/setup_cli.py ADDED
@@ -0,0 +1,179 @@
1
+ import argparse
2
+ import json
3
+ import shlex
4
+ import shutil
5
+ import subprocess
6
+ import sys
7
+ from pathlib import Path
8
+
9
+
10
+ POLICY_START = "<!-- rlm-tools-policy:start -->"
11
+ POLICY_END = "<!-- rlm-tools-policy:end -->"
12
+
13
+
14
+ def build_install_command(client: str) -> list[str]:
15
+ if client == "claude":
16
+ return ["claude", "mcp", "add", "rlm-tools", "--", "uvx", "rlm-tools"]
17
+ if client == "codex":
18
+ return ["codex", "mcp", "add", "rlm-tools", "--", "uvx", "rlm-tools"]
19
+ raise ValueError(f"Unsupported client: {client}")
20
+
21
+
22
+ def detect_supported_clients() -> list[str]:
23
+ clients = []
24
+ if shutil.which("claude"):
25
+ clients.append("claude")
26
+ if shutil.which("codex"):
27
+ clients.append("codex")
28
+ return clients
29
+
30
+
31
+ def run_install(client: str, dry_run: bool = False) -> tuple[bool, str]:
32
+ command = build_install_command(client)
33
+ command_str = " ".join(shlex.quote(part) for part in command)
34
+
35
+ if dry_run:
36
+ return True, f"[dry-run] {command_str}"
37
+
38
+ if shutil.which(command[0]) is None:
39
+ return False, f"{command[0]} CLI not found on PATH"
40
+
41
+ result = subprocess.run(command, capture_output=True, text=True, check=False)
42
+ if result.returncode == 0:
43
+ output = result.stdout.strip() or "Configured successfully."
44
+ return True, output
45
+
46
+ output = result.stderr.strip() or result.stdout.strip() or "Unknown error"
47
+ return False, output
48
+
49
+
50
+ def render_json_mcp_config() -> str:
51
+ config = {
52
+ "mcpServers": {
53
+ "rlm-tools": {
54
+ "command": "uvx",
55
+ "args": ["rlm-tools"],
56
+ }
57
+ }
58
+ }
59
+ return json.dumps(config, indent=2)
60
+
61
+
62
+ def render_policy_block() -> str:
63
+ return (
64
+ f"{POLICY_START}\n"
65
+ "## RLM Tools Policy\n\n"
66
+ "For codebase exploration, prefer `rlm-tools` over standard read/grep/glob tools.\n\n"
67
+ "Workflow:\n"
68
+ "1. Start with `rlm_start(path, query)`.\n"
69
+ "2. Use `rlm_execute(session_id, code)` to batch search/read/analyze steps.\n"
70
+ "3. Print concise summaries rather than raw payloads.\n"
71
+ "4. End with `rlm_end(session_id)` when finished.\n\n"
72
+ "Fallback rule:\n"
73
+ "- Use standard read/grep/glob only if `rlm-tools` is unavailable or errors.\n"
74
+ f"{POLICY_END}\n"
75
+ )
76
+
77
+
78
+ def upsert_policy_block(existing_text: str) -> str:
79
+ block = render_policy_block()
80
+ start_idx = existing_text.find(POLICY_START)
81
+ end_idx = existing_text.find(POLICY_END)
82
+
83
+ if start_idx != -1 and end_idx != -1 and end_idx > start_idx:
84
+ end_idx = end_idx + len(POLICY_END)
85
+ replacement = block.rstrip("\n")
86
+ return existing_text[:start_idx] + replacement + existing_text[end_idx:]
87
+
88
+ if not existing_text.strip():
89
+ return block
90
+ return existing_text.rstrip() + "\n\n" + block
91
+
92
+
93
+ def write_policy(path: Path) -> None:
94
+ existing_text = path.read_text() if path.exists() else ""
95
+ updated_text = upsert_policy_block(existing_text)
96
+ path.write_text(updated_text)
97
+
98
+
99
+ def main() -> None:
100
+ parser = argparse.ArgumentParser(
101
+ prog="rlm-tools-setup",
102
+ description=(
103
+ "Configure rlm-tools for Claude/Codex and optionally write policy guidance "
104
+ "that makes agents prefer rlm-tools for code exploration."
105
+ ),
106
+ )
107
+ parser.add_argument(
108
+ "--client",
109
+ choices=["auto", "claude", "codex", "json"],
110
+ default="auto",
111
+ help="Target client to configure (default: auto-detect claude/codex).",
112
+ )
113
+ parser.add_argument(
114
+ "--dry-run",
115
+ action="store_true",
116
+ help="Print install commands without executing them.",
117
+ )
118
+ parser.add_argument(
119
+ "--print-policy",
120
+ action="store_true",
121
+ help="Print the recommended policy block for AGENTS.md or system instructions.",
122
+ )
123
+ parser.add_argument(
124
+ "--write-policy",
125
+ metavar="PATH",
126
+ help="Write or update the policy block in a markdown file (e.g. AGENTS.md).",
127
+ )
128
+ parser.add_argument(
129
+ "--print-json",
130
+ action="store_true",
131
+ help="Print JSON MCP config snippet for non-CLI clients.",
132
+ )
133
+
134
+ args = parser.parse_args()
135
+
136
+ any_success = False
137
+ install_targets: list[str] = []
138
+ if args.client == "auto":
139
+ install_targets = detect_supported_clients()
140
+ elif args.client in {"claude", "codex"}:
141
+ install_targets = [args.client]
142
+
143
+ if args.client == "json" or args.print_json:
144
+ print("JSON MCP config snippet:")
145
+ print(render_json_mcp_config())
146
+ print()
147
+
148
+ for client in install_targets:
149
+ ok, output = run_install(client, dry_run=args.dry_run)
150
+ status = "ok" if ok else "error"
151
+ print(f"[{status}] {client}: {output}")
152
+ any_success = any_success or ok
153
+
154
+ if args.client == "auto" and not install_targets:
155
+ print("No supported client CLI found (expected `claude` and/or `codex` on PATH).")
156
+ print("Use --print-json to configure another MCP client.")
157
+
158
+ if args.write_policy:
159
+ policy_path = Path(args.write_policy)
160
+ write_policy(policy_path)
161
+ print(f"Policy block written to {policy_path}")
162
+ any_success = True
163
+ elif args.print_policy:
164
+ print("Recommended policy block:")
165
+ print(render_policy_block())
166
+
167
+ if (
168
+ not install_targets
169
+ and args.client != "json"
170
+ and not args.write_policy
171
+ and not args.print_json
172
+ and not args.print_policy
173
+ ):
174
+ print("Nothing to do. Try `rlm-tools-setup --print-policy --print-json`.", file=sys.stderr)
175
+ sys.exit(1)
176
+
177
+ if install_targets and not any_success and not args.write_policy:
178
+ sys.exit(1)
179
+
@@ -0,0 +1,221 @@
1
+ Metadata-Version: 2.4
2
+ Name: rlm-tools
3
+ Version: 0.1.0
4
+ Summary: MCP server providing a persistent Python sandbox for token-efficient codebase exploration across MCP clients
5
+ Project-URL: Homepage, https://github.com/stefanoshea/rlm-tools
6
+ Project-URL: Repository, https://github.com/stefanoshea/rlm-tools
7
+ Project-URL: Issues, https://github.com/stefanoshea/rlm-tools/issues
8
+ License: MIT License
9
+
10
+ Copyright (c) 2026 Stefan O'Shea
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the "Software"), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all
20
+ copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
+ SOFTWARE.
29
+ License-File: LICENSE
30
+ Requires-Python: >=3.10
31
+ Requires-Dist: anthropic>=0.40.0
32
+ Requires-Dist: mcp[cli]>=1.2.0
33
+ Provides-Extra: dev
34
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
35
+ Requires-Dist: pytest>=8.0; extra == 'dev'
36
+ Description-Content-Type: text/markdown
37
+
38
+ # RLM Tools
39
+
40
+ <!-- mcp-name: io.github.stefanoshea/rlm-tools -->
41
+
42
+ 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.
43
+
44
+ RLM Tools gives your agent a persistent sandbox to explore code in. Data stays server-side. Only the conclusions come back.
45
+
46
+ ```bash
47
+ # For Codex / generic MCP clients
48
+ uvx rlm-tools-setup --write-policy AGENTS.md
49
+
50
+ # For Claude Code
51
+ uvx rlm-tools-setup --write-policy CLAUDE.md
52
+ ```
53
+
54
+ This auto-detects Claude/Codex on your PATH, registers the MCP server, and writes a policy block that nudges agents toward `rlm-tools` for repo exploration. Use `CLAUDE.md` for Claude Code (it reads this file automatically) or `AGENTS.md` for other clients.
55
+
56
+ If you prefer manual setup:
57
+
58
+ ```bash
59
+ # Claude Code
60
+ claude mcp add rlm-tools -- uvx rlm-tools
61
+
62
+ # Codex
63
+ codex mcp add rlm-tools -- uvx rlm-tools
64
+ ```
65
+
66
+ ## What Changes
67
+
68
+ **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.
69
+
70
+ **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:
71
+
72
+ ```python
73
+ matches = grep("import UIKit")
74
+ by_module = {}
75
+ for m in matches:
76
+ module = m["file"].split("/")[0]
77
+ by_module.setdefault(module, []).append(m)
78
+ for module, ms in sorted(by_module.items(), key=lambda x: -len(x[1]))[:5]:
79
+ print(f"{module}: {len(ms)} files")
80
+ ```
81
+
82
+ 500 lines of grep results become 5 lines of summary. The agent sees what it needs, nothing more.
83
+
84
+ ## Real-World Impact
85
+
86
+ In typical coding workflows: **25-35% context reduction.** That means your agent can explore roughly 40-50% more code before hitting context limits.
87
+
88
+ In heavy exploration tasks (reading many files, broad searches), savings go much further:
89
+
90
+ | Scenario | Standard Tools | RLM Tools | Saved |
91
+ |---|---:|---:|---:|
92
+ | Grep across full app | 40,045 chars | 1,644 chars | 95.9% |
93
+ | Read 10 large files | 1,493,720 chars | 13,588 chars | 99.1% |
94
+ | Multi-step exploration | 136,102 chars | 5,285 chars | 96.1% |
95
+ | Grep then read matches | 340,408 chars | 6,022 chars | 98.2% |
96
+ | Find all usages of a pattern | 13,478 chars | 3,691 chars | 72.6% |
97
+ | Understand a module | 94,745 chars | 16,925 chars | 82.1% |
98
+
99
+ Full benchmark methodology and reproduction steps: [`docs/benchmarks.md`](docs/benchmarks.md)
100
+
101
+ ## How It Works
102
+
103
+ Three MCP tools. That's the entire API:
104
+
105
+ | Tool | Purpose |
106
+ |---|---|
107
+ | `rlm_start(path, query)` | Open a session on a directory |
108
+ | `rlm_execute(session_id, code)` | Run Python in the sandbox |
109
+ | `rlm_end(session_id)` | Close session, free resources |
110
+
111
+ The sandbox provides built-in helpers:
112
+
113
+ - `read_file(path)` / `read_files(paths)` — Read files into variables (cached across calls)
114
+ - `grep(pattern)` / `grep_summary(pattern)` / `grep_read(pattern)` — Search
115
+ - `glob_files(pattern)` — Find files by pattern
116
+ - `tree(path, max_depth)` — Directory structure
117
+ - `llm_query(prompt, context)` — Sub-LLM analysis (optional, requires API key)
118
+
119
+ 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.
120
+
121
+ ## Works With
122
+
123
+ RLM Tools is a standard [MCP](https://modelcontextprotocol.io) server. It works with any MCP-compatible client: **Claude Code**, **Codex**, **Cursor**, and others.
124
+
125
+ ### Optional Strict Mode
126
+
127
+ If your MCP client supports tool permissions or hooks, disable/block default read/grep/glob tools for repository exploration and keep `rlm-tools` enabled. This is the strongest way to force the token-efficient path.
128
+
129
+ <details>
130
+ <summary><strong>Other installation methods</strong></summary>
131
+
132
+ ### JSON MCP config (Cursor, Windsurf, etc.)
133
+
134
+ ```json
135
+ {
136
+ "mcpServers": {
137
+ "rlm-tools": {
138
+ "command": "uvx",
139
+ "args": ["rlm-tools"]
140
+ }
141
+ }
142
+ }
143
+ ```
144
+
145
+ ### Setup helper command
146
+
147
+ ```bash
148
+ # Auto-detect Claude/Codex CLIs and configure rlm-tools
149
+ uvx rlm-tools-setup
150
+
151
+ # Print JSON config snippet for other clients
152
+ uvx rlm-tools-setup --print-json
153
+
154
+ # Print policy text instead of writing it
155
+ uvx rlm-tools-setup --print-policy
156
+ ```
157
+
158
+ ### Direct run
159
+
160
+ ```bash
161
+ uvx rlm-tools
162
+ ```
163
+
164
+ ### From source
165
+
166
+ ```bash
167
+ git clone https://github.com/stefanoshea/rlm-tools.git
168
+ cd rlm-tools
169
+ uv sync
170
+ uv run rlm-tools
171
+ ```
172
+
173
+ Then point your MCP client to `command: uv`, `args: ["--directory", "/path/to/rlm-tools", "run", "rlm-tools"]`.
174
+
175
+ </details>
176
+
177
+ ## Configuration
178
+
179
+ Copy `.env.example` to `.env` to customize. All settings are optional — RLM Tools works out of the box with zero config.
180
+
181
+ 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.
182
+
183
+ | Variable | Default | Description |
184
+ |----------|---------|-------------|
185
+ | `ANTHROPIC_API_KEY` | — | Required for `llm_query()` only. Uses Anthropic's API (Claude). |
186
+ | `RLM_SUB_MODEL` | `claude-haiku-4-5-20251001` | Claude model used for `llm_query()` |
187
+ | `RLM_MAX_SESSIONS` | `5` | Max concurrent sessions |
188
+ | `RLM_SESSION_TIMEOUT` | `10` | Session timeout in minutes |
189
+
190
+ ## Security
191
+
192
+ The sandbox is read-only and restricted:
193
+
194
+ - **Imports**: Safe stdlib only (re, json, collections, math, etc.)
195
+ - **Builtins**: Blocks exec, eval, compile, `__import__`, breakpoint
196
+ - **File access**: Read-only, scoped to session directory, path traversal blocked
197
+ - **Execution**: Configurable per-call timeout (default 30s)
198
+ - **Rate limits**: Configurable max calls per session
199
+
200
+ ## Background
201
+
202
+ RLM Tools implements an [RLM-style](https://arxiv.org/abs/2512.24601) exploration loop: keep raw data in tool-side memory, send only compact outputs to the model. Built on the [Model Context Protocol](https://modelcontextprotocol.io).
203
+
204
+ ## Development
205
+
206
+ ```bash
207
+ git clone https://github.com/stefanoshea/rlm-tools.git
208
+ cd rlm-tools
209
+ uv sync --dev
210
+ pytest tests
211
+ ```
212
+
213
+ Run comparative benchmarks (requires a local project checkout):
214
+
215
+ ```bash
216
+ RLM_EVAL_PROJECT_PATH=/path/to/project pytest evals -q -s
217
+ ```
218
+
219
+ ## License
220
+
221
+ MIT
@@ -0,0 +1,13 @@
1
+ rlm_tools/__init__.py,sha256=eR23tRsjCqcmy62hzqAQTBZlDbiku0Z_h81TrHCfDms,77
2
+ rlm_tools/__main__.py,sha256=kXwGR0h4I_1BdqTv1YV6f86NLM1OwukbORECfPc9OPg,65
3
+ rlm_tools/helpers.py,sha256=avMtoAM_v5NWST9Jj30qrXi94b7gltQWQkYvVZX9JtQ,7742
4
+ rlm_tools/llm_bridge.py,sha256=gIrG1cqf5J4lYryC3PF7CJFnQr2J732sp4udMAr8YnE,2150
5
+ rlm_tools/sandbox.py,sha256=ZVHVnvc-N0tNJHSmxoRr-uhXEku3B_5-GCXlA8_Y-Og,4232
6
+ rlm_tools/server.py,sha256=6gB6jhBFlRKq5Y2oI5V9O4WpIQ_qOfiMgK9j2H_z7l4,12158
7
+ rlm_tools/session.py,sha256=t7X8tMBC5ue06HSh8wXIt4XjYfF_t3EPDo58nGnGaAU,2434
8
+ rlm_tools/setup_cli.py,sha256=RBFlHWXb0a4zdFG_rnG_Av7A1CwPIJmkYqUg1CHlpMQ,5678
9
+ rlm_tools-0.1.0.dist-info/METADATA,sha256=JPBklgpg7LM1NGuFevssvv-djUTo8ZwOgtDbHKJNBTI,8260
10
+ rlm_tools-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
11
+ rlm_tools-0.1.0.dist-info/entry_points.txt,sha256=g0dtVQZwnvW0ltHJfhmuhMt0YCKYFb5jpe4067IzQbM,95
12
+ rlm_tools-0.1.0.dist-info/licenses/LICENSE,sha256=wADfpqFrIh8rt6IPISe_5AJyv5xs0QPp_j4pu8q91dE,1070
13
+ rlm_tools-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.28.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ rlm-tools = rlm_tools.server:main
3
+ rlm-tools-setup = rlm_tools.setup_cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Stefan O'Shea
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.