feat: add repo map codebase intelligence

.gitattributes

@@ -59,6 +59,7 @@ CODE_OF_CONDUCT* text
 *.xml text
 *.csv text
 *.sql text
+*.scm text eol=lf
 
 # Graphics (binary)
 *.png binary

README.md

@@ -248,6 +248,7 @@ Advanced and source-build guides:
 - **Images**: URL and base64 image inputs for providers that support vision
 - **Provider profiles**: Guided setup plus saved user-level provider profile support
 - **Local and remote model backends**: Cloud APIs, local servers, and Apple Silicon local inference
+- **Codebase intelligence (repo map)**: Structural map of the repository ranked by PageRank importance, auto-injected into context when the `REPO_MAP` flag is enabled. Inspect with `/repomap` (2048-token default). See [docs/repo-map.md](docs/repo-map.md) for details.
 
 ## Provider Notes
 

docs/repo-map.md

@@ -0,0 +1,67 @@
+# Codebase Intelligence — Repo Map
+
+The repo map feature gives the AI model structural awareness of your codebase at the start of each session. Instead of the model needing to explore the repository with `Grep`, `Glob`, and `Read` calls, it starts with a ranked summary of the most important files and their key signatures.
+
+## How it works
+
+1. **File enumeration** — Lists all tracked files via `git ls-files` (falls back to a manual directory walk when not in a git repo)
+2. **Symbol extraction** — Parses each supported source file with tree-sitter to extract function, class, type, and interface definitions, plus cross-file references
+3. **Reference graph** — Builds a directed graph where an edge from file A to file B means A references a symbol defined in B. Edges are weighted by reference count multiplied by the IDF (inverse document frequency) of the symbol name — common names like `get`, `set`, `value` contribute less
+4. **PageRank** — Ranks files by structural importance using PageRank. Files imported by many others rank highest
+5. **Rendering** — Walks ranked files top-down, emitting file paths and definition signatures, stopping when the token budget is reached
+
+Results are cached to disk (`~/.openclaude/repomap-cache/`) keyed by file path, mtime, and size. Only changed files are re-parsed on subsequent runs.
+
+## Supported languages
+
+- TypeScript (`.ts`, `.tsx`)
+- JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`)
+- Python (`.py`)
+
+Additional language grammars will be added in future releases.
+
+## Enabling auto-injection
+
+The repo map is gated behind the `REPO_MAP` feature flag, **off by default**. To enable auto-injection into the session context:
+
+Set the environment variable before launching:
+
+```bash
+REPO_MAP=1 openclaude
+```
+
+Or add it to your shell profile for persistent use.
+
+When enabled, the map is built once per session and prepended to the system context alongside git status and CLAUDE.md content. The auto-injected map uses a 1024-token budget.
+
+Auto-injection is skipped in:
+- Bare mode (`--bare`)
+- Remote sessions (`CLAUDE_CODE_REMOTE`)
+
+## The /repomap slash command
+
+The `/repomap` command is always available regardless of the feature flag. It lets you inspect and tune the map interactively.
+
+```text
+/repomap                          # Show the map with default settings (2048 tokens)
+/repomap --tokens 4096            # Increase the token budget for a larger map
+/repomap --focus src/tools/       # Boost specific paths in the ranking
+/repomap --focus src/context.ts   # Can use multiple --focus flags
+/repomap --stats                  # Show cache statistics
+/repomap --invalidate             # Clear cache and rebuild from scratch
+```
+
+## The RepoMap tool
+
+The model can also call the `RepoMap` tool on demand during a session. This is useful when:
+- The model needs structural context mid-conversation
+- The user asks about specific areas (the model can pass `focus_files` or `focus_symbols`)
+- A larger token budget is needed than the auto-injected default
+
+## Known limitations
+
+- **Signatures only** — The map shows function/class/type declarations, not implementations. The model still needs `Read` to see function bodies.
+- **Cold build time** — First build on large repos (2000+ files) can take 20-30 seconds due to WASM-based parsing. Subsequent builds use the disk cache and complete in under 100ms.
+- **Language coverage** — Only TypeScript, JavaScript, and Python are supported. Files in other languages are skipped.
+- **TypeScript references** — The TypeScript tree-sitter query captures type annotations and `new` expressions as references, but not plain function calls. This means the ranking slightly favors type-heavy hub files.
+- **Git dependency** — File enumeration uses `git ls-files` by default. Non-git repos fall back to a directory walk with hardcoded exclusions.

knip.json

@@ -16,6 +16,7 @@
   "project": ["src/**/*.{ts,tsx}", "scripts/**/*.ts"],
   "ignore": [
     "src/integrations/generated/**",
+    "src/context/repoMap/__fixtures__/**",
     "src/services/internalLogging.ts",
     "src/types/generated/**",
     "src/test/fixtures/**",

package.json

@@ -105,11 +105,14 @@
     "fflate": "0.8.2",
     "figures": "6.1.0",
     "fuse.js": "7.1.0",
+    "graphology": "0.26.0",
     "get-east-asian-width": "1.5.0",
     "google-auth-library": "10.6.2",
     "https-proxy-agent": "7.0.6",
     "ignore": "7.0.5",
+    "graphology-metrics": "2.4.0",
     "indent-string": "5.0.0",
+    "js-tiktoken": "1.0.21",
     "jsonc-parser": "3.3.1",
     "lodash-es": "4.18.1",
     "lru-cache": "11.2.7",
@@ -127,10 +130,12 @@
     "signal-exit": "4.1.0",
     "supports-hyperlinks": "3.2.0",
     "tree-kill": "1.2.2",
+    "tree-sitter-wasms": "0.1.13",
     "turndown": "7.2.2",
     "type-fest": "4.41.0",
     "undici": "7.28.0",
     "usehooks-ts": "3.1.1",
+    "web-tree-sitter": "0.25.10",
     "vscode-languageserver-protocol": "3.17.5",
     "wrap-ansi": "9.0.2",
     "ws": "8.21.0",

scripts/build.ts

@@ -100,6 +100,9 @@ const featureFlags: Record<string, boolean> = {
   COWORKER_TYPE_TELEMETRY: false, // Telemetry for agent/coworker type classification
   MCP_SKILLS: true,               // Dynamic MCP skill discovery via skill:// resources
 
+  // ── Disabled by default, opt-in via runtime env var ─────────────────
+  REPO_MAP: false,                // Auto-injected codebase intelligence repo-map; users opt in with REPO_MAP=1 (the runtime gate in src/context.ts honors the env var even when this flag is false)
+
   // ── Enabled: upstream defaults ──────────────────────────────────────
   COORDINATOR_MODE: true,             // Multi-agent coordinator with worker delegation
   BUILTIN_EXPLORE_PLAN_AGENTS: true,  // Built-in Explore/Plan specialized subagents

scripts/externals.ts

@@ -25,6 +25,13 @@ export const COMMON_EXTERNALS: string[] = [
   // Orama search engine
   '@orama/orama',
   '@orama/plugin-data-persistence',
+  // web-tree-sitter ships a WASM file alongside its JS and resolves the
+  // path via require.resolve at runtime; bundling would freeze the build
+  // host's absolute path, so keep it external.
+  'web-tree-sitter',
+  // tree-sitter-wasms ships per-language .wasm files resolved via
+  // require.resolve at runtime — same bundling concern as web-tree-sitter.
+  'tree-sitter-wasms',
 ]
 
 // Additional packages external only in the SDK bundle (TUI + heavy deps)
@@ -124,4 +131,9 @@ export const INTENTIONALLY_BUNDLED: string[] = [
   'vscode-languageserver-protocol',
   // File watching
   'chokidar',
+  // Graph algorithms (repo map PageRank)
+  'graphology',
+  'graphology-metrics',
+  // Tokenizer for repo map token budgeting
+  'js-tiktoken',
 ]

src/commands.ts

@@ -27,6 +27,7 @@ import doctor from './commands/doctor/index.js'
 import onboardGithub from './commands/onboard-github/index.js'
 import knowledge from './commands/knowledge/index.js'
 import memory from './commands/memory/index.js'
+import repomap from './commands/repomap/index.js'
 import help from './commands/help/index.js'
 import ide from './commands/ide/index.js'
 import init from './commands/init.js'
@@ -331,6 +332,7 @@ const COMMANDS = memoize((): Command[] => [
   releaseNotes,
   reloadPlugins,
   rename,
+  repomap,
   replay,
   requestSize,
   requestSizeNonInteractive,

src/commands/repomap/index.ts

@@ -0,0 +1,17 @@
+/**
+ * /repomap command - minimal metadata only.
+ * Implementation is lazy-loaded from repomap.ts to reduce startup time.
+ */
+import type { Command } from '../../commands.js'
+
+const repomap = {
+  type: 'local',
+  name: 'repomap',
+  description:
+    'Show or configure the repository structural map (codebase intelligence)',
+  isHidden: false,
+  supportsNonInteractive: true,
+  load: () => import('./repomap.js'),
+} satisfies Command
+
+export default repomap