RepoLens MCP

Local-first repository intelligence for AI coding agents. Index a repo into SQLite, expose architecture-aware MCP tools, and inspect code relationships in a browser dashboard.

RepoLens MCP is an original TypeScript implementation built around fast local verification, readable internals, and reviewable engineering evidence. It focuses on the workflows engineers actually need during AI-assisted development: finding code, tracing symbols, checking impact, and preserving architecture decisions.

Core Capabilities

MCP-native workflow: 38 tools grouped around indexing, code search, graph search, tracing, impact analysis, project inventory, fleet views, report generation, and ADR memory.
Code graph extraction: captures symbols, routes, imports, package manifests, lockfiles, infrastructure files, protocol surfaces, event channels, typed relationships, conservative data flow, runtime traces, and HTTP route-call links.
Local verification loop: repeatable full/incremental benchmarks, package-boundary checks, release gates, graph packages, dashboard/report artifacts, and security-summary commands keep validation inspectable.
Agent-ready setup: doctor inspects the local Codex MCP configuration, install-codex can add a managed MCP block with dry-run and force safeguards, uninstall-codex removes only managed RepoLens config, agent-hook provides executable non-blocking broad-search reminders, and agent-setup/install-agents generate reviewable guidance plus opt-in hook/reminder files for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro, including a managed local Claude PreToolUse hook config.
Local-first SQLite memory: all indexed data stays in .repolens/memory.db.
Project catalog and cross-repo graphing: list-projects, project-status, fleet-summary, fleet-graph, and delete-project track indexed repositories, aggregate languages/routes/HTTP calls/dependencies, and produce a catalog-wide graph with shared dependencies, route overlaps, inferred consumer/provider service links, and shareable HTML/JSON artifacts through fleet-graph --out.
Incremental refreshes: skip unchanged files, prune removed files, preserve the existing graph when a repo has not changed, optionally refresh on MCP startup with REPOLENS_AUTO_INDEX, and keep long-running MCP sessions fresh with git-aware REPOLENS_AUTO_SYNC.
Persistent local config: config set auto-index incremental and config set auto-sync true store defaults for MCP startup indexing, live-session syncing, root, database path, max file size, max file count, labels, graph-package bootstrap, and diagnostics output without requiring shell env vars.
Watch mode: keep an indexed graph fresh during active coding with polling-based incremental refreshes, optionally skipping unchanged git polls with --git-aware.
Operational diagnostics: opt into JSONL lifecycle events for index, benchmark, watch, MCP startup auto-index, and auto-sync runs with --diagnostics, REPOLENS_DIAGNOSTICS, or persistent diagnostics-path.
Portable graph and report artifacts: export self-contained interactive HTML graph explorers, architecture reports, and compressed .rlgz graph packages from the CLI; first index can bootstrap a missing database from .repolens/graph.rlgz.
Operational dashboard: browse an interactive graph explorer with filtering, hover/click node inspection, legend, pause, and fit controls, plus structural filters, references, semantic/vector search, schema counts, relationship patterns, label property hints, fleet service links, dead-code candidates, review signals, and report links without a frontend build.
Graph communities: detects functional modules from weighted relationships, not just folder names.
Code-aware search ranking: uses SQLite FTS5 BM25 ranking with indexed camelCase and snake_case term expansion, so create order can find createOrder without scanning files.
Reference lookup: finds exact indexed identifier references and labels definition lines for language-server-style navigation without requiring an external LSP process.
Type relationship graph: adds INHERITS, IMPLEMENTS, and USES_TYPE edges from class/interface/protocol declarations and typed signatures for safer impact analysis.
Configuration links: extracts config keys from repo-local config files and links config keys, dependency declarations, and referenced config files back to code with CONFIGURES edges.
Receiver-aware call graph: resolves TypeScript/JavaScript calls such as repo.save() to the method on the inferred constructed class, avoiding ambiguous same-name method edges.
Local semantic and vector search: adds dependency-free SIMILAR_TO and SEMANTICALLY_RELATED edges, concept search, and persisted local vector embeddings over names, paths, signatures, metadata, and symbol bodies.
Context packs for agents: one query can return semantic matches, vector matches, graph matches, BM25 code hits, snippets, and nearby edges for focused development context.
Redacted secret scan: review high-confidence token shapes, sensitive assignments, and environment references from indexed source/config lines without returning raw secret values.
Resolved import graph: creates IMPORTS_FILE edges for relative imports, file-like includes/requires, dotted or backslash namespaces, workspace package names, source-root imports, and tsconfig/jsconfig path aliases.
Route-call edges: stores literal HTTP requests as http_call nodes, connects callers with CALLS_HTTP_ENDPOINT, and links matching in-repo routes with HTTP_CALLS.
Runtime trace ingestion: imports observed HTTP, event, or symbol traces as OBSERVED_* graph edges with counts and timestamps.
Channel/event edges: detects EventEmitter, Socket.IO-style, DOM custom event, Python decorator/call, and Swift NotificationCenter channels with EMITS and LISTENS_ON edges.
Protocol surfaces: extracts GraphQL operations/types, gRPC services/RPC routes from protobuf, OpenAPI routes, and common tRPC procedures/calls.
Manifest and lockfile dependency graph: extracts declared package/dependency nodes from npm, Composer, Python, Go, Cargo, Maven, Gradle, Dart, Elixir, Ruby, and requirements.txt manifests, plus pinned lockfile and locked_dependency nodes from common package-manager locks.
Infrastructure graph nodes: indexes Dockerfile stages/images, Kubernetes resources, container images, and Kustomize overlays with DECLARES, CONFIGURES, and IMPORTS edges.
Architecture recommendations: turns structural hotspots, git-history churn, import-resolved dependency cycles, dead-code candidates, and review signals into concrete next steps.
Wide practical coverage: TypeScript, JavaScript, Python, Go, Java, Rust, Swift, C/C++, C#, Kotlin, PHP, Ruby, Elixir, Dart, Terraform/HCL, QML, Apex, SQL, YAML, Markdown, JSON, and shell-oriented project files.
Project-specific language overrides: map framework or template extensions in .repolens.json, such as treating .astro or .view files as TypeScript for indexing.
Validation evidence: tests, CI, CodeQL, OpenSSF Scorecard, CycloneDX SBOM generation, GitHub build-provenance attestations, docs, local dashboard smoke checks, and a documented local big-repo validation run.
Architecture decisions built in: persist ADR-style decisions next to the code graph.
No frontend build required: the dashboard is served by the CLI.

Security And Quality

Protected mainline: main requires PR review, CODEOWNERS review, fresh branch checks, resolved conversations, linear history, verify, and CodeQL Analyze; force pushes and branch deletion are blocked.
GitHub security coverage: CodeQL, OpenSSF Scorecard, Dependabot security updates, secret scanning with push protection, private vulnerability reporting, pinned workflow actions, least-privilege workflow tokens, and a release gate that blocks publishing when actionable CodeQL, Dependabot, or secret-scanning alerts are open or alert APIs are unavailable.
Property-based fuzzing: fast-check fuzzes import resolver traversal boundaries, safe alias/source-root/workspace-package resolution, and MCP JSON-RPC tool-call validation in tests/security-fixes.test.ts and tests/mcp-server.test.ts.
Release integrity: npm provenance, GitHub build-provenance attestations, CycloneDX SBOM generation, lockfile dependency graphing, clean builds, dry-run package validation, and a package contents gate that blocks local graph artifacts and stale compiled output from being published.
Agent-readable docs: llms.txt and docs/agent-guide.md give coding agents a concise operating guide, data-boundary rules, and validation commands.

Quick Start

npm install
npm run build
node --experimental-sqlite dist/src/cli.js index .
node --experimental-sqlite dist/src/cli.js architecture
node --experimental-sqlite dist/src/cli.js serve

Then open http://127.0.0.1:9749.

The dashboard includes an interactive graph explorer, code search, reference lookup, semantic/vector search, graph search, graph schema tables with relationship patterns and label property hints, fleet service links, hotspot and boundary summaries, git-history signals, dead-code candidates, and one-click Markdown/HTML architecture reports.

From a local clone, the installer runs the same build and Codex checks:

./install.sh --install-codex --dry-run
./install.sh --install-codex
./install.sh --install-agents --dry-run
./install.sh --install-agents --with-hooks --dry-run
./install.sh --uninstall-agents --dry-run

Windows PowerShell uses the same installer flow:

.\install.ps1 -InstallCodex -DryRun
.\install.ps1 -InstallCodex
.\install.ps1 -InstallAgents -DryRun
.\install.ps1 -InstallAgents -WithHooks -DryRun
.\install.ps1 -UninstallAgents -DryRun

Project-specific language suffixes can be mapped in .repolens.json without changing RepoLens source:

{
  "languages": {
    ".astro": "typescript",
    ".view": "typescript",
    "*.blade.php": "php"
  }
}

CLI

repolens-mcp index [repo] [--db path] [--max-file-bytes n] [--max-files n] [--incremental] [--label name] [--write-package [graph.rlgz]] [--diagnostics [path|true|off]]
repolens-mcp index [repo] [--bootstrap-package .repolens/graph.rlgz] [--no-bootstrap]
repolens-mcp version [--check] [--registry url]
repolens-mcp update-check [--registry url]
repolens-mcp benchmark [repo] [--db path] [--max-file-bytes n] [--max-files n] [--no-secret-scan] [--diagnostics [path|true|off]]
repolens-mcp list-projects [--limit n]
repolens-mcp project-status [root-or-db-or-label]
repolens-mcp delete-project <root-or-db-or-label> [--delete-db]
repolens-mcp fleet-summary [--limit n]
repolens-mcp fleet-graph [--limit n] [--max-nodes n] [--max-edges n] [--out fleet.html|fleet.json]
repolens-mcp config list|get|set|reset|path [key] [value]
repolens-mcp architecture [--db path]
repolens-mcp search <query> [--db path]
repolens-mcp scan-secrets [--db path] [--limit n] [--min-confidence low|medium|high] [--include-tests]
repolens-mcp symbols <query> [--kind function]
repolens-mcp snippet <symbol-or-path:line> [--context n]
repolens-mcp references <symbol> [--db path] [--limit n]
repolens-mcp trace <symbol> [--direction inbound|outbound|both] [--mode all|calls|data_flow|cross_service] [--parameter name]
repolens-mcp impact <path-or-symbol...>
repolens-mcp schema [--db path]
repolens-mcp communities [--db path] [--limit n] [--min-size n]
repolens-mcp watch [repo] [--db path] [--interval-ms n] [--git-aware] [--diagnostics [path|true|off]]
repolens-mcp search-graph [query] [--kind function] [--relationship CALLS] [--min-degree n]
repolens-mcp semantic "live session repository" [--limit n]
repolens-mcp vector "live session repository" [--limit n]
repolens-mcp context-pack "create order" [--limit n] [--context n]
repolens-mcp query-graph "MATCH (a)-[:CALLS]->(b) RETURN a.name,b.name LIMIT 5"
repolens-mcp dead-code [--db path]
repolens-mcp cycles [--db path] [--limit n]
repolens-mcp ingest-traces traces.json [--db path]
repolens-mcp changes [repo] [--db path]
repolens-mcp report [--db path] [--format markdown|html] [--graph-limit n] [--out report.html]
repolens-mcp export-graph --out graph.html [--db path]
repolens-mcp pack-graph --out graph.rlgz [--db path] [--label name]
repolens-mcp unpack-graph graph.rlgz [--db path] [--overwrite]
repolens-mcp doctor [--config ~/.codex/config.toml] [--name repolens]
repolens-mcp install-codex [--db .repolens/memory.db] [--dry-run] [--force]
repolens-mcp uninstall-codex [--dry-run]
repolens-mcp agent-setup [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--db .repolens/memory.db] [--with-hooks]
repolens-mcp install-agents [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--dry-run] [--with-hooks]
repolens-mcp uninstall-agents [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--dry-run] [--with-hooks]
repolens-mcp agent-hook|hook-augment [--db .repolens/memory.db] [--name repolens] [--json|--claude] [--with-query]
repolens-mcp decision --title "Use SQLite" --body "Keep memory local."
repolens-mcp decision-update 1 --status accepted --tags sqlite,privacy
repolens-mcp decision-delete 1
repolens-mcp serve [--db path] [--port 9749]
repolens-mcp mcp

MCP Tools

Tool	Purpose
`index_repository`	Build or refresh the local SQLite memory, optionally bootstrapping from a `.rlgz` graph package when the database is missing.
`version_status`	Report installed package and Node versions, plus optional npm latest-version/update guidance.
`benchmark_repository`	Run full and no-op incremental indexing, graph totals, throughput, and optional redacted secret-scan summary for repeatable performance evidence.
`export_graph_package`	Create a compressed, checksummed `.rlgz` package from an indexed graph database.
`import_graph_package`	Import a compressed `.rlgz` package into a local graph database.
`manage_config`	Read or update persistent RepoLens defaults for startup auto-indexing and graph paths.
`list_projects`	List repositories indexed through RepoLens on this machine.
`index_status`	Return the latest indexed status for a root, database path, label, or project folder name.
`delete_project`	Remove a project from the local catalog, with optional safe `.repolens` DB cleanup.
`fleet_summary`	Aggregate indexed projects by language, package, dependency, route, HTTP call, route overlap, and inferred service link.
`cross_repo_graph`	Return a catalog-wide graph of indexed repositories, shared dependencies, overlapping routes, and inferred cross-repo HTTP caller/provider edges.
`agent_setup`	Render or write project-local RepoLens MCP setup guidance for supported coding agents.
`search_code`	Search indexed source lines with BM25 ranking and code-aware token expansion.
`scan_secrets`	Scan indexed source/config lines for redacted secret, token, credential, and sensitive environment patterns.
`search_symbols`	Search functions, classes, routes, resources, headings, and package nodes.
`get_code_snippet`	Return source lines around a symbol, qualified name, file path, or `path:line` target.
`find_references`	Find indexed definition and reference lines for a symbol or identifier.
`get_architecture`	Return language mix, hotspots, git-history churn, entrypoints, packages, and risk markers.
`trace_symbol` / `trace_path`	Trace inbound, outbound, or bidirectional paths around a symbol; modes include calls, data flow, cross-service HTTP/event edges, and unfiltered graph traversal.
`impact_analysis`	Find adjacent symbols for changed files or symbols.
`get_graph_schema`	Return node labels, edge types, relationship patterns, label properties, language coverage, and totals.
`find_communities`	Detect weighted graph communities with representative symbols, cohesion, and boundary counts.
`search_graph`	Search structurally by query, kind, regex, relationship, file scope, or degree.
`semantic_search`	Search symbols by local semantic token overlap across names, paths, signatures, and bodies.
`vector_search`	Search symbols with deterministic local vector embeddings over names, paths, signatures, metadata, and bodies.
`context_pack`	Return semantic matches, vector matches, graph matches, code hits, snippets, and nearby edges for one query.
`query_graph`	Run a read-only Cypher-like query over symbols and one-hop edges.
`find_dead_code`	Find non-exported functions and methods with no inbound call edges.
`find_dependency_cycles`	Find import-resolved dependency cycles between architecture clusters.
`ingest_traces`	Add observed runtime HTTP, event, or symbol edges as `OBSERVED_*` relationships.
`detect_changes`	Map uncommitted git changes to indexed graph impact with per-file blast radius, relationship counts, and risk reasons.
`architecture_report`	Generate a markdown or HTML architecture report with graph, hotspot, history, risk, and recommendation sections.
`remember_decision`	Persist an ADR-style architecture decision.
`list_decisions`	Retrieve saved decisions.
`update_decision`	Update an existing architecture decision without rewriting unspecified fields.
`delete_decision`	Delete an architecture decision by id.
`graph_snapshot`	Export compact graph data for dashboards or reviews.

Supported Extraction

The extractor is intentionally compact and extensible:

TypeScript and JavaScript: classes, interfaces, types, functions, const functions, imports, resolved local import edges, Express-style routes, and Next.js App Router app/api/**/route.ts handlers.
Receiver-aware TypeScript/JavaScript call edges: method symbols are attached to parent classes, and constructor-assigned receivers such as const repo = new MemoryOrderRepository() resolve repo.save() to the matching class method instead of every method named save.
Conservative data-flow edges: maps meaningful call arguments to target parameters when the callee can be resolved without ambiguous duplicate names, and prunes stale DATA_FLOWS edges during incremental refreshes.
Trace modes: trace_path can focus on call paths, value propagation through DATA_FLOWS, cross-service HTTP/event paths, or all nearby edges.
HTTP call linking: literal fetch, Axios, and Node http calls become http_call nodes with CALLS_HTTP_ENDPOINT; matching route nodes also receive HTTP_CALLS.
GraphQL, gRPC, and OpenAPI: .graphql, .gql, .proto, OpenAPI JSON, and OpenAPI YAML files produce protocol nodes; protobuf rpc methods become route nodes using /Service/Method paths, and OpenAPI {id} path params normalize to :id.
tRPC: common procedure declarations and client calls become trpc_procedure and trpc_call nodes.
Channel/event linking: EventEmitter/Socket.IO-style emit, on, once, addListener, subscribe, DOM CustomEvent, Python @*.on, and Swift NotificationCenter patterns become channel nodes with EMITS and LISTENS_ON edges.
Swift: classes, structs, enums, protocols, actors, functions, and imports.
Python: classes, functions, imports, route decorators.
Go, Java, Rust: common functions, methods, types, classes, traits, structs, imports, and route decorators where applicable.
C/C++, C#, Kotlin, PHP, Dart, Ruby, Elixir, QML, and Apex: practical symbol extraction for classes/interfaces/records/modules/functions/methods, imports/includes/uses/requires, plus C#/PHP/Kotlin/Apex route annotations and route helpers.
SQL: created tables, views, indexes, functions, procedures.
Terraform/HCL: resource, data, module, variable, output, and provider blocks, including module source import edges.
YAML: multi-document Kubernetes resources from kind and metadata.name, container image links, and Kustomize resources, bases, and components.
Dockerfile: build stages, base images, and COPY --from stage dependencies.
Markdown: headings as knowledge nodes.
Manifest files: package.json, composer.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle, pubspec.yaml, mix.exs, and *.gemspec package/dependency nodes.
Lockfiles: package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, yarn.lock, composer.lock, Cargo.lock, poetry.lock, go.sum, and Gemfile.lock become lockfile and locked_dependency nodes connected by LOCKS edges.

Repository Ignore Rules

Add .repolensignore at the repository root to exclude generated code, local scratch folders, vendored samples, or sensitive paths from indexing. Rules are path-relative globs with ! negation, similar to .gitignore; RepoLens still applies its built-in skips for dependency folders, build outputs, binaries, and .repolens artifacts.

Local Graph Artifact Cleanup

.repolens/ is gitignored and can grow when you run benchmarks, imports, dashboard exports, or large-repo validation locally. Review old artifacts with:

find .repolens -maxdepth 1 -type f -size +50M -print

Use repolens-mcp delete-project <root-or-db-or-label> --delete-db for catalog-tracked databases, or manually remove reviewed scratch artifacts you no longer need. Do not publish .repolens/ databases or graph packages without reviewing them for derived source metadata.

Query Graph Subset

query-graph and query_graph are read-only. Supported patterns:

MATCH (f:Function) WHERE f.name = 'main' RETURN f.name,f.filePath LIMIT 10
MATCH (a)-[r:CALLS]->(b) WHERE b.name CONTAINS 'order' RETURN a.name,b.name,r.type LIMIT 10
MATCH (a)<-[:CALLS]-(b) RETURN a.name,b.name LIMIT 10
MATCH (s) WHERE s.kind IN ['function', 'method'] RETURN s.name,s.kind LIMIT 10
MATCH (s) WHERE s.kind = 'route' OR s.kind = 'http_call' RETURN s.name,s.kind LIMIT 10
MATCH (a)-[r]->(b) WHERE r.weight >= 0.7 RETURN a.name,b.name,r.weight LIMIT 10
MATCH (f:Function) RETURN count(f) AS functions
MATCH (f:Function) RETURN DISTINCT f.name ORDER BY f.name SKIP 10 LIMIT 10

Supported WHERE operators are =, <>, CONTAINS, STARTS WITH, ENDS WITH, IN, >, >=, <, and <=, joined with AND or OR; AND binds tighter than OR. Supported result clauses include RETURN DISTINCT, count(...), ORDER BY, SKIP, and LIMIT.

Validation

npm run verify
npm run test:skip-gate
npm run package:check
npm run installer:audit
npm run audit:prod
GITHUB_REPOSITORY=sameer2191/repolens-mcp GH_TOKEN="$(gh auth token)" npm run security:github
GITHUB_REPOSITORY=sameer2191/repolens-mcp GH_TOKEN="$(gh auth token)" npm run release:security-gate
node --experimental-sqlite dist/src/cli.js index /path/to/big/repo --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js benchmark /path/to/big/repo --db /tmp/benchmark.db
node --experimental-sqlite dist/src/cli.js list-projects
node --experimental-sqlite dist/src/cli.js project-status /path/to/big/repo
node --experimental-sqlite dist/src/cli.js fleet-summary
node --experimental-sqlite dist/src/cli.js fleet-graph --limit 20 --max-nodes 500 --max-edges 1000 --out /tmp/repolens-fleet.html
node --experimental-sqlite dist/src/cli.js index /path/to/big/repo --db /tmp/memory.db --incremental
node --experimental-sqlite dist/src/cli.js architecture --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js schema --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js communities --db /tmp/memory.db --limit 12
node --experimental-sqlite dist/src/cli.js snippet createOrder --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js references createOrder --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js semantic "order checkout flow" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js vector "order checkout flow" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js context-pack "order checkout flow" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js cycles --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js query-graph "MATCH (f:Function) RETURN f.name,f.filePath LIMIT 5" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js ingest-traces traces.json --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js report --db /tmp/memory.db --format html --out report.html
node --experimental-sqlite dist/src/cli.js export-graph --db /tmp/memory.db --out graph.html --limit 1000
node --experimental-sqlite dist/src/cli.js pack-graph --db /tmp/memory.db --out graph.rlgz --label validation
node --experimental-sqlite dist/src/cli.js unpack-graph graph.rlgz --db /tmp/imported-memory.db
node --experimental-sqlite dist/src/cli.js watch /path/to/big/repo --db /tmp/memory.db --interval-ms 2500 --git-aware
node --experimental-sqlite dist/src/cli.js config set auto-index incremental
node --experimental-sqlite dist/src/cli.js config set root /path/to/big/repo
node --experimental-sqlite dist/src/cli.js serve --db /tmp/memory.db --port 9749
node --experimental-sqlite dist/src/cli.js agent-setup --target /tmp/project --agents all

Security-summary commands need a token that can read GitHub security-alert endpoints; see SECURITY.md for local token requirements.

The repo includes docs/research-notes.md with source-research notes and design decisions, plus docs/BENCHMARK.md with sanitized validation evidence for the npm package.

Team-Shared Graph Bootstrap

Create a reusable graph package:

repolens-mcp index . --db .repolens/memory.db --write-package

--write-package without a value writes .repolens/graph.rlgz after a successful index. Pass a path such as --write-package artifacts/service.rlgz to write somewhere else, or use REPOLENS_WRITE_PACKAGE=.repolens/graph.rlgz for session-wide automation. .rlgz packages are marked as binary by .gitattributes; review them before force-adding ignored .repolens artifacts to a repository.

On another machine or a fresh clone, the first index will import .repolens/graph.rlgz when the target database is missing, then run an incremental refresh for local changes:

repolens-mcp index . --db .repolens/memory.db

Use --bootstrap-package path/to/graph.rlgz for a custom artifact, REPOLENS_BOOTSTRAP_PACKAGE=path/to/graph.rlgz for MCP/session-wide configuration, or --no-bootstrap / REPOLENS_BOOTSTRAP_PACKAGE=0 to force a fresh database.

MCP Client Config

Codex users can inspect or install the MCP entry directly:

repolens-mcp doctor
repolens-mcp install-codex --db .repolens/memory.db --dry-run
repolens-mcp install-codex --db .repolens/memory.db
repolens-mcp uninstall-codex --dry-run

install-codex refuses to replace an existing unmanaged mcp_servers.repolens entry unless --force is passed. uninstall-codex removes only the RepoLens managed block and leaves unmanaged MCP entries untouched.

Optional startup indexing for MCP sessions:

[mcp_servers.repolens.env]
REPOLENS_DB = ".repolens/memory.db"
REPOLENS_AUTO_INDEX = "1"          # incremental startup refresh
REPOLENS_AUTO_SYNC = "1"           # keep a long-running MCP session fresh after git changes
REPOLENS_AUTO_SYNC_INTERVAL_MS = "2500"
REPOLENS_ROOT = "."                # optional, defaults to process cwd
REPOLENS_MAX_FILE_BYTES = "750000" # optional
REPOLENS_MAX_FILES = "5000"        # optional, fail closed on unexpected huge repos
REPOLENS_DIAGNOSTICS = "true"      # optional, writes .repolens/diagnostics.jsonl

Set REPOLENS_AUTO_INDEX=full to force a full rebuild on startup. Leave it unset for the default manual-index behavior. REPOLENS_AUTO_SYNC=1 starts a background git-aware watcher after startup; unchanged HEAD/status polls are skipped, while committed or dirty worktree changes trigger incremental refreshes.

You can also persist those defaults without shell env vars:

node --experimental-sqlite dist/src/cli.js config set auto-index incremental
node --experimental-sqlite dist/src/cli.js config set auto-sync true
node --experimental-sqlite dist/src/cli.js config set auto-sync-interval-ms 2500
node --experimental-sqlite dist/src/cli.js config set root /path/to/repo
node --experimental-sqlite dist/src/cli.js config set db-path /path/to/repo/.repolens/memory.db
node --experimental-sqlite dist/src/cli.js config set max-files 5000
node --experimental-sqlite dist/src/cli.js config set diagnostics-path .repolens/diagnostics.jsonl

Project teams can generate agent guidance and config snippets for the broader agent set:

repolens-mcp agent-setup --target . --agents all
repolens-mcp install-agents --target . --agents codex,claude,gemini --dry-run
repolens-mcp install-agents --target . --agents codex,claude,gemini --with-hooks --dry-run
repolens-mcp install-agents --target . --agents codex,claude,gemini
repolens-mcp uninstall-agents --target . --agents codex,claude,gemini --with-hooks --dry-run

install-agents writes managed markdown blocks into project-local instruction files and a docs/repolens-agent-setup.md guide. For VS Code it also writes a project-local .vscode/mcp.json servers.repolens entry while preserving unrelated servers. Add --with-hooks to generate opt-in, non-blocking hook/reminder files plus docs/repolens-agent-hooks.md; for Claude Code it also merges a managed .claude/settings.local.json PreToolUse hook entry while preserving unrelated hooks and settings. These files tell agents when to call RepoLens before broad searches or risky edits and include an executable hook-augment --claude command for agents that pass hook payload JSON through stdin. agent-hook/hook-augment recognizes PreToolUse-style Grep, Glob, and broad shell search payloads, emits either text, JSON, or Claude-compatible hookSpecificOutput.additionalContext, exits successfully, and does not intercept Read/Edit/Write tools. The hook does not query or mutate the local graph by default; add --with-query only when you want it to open the RepoLens database and append symbol metadata matches. uninstall-agents --with-hooks removes those managed reminder files and the managed Claude hook entry alongside managed RepoLens markdown blocks and managed VS Code config entries while preserving hand-written content. The MCP agent_setup tool is dry-run by default; write mode is limited to the server working directory, and executable hook writes require REPOLENS_ALLOW_MCP_HOOK_WRITES=1, so interactive CLI installers are the recommended hook setup path. The guide includes MCP config snippets for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.

{
  "mcpServers": {
    "repolens-mcp": {
      "command": "npx",
      "args": ["-y", "@sameermir/repolens-mcp", "mcp"],
      "env": {
        "REPOLENS_DB": ".repolens/memory.db"
      }
    }
  }
}

Architecture

flowchart LR
  Repo["Repository files"] --> Walker["Ignore-aware walker"]
  Walker --> Extractor["Language extractors"]
  Extractor --> Store["SQLite memory"]
  Store --> MCP["MCP tools"]
  Store --> CLI["CLI"]
  Store --> Dashboard["Local dashboard"]
  MCP --> Agent["AI coding agent"]

Roadmap

Optional parser-backed adapters for deeper language-specific call/use precision where regex extractors are not enough.
Host-aware service-link inference from config, environment variables, and trace data.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

RepoLens MCP

Core Capabilities

Security And Quality

Quick Start

CLI

MCP Tools

Supported Extraction

Repository Ignore Rules

Local Graph Artifact Cleanup

Query Graph Subset

Validation

Team-Shared Graph Bootstrap

MCP Client Config

Architecture

Roadmap

About

Uh oh!

Releases 2

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
install.ps1		install.ps1
install.sh		install.sh
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

RepoLens MCP

Core Capabilities

Security And Quality

Quick Start

CLI

MCP Tools

Supported Extraction

Repository Ignore Rules

Local Graph Artifact Cleanup

Query Graph Subset

Validation

Team-Shared Graph Bootstrap

MCP Client Config

Architecture

Roadmap

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages