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 +1 -0
- rlm_tools/__main__.py +5 -0
- rlm_tools/helpers.py +212 -0
- rlm_tools/llm_bridge.py +69 -0
- rlm_tools/sandbox.py +136 -0
- rlm_tools/server.py +331 -0
- rlm_tools/session.py +78 -0
- rlm_tools/setup_cli.py +179 -0
- rlm_tools-0.1.0.dist-info/METADATA +221 -0
- rlm_tools-0.1.0.dist-info/RECORD +13 -0
- rlm_tools-0.1.0.dist-info/WHEEL +4 -0
- rlm_tools-0.1.0.dist-info/entry_points.txt +3 -0
- rlm_tools-0.1.0.dist-info/licenses/LICENSE +21 -0
rlm_tools/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""RLM Tools - Persistent Python REPL for MCP-based codebase exploration."""
|
rlm_tools/__main__.py
ADDED
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
|
rlm_tools/llm_bridge.py
ADDED
|
@@ -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,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.
|