rlm-navigator 0.1.0 → 0.1.1

package/.claude/agents/rlm-subcall.md

@@ -0,0 +1,65 @@
+# RLM Sub-Agent — Chunk Analyst
+
+## Role
+You are a lightweight analysis agent (prefer Haiku model). Given file chunks or skeletons and a user query, identify relevant symbols and guide exploration.
+
+## Input
+You receive:
+1. A **query** describing what the user is looking for
+2. One or more **file chunks** (from `write_chunks()`) or **file skeletons** (from `rlm_map`)
+3. A **chunk_id** identifying the current chunk (e.g., `"server.py:chunk_3"`)
+4. Optionally a **directory tree** (output from `rlm_tree`)
+
+## Output
+Return a JSON object following this exact schema:
+
+```json
+{
+  "chunk_id": "file.py:chunk_3",
+  "relevant": [
+    {
+      "file": "src/auth.py",
+      "symbol": "authenticate_user",
+      "lines": "L45-82",
+      "confidence": 0.95,
+      "reason": "Directly handles user authentication flow"
+    }
+  ],
+  "missing": ["Token refresh logic not found in this chunk"],
+  "suggested_next_queries": [
+    "map src/middleware.py for request interception",
+    "search for 'refresh_token' in src/"
+  ],
+  "answer_if_complete": null
+}
+```
+
+## Field Rules
+
+### `relevant` (max 10 items)
+- Rank by confidence (highest first)
+- Include file path, symbol name, line range, confidence (0-1), and reason
+- Only include symbols actually relevant to the query
+
+### `missing`
+- List what the query asks about but was NOT found in this chunk
+- Helps the orchestrator know what still needs to be located
+
+### `suggested_next_queries`
+- Each entry should be an actionable RLM tool call description
+- Format: `"<action> <target> for <reason>"`
+- Examples: `"map src/db.py for database connection handling"`, `"search 'cache' in lib/"`, `"drill handle_request in daemon/rlm_daemon.py"`
+- Max 5 suggestions, ordered by priority
+
+### `answer_if_complete`
+- Set to `null` unless the query is FULLY answerable from this chunk alone
+- When set, provide a concise answer string
+- The orchestrator will stop delegating chunks when this is non-null
+
+## Rules
+- Be concise — your output feeds back into the main agent's context
+- Maximum 10 relevant items per response
+- Do NOT drill into files yourself — just identify what to drill
+- Do NOT fabricate line numbers — use ranges from the chunk header or skeleton output
+- If the query is vague, return the top 3-5 most likely candidates
+- Always populate `suggested_next_queries` unless `answer_if_complete` is set

package/.claude/skills/rlm-navigator/SKILL.md

@@ -0,0 +1,125 @@
+# RLM Navigator — Recursive Codebase Navigation Skill
+
+## Purpose
+Navigate codebases with minimal token usage by treating source files as hierarchical trees of AST skeletons. Never read full files when signatures suffice.
+
+## Workflow — ALWAYS follow this order:
+
+### 1. Health Check
+```
+get_status
+```
+If offline, tell the user to start the daemon:
+```
+python daemon/rlm_daemon.py --root <project_path>
+```
+
+### 2. Explore Structure (never use `ls`, `find`, or `Glob`)
+```
+rlm_tree path="" max_depth=3
+```
+See directory layout, file sizes, detected languages. Narrow down to relevant subdirectories.
+
+### 3. Read Signatures (never `cat` or `Read` full files)
+```
+rlm_map path="src/main.py"
+```
+See function/class/method signatures + docstrings. Bodies are replaced with `...`.
+This tells you WHAT exists without consuming tokens on HOW.
+
+### 4. Surgical Drill (only when you need implementation details)
+```
+rlm_drill path="src/main.py" symbol="process_data"
+```
+Reads ONLY the lines of the specific symbol. This is the only time implementation code is loaded.
+
+### 5. Search Across Files
+```
+rlm_search query="authenticate" path="src/"
+```
+Find where a symbol is defined across multiple files without reading any of them.
+
+## Rules
+
+- **NEVER read a full file** unless the file is under 50 lines or you've confirmed via `rlm_map` that you need the entire thing.
+- **NEVER use `ls`, `find`, `Glob`** for directory exploration — use `rlm_tree`.
+- **Map before drill** — always `rlm_map` a file before `rlm_drill` into it.
+- **Minimize drill calls** — only drill symbols you actually need to understand or modify.
+- **Batch your thinking** — after mapping, decide ALL symbols you need, then drill them in sequence.
+- **Prefer skeleton references** — when discussing code, reference signatures from `rlm_map` output rather than drilling just to quote code.
+
+## When NOT to use RLM
+
+- Files you're about to edit entirely (use Read tool directly)
+- Config files under 20 lines (just read them)
+- Files you've already drilled into this conversation (they're in context)
+
+## Sub-Agent Delegation
+
+For large directories with many files, delegate to the `rlm-subcall` agent:
+- Give it the `rlm_tree` output and your query
+- It will identify which files are relevant
+- You then `rlm_map` only those files
+
+## REPL-Assisted Analysis
+
+For multi-step analysis that builds on previous findings:
+
+### Setup
+```
+rlm_repl_init
+```
+Initializes a stateful Python REPL with helpers: `peek()`, `grep()`, `chunk_indices()`, `write_chunks()`, `add_buffer()`.
+
+### Explore with Helpers
+```
+rlm_repl_exec code="print(grep('TODO|FIXME|HACK', 'src/'))"
+```
+Use `peek()` to read specific line ranges, `grep()` for regex search across files.
+
+### Accumulate Findings
+```
+rlm_repl_exec code="add_buffer('auth_flow', 'Step 1: Token validated in middleware.py:45')"
+rlm_repl_exec code="add_buffer('auth_flow', 'Step 2: User loaded in auth.py:92')"
+```
+Use `add_buffer(key, text)` to collect findings across multiple exec calls.
+
+### Export Results
+```
+rlm_repl_export
+```
+Retrieves all accumulated buffers for synthesis.
+
+### Rules
+- Initialize REPL at the start of complex analysis sessions
+- Use buffers to collect findings rather than relying on context window
+- Variables persist between `rlm_repl_exec` calls — assign intermediate results
+- Reset with `rlm_repl_reset` when switching to unrelated analysis
+
+## Chunk-Delegate-Synthesize Workflow
+
+For large files or cross-file analysis, use the chunk-delegate pattern:
+
+### 1. Chunk via REPL
+```
+rlm_repl_exec code="paths = write_chunks('src/large_module.py', size=200, overlap=20); print(paths)"
+```
+Splits the file into manageable chunks written to `.claude/rlm_state/chunks/`.
+
+### 2. Delegate Each Chunk
+Send each chunk to the `rlm-subcall` sub-agent with:
+- The chunk content (from `peek()` or the chunk file)
+- The user's query
+- A `chunk_id` (e.g., `"large_module.py:chunk_0"`)
+
+### 3. Follow Suggested Queries
+The sub-agent returns `suggested_next_queries` — these are actionable RLM tool calls. Execute the highest-priority ones to fill in gaps identified in the `missing` field.
+
+### 4. Synthesize
+When a sub-agent returns `answer_if_complete` (non-null), or when all chunks have been analyzed, synthesize the collected `relevant` items and buffer contents into a final answer.
+
+### When to Use This Workflow
+- Files over 500 lines that need thorough analysis
+- Cross-file analysis spanning 5+ files
+- Architecture understanding tasks ("how does X work end-to-end?")
+- When a single `rlm_map` + `rlm_drill` cycle is insufficient

package/bin/cli.js

@@ -82,10 +82,21 @@ async function install() {
     process.exit(1);
   }
 
-  // 1. Copy daemon/ and server/ into .rlm/
-  console.log("[1/5] Copying daemon and server into .rlm/ ...");
+  // 1. Copy daemon/, server/, and .claude/ into .rlm/ and project
+  console.log("[1/5] Copying daemon, server, and skills ...");
   copyDirSync(path.join(PKG_ROOT, "daemon"), path.join(RLM_DIR, "daemon"));
   copyDirSync(path.join(PKG_ROOT, "server"), path.join(RLM_DIR, "server"));
+
+  // Copy .claude/skills/ and .claude/agents/ into project's .claude/
+  const srcSkills = path.join(PKG_ROOT, ".claude", "skills");
+  const srcAgents = path.join(PKG_ROOT, ".claude", "agents");
+  const destClaude = path.join(CWD, ".claude");
+  if (fs.existsSync(srcSkills)) {
+    copyDirSync(srcSkills, path.join(destClaude, "skills"));
+  }
+  if (fs.existsSync(srcAgents)) {
+    copyDirSync(srcAgents, path.join(destClaude, "agents"));
+  }
   console.log("  Done.\n");
 
   // 2. Install Python deps
@@ -188,7 +199,19 @@ function uninstall() {
     console.log(".rlm/ not found — nothing to remove.\n");
   }
 
-  // 3. Remove CLAUDE.md snippet
+  // 3. Remove .claude/skills/rlm-navigator/ and .claude/agents/rlm-subcall.md
+  const skillDir = path.join(CWD, ".claude", "skills", "rlm-navigator");
+  const agentFile = path.join(CWD, ".claude", "agents", "rlm-subcall.md");
+  if (fs.existsSync(skillDir)) {
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    console.log("Removed .claude/skills/rlm-navigator/");
+  }
+  if (fs.existsSync(agentFile)) {
+    fs.unlinkSync(agentFile);
+    console.log("Removed .claude/agents/rlm-subcall.md");
+  }
+
+  // 4. Remove CLAUDE.md snippet
   const claudeMdPath = path.join(CWD, "CLAUDE.md");
   if (fs.existsSync(claudeMdPath)) {
     const content = fs.readFileSync(claudeMdPath, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rlm-navigator",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Token-efficient codebase navigation for AI-assisted coding",
   "bin": {
     "rlm-navigator": "./bin/cli.js"
@@ -12,6 +12,8 @@
     "server/src/",
     "server/package.json",
     "server/tsconfig.json",
-    "templates/"
+    "templates/",
+    ".claude/skills/",
+    ".claude/agents/"
   ]
 }