Code Intelligence Platform

A static code analysis platform that builds a Knowledge Graph from your source code and makes it explorable through a Web UI, HTTP API, CLI, and MCP server.

✨ Features

• Knowledge Graph — parses 14+ languages into nodes (functions, classes, files, etc.) and edges (calls, imports, extends, etc.)
• Force-directed Graph Explorer — interactive Sigma.js visualization with color-coded node types, hover highlighting, and filters
• Graph Query Language (GQL) — query your codebase with FIND, TRAVERSE, PATH, COUNT GROUP BY; CLI, HTTP API, and MCP tool
• Source Code Preview — click any node to open syntax-highlighted source at the exact line; "Open in editor" (vscode://) button
• Query Console — web UI panel with GQL editor, sortable results table, query history, and example queries
• AI-Generated Symbol Summaries — optional --summarize flag generates 1-2 sentence summaries per symbol via OpenAI, Anthropic, or Ollama; cached by code hash
• Hybrid Search (BM25 + Vector RRF) — Reciprocal Rank Fusion of keyword + semantic search; searchMode: 'bm25' | 'vector' | 'hybrid' in response
• Semantic Vector Search — embeddings via all-MiniLM-L6-v2; enriched with summaries when available
• Code AI Chat — grounded assistant that cites source files in every answer
• File Watcher & Auto-Reindex — code-intel watch detects file saves and patches the live graph within ~1 second; WebSocket push notifies connected clients
• Code Health — code-intel health reports dead code, circular dependencies (Tarjan SCC), god nodes, orphan files, and a 0–100 health score
• HTTP API — REST endpoints for graph, search, inspect, blast radius, flows, query, source, health
• MCP Server — Model Context Protocol integration for LLM tooling with 6 new reasoning tools (explain_relationship, pr_impact, similar_symbols, health_report, suggest_tests, cluster_summary), pagination, and tool-chaining hints
• Security & Quality Scanning — code-intel secrets (hardcoded API keys, DB URLs, RSA keys), code-intel scan (SQL Injection CWE-89, XSS CWE-79, SSRF CWE-918, Path Traversal CWE-22, Command Injection CWE-78), --format sarif for CI integration
• Complexity Metrics — code-intel complexity --top N ranks functions by cyclomatic + cognitive complexity; complexity_hotspots MCP tool
• Test Coverage Gaps — code-intel coverage lists untested exported symbols sorted by blast radius; --threshold <pct> fails CI if below target
• Deprecated API Detection — code-intel deprecated finds usages of @deprecated JSDoc, @Deprecated (Java), #[deprecated] (Rust), and built-in Node.js deprecated APIs
• CLI — analyze, serve, watch, query, search, inspect, impact, health commands with animated █░ progress bars and braille spinners
• Multi-language — TypeScript, JavaScript, Python, Java, Go, C, C++, C#, Rust, PHP, Ruby, Swift, Kotlin, Dart (14 languages via tree-sitter AST)
• Incremental Analysis — --incremental flag re-parses only git-changed/mtime-changed files; 10k-file repo with 3 changes: 288ms
• Parallel Analysis — --parallel flag runs parse + resolve phases on worker threads for large repos
• AI Context Files — auto-generates AGENTS.md and CLAUDE.md after every analysis (universal, always written); agent-specific files (.github/copilot-instructions.md, .cursor/rules/code-intel.mdc, .windsurfrules) are written only when the corresponding binary is detected on PATH — never pollutes projects with files for tools the user doesn't have; code-intel setup writes all files for user-initiated one-time setup — supporting Amp, Claude Code, Codex, Copilot, Cursor, Aider, Gemini, Kiro, OpenCode, Trae, Hermes, Factory, Pi, Antigravity, OpenClaw, Cline, Windsurf, Kilo Code, and more
• Agent Hook System (v1.0.2) — code-intel setup installs PreToolUse hooks for all major AI agents; when an agent runs grep MyClass src/, the code-intel-hook binary (~10KB, ~50ms startup) silently rewrites it to code-intel search "MyClass" — saving ~3,000 tokens per lookup; supports Claude Code, Cursor, Gemini CLI, GitHub Copilot (VS Code + CLI), OpenCode, OpenClaw; rules files for Cline/Roo Code, Windsurf, Kilo Code, Antigravity, Codex CLI
• Skill Files — generates .claude/skills/code-intel/ with per-cluster SKILL.md files (hot symbols, entry points, impact guidance) for AI assistants
• Repository Groups — multi-repo / monorepo service tracking with workspace auto-discovery (npm, pnpm, Nx, Turborepo), contract extraction (OpenAPI, GraphQL, Protobuf), type-aware similarity scoring, and cross-repo dependency detection
• .codeintelignore — exclude directories from analysis (like .gitignore but for code-intel)
• Structured Logging — winston-based logger with daily-rotating log files at ~/.code-intel/logs/, sensitive-data masking, and configurable log levels
• Performance — parallel batch file I/O, shared file cache (zero double-reads), O(log n) binary-search enclosing-function lookup
• code-intel init Wizard (v0.9) — interactive 5-step setup wizard; creates ~/.code-intel/config.json with editor MCP registration, LLM provider, embeddings, auth mode, and port settings
• Config Management CLI (v0.9) — config get/set/list/validate/reset with JSON Schema, $ENV_VAR expansion, and masked secret output
• Better Error Messages (v0.9) — CI-XXXX error codes, actionable hints, --debug stack traces, startup prerequisite checks
• Shell Completion (v0.9) — code-intel completion bash|zsh|fish; dynamic repo + group name completion; setup --completion auto-installs
• VS Code Extension (v0.9) — symbol hover tooltips, Symbol Explorer panel, status bar freshness indicator, "Open in Graph" command, command palette integration
• Self-Update (v0.9) — code-intel update checks npm registry; background version check on startup; --no-update-check to suppress
• --dry-run flag (v0.9) — analyze, clean, group sync preview what would happen without side effects
• code-intel doctor (v0.9) — full diagnostics: Node.js, git, config, registry, DB integrity, network; exit 1 on any failure
• Lazy Graph Loading (v1.0) — serve starts in <2s for 10k-file repos; LRU node cache (5,000 nodes by default, GRAPH_CACHE_SIZE env var); background warm of high-blast-radius nodes
• Pre-Built BM25 Index (v1.0) — inverted index built at analysis time; loaded into memory on serve startup; 2,000+ q/s throughput; incremental-only updates on re-index
• Memory-Efficient Graph (v1.0) — Int32Array-packed adjacency + symbol interning = ≥30% memory reduction; --max-memory <MB> flag spills node content to DB
• Pipeline Profiling (v1.0) — analyze --profile writes .code-intel/profile.json; per-phase heap memory captured; bottleneck warning if any phase >50% of total; verbose timing table
• Load & Soak Tests (v1.0) — nightly CI load tests (1k/10k fixture repos), weekly soak tests (memory stability, watcher throughput), regression gate: >20% regression fails CI; tests/perf/baseline.json committed to repo
• Graceful Degradation (v1.0) — X-Stale/X-Stale-Since headers on DB outage; LLM-unavailable summarize skip; MCP tool timeout → { truncated: true }; watcher crash recovery; worker crash retry
• Token-Efficient MCP (v1.0.1) — compact JSON responses (null/undefined stripped); MCP tool defaults tuned for LLM sessions: search/file_symbols/list_exports default 10 results (was 50), blast_radius/pr_impact default 2 hops (was 5); suggested_next_tools opt-in via CODE_INTEL_SUGGEST_NEXT_TOOLS=true; ~63% fewer tokens per typical 5-tool session
• Context Builder (v1.0.1) — src/context/builder.ts builds structured [SUMMARY] / [LOGIC] / [RELATION] / [FOCUS CODE] documents from seed symbols in ≤50% of v1.0.0 token cost; query-intent presets (code, callers, architecture, auto); adaptive snippets; cross-block dedup; code-intel context <symbols...> --show-context
• Enforced Tool Policy in AI Context Files (v1.0.1) — AGENTS.md/CLAUDE.md/copilot-instructions.md/.cursor/rules/.kiro/steering now include a TOOL POLICY: ENFORCED block forbidding raw grep/find/cat in favour of code-intel search → inspect → impact; saves ~3,000 tokens per cold-file lookup
• Inspect Disambiguation (v1.0.3) — inspect now detects when a symbol name exists in multiple files; CLI shows a multi-match warning listing all candidates with source previews and suggests --file; MCP returns a disambiguation JSON object instead of silently resolving the wrong class
• --file flag for CLI (v1.0.3) — inspect <symbol> --file <pattern> and impact <symbol> --file <pattern> select the correct implementation when the same name exists across multiple modules (e.g. login in API vs CMS, requestAccessToken in JWT vs Token)
• code-intel read <file> (v1.0.3) — new CLI command reads raw source lines from any indexed file using partial path matching; supports --start/--end line range (max 300 lines per call); essential for reading config files with no indexable symbols
• MCP get_source tool (v1.0.3) — MCP equivalent of read; reads raw numbered source lines from any indexed file by partial path; accepts start_line/end_line; returns hasMore flag for pagination
• BM25 Class-Name Boosting (v1.0.3) — file basename (class name) now weighted strongly in BM25 documents; queries like "Token requestAccessToken" rank the Token class above JWT for same-named methods; content window expanded 1 000 → 1 500 chars
• Claude Code Plugin — PostToolUse & Augment (v1.0.3) — code-intel hook claude now handles both PreToolUse (command rewrite + graph context injection) and PostToolUse (stale-index notification after git commit/merge/pull via HEAD vs .code-intel/meta.json comparison); new code-intel augment -- <pattern> command injects compact symbol context (in:N out:N call counts, snippet) into the agent before grep/rg/cat calls; code-intel hook <agent> now supports claude | cursor | gemini | copilot
• analyze no longer creates unwanted agent files (v1.0.3-patch) — strict binary-only gate: no binary = no file, period; pre-existing files from old runs are NOT updated unless the binary is present; AGENTS.md and CLAUDE.md always written; Kiro, Cline, Kilo Code, Antigravity files are setup-only and never touched by analyze
• Cross-OS Agent Detection & MCP Registration (v1.0.3) — init and setup agent detection and MCP config writing now work correctly on Ubuntu, macOS, and Windows; commandExists() uses execFileSync('which'/'where') instead of a broken shell-composed string; OS-aware path helpers resolve the right config directories; atomic rename retries up to 5× on Windows transient file-lock errors; npx-based MCP entry used for all agents
• Safe MCP config merging — zero data loss (v1.0.3-patch) — mergeJsonFile() creates a .bak backup before every write; Amp uses root-level flat-key merge so no "amp.*" settings are destroyed; all agents check idempotency before writing; Kiro IDE and OpenCode added as first-class setup agents with correct config formats

🚀 Quick Start

Requirements

• Node.js 22+
• npm 10+

Option A — Install globally from npm (recommended)

npm install -g @vohongtho.infotech/code-intel

Note: You may see npm warn ERESOLVE overriding peer dependency warnings about tree-sitter. These are harmless — they relate to native Node.js bindings that are not used; the CLI uses web-tree-sitter (WASM) exclusively. For a warning-free install, add --legacy-peer-deps.

Verify the installation:

code-intel --version

Option B — Build from source

Use this if you want to develop, modify, or contribute to the platform.

1. Clone the repository

git clone https://github.com/vohongtho/code-intel-platform.git
cd code-intel-platform

2. Install all workspace dependencies

npm install --legacy-peer-deps

3. Build all packages (shared → core → web)

npm run build

This runs tsup for the core package (outputs to code-intel/core/dist/) and vite for the web UI (outputs to code-intel/web/dist/).

4. Install the built CLI globally

npm install -g ./code-intel/core

Verify:

code-intel --version

Tip: After making code changes, re-run npm run build — the CLI picks up the new build automatically since the global install points to the local dist/ folder.

Option C — Build locally & install globally (CI / automation)

Use this approach in CI pipelines, Docker images, or any environment where you need a clean, self-contained global install from local source without a persistent node_modules link.

1. Clone & install dependencies

git clone https://github.com/vohongtho/code-intel-platform.git
cd code-intel-platform
npm install --legacy-peer-deps

2. Build all packages

npm run build

3. Pack the core package into a tarball

cd code-intel/core
npm pack
# produces: vohongtho.infotech-code-intel-0.1.4.tgz (version number may vary)
cd ../..

4. Install the tarball globally

npm install -g code-intel/core/vohongtho.infotech-code-intel-*.tgz

5. Verify

code-intel --version

One-liner (copy-paste for CI scripts)

git clone https://github.com/vohongtho/code-intel-platform.git && \
  cd code-intel-platform && \
  npm install --legacy-peer-deps && \
  npm run build && \
  npm pack --workspace=code-intel/core && \
  npm install -g vohongtho.infotech-code-intel-*.tgz

Docker example

FROM node:22-bookworm-slim

RUN git clone https://github.com/vohongtho/code-intel-platform.git /opt/code-intel && \
    cd /opt/code-intel && \
    npm install --legacy-peer-deps && \
    npm run build && \
    npm pack --workspace=code-intel/core && \
    npm install -g vohongtho.infotech-code-intel-*.tgz && \
    rm -rf /opt/code-intel

WORKDIR /workspace
ENTRYPOINT ["code-intel"]

Why pack instead of npm install -g ./code-intel/core? npm pack produces a standalone tarball containing only the published files (the dist/ folder + package.json). This mirrors exactly what is published to npm and avoids bringing in dev symlinks or workspace hoisting artefacts.

Analyze & Serve

# First, analyze the project to build the index
code-intel analyze

# Then start the server (requires an existing index)
code-intel serve

# Or with a specific path and port
code-intel analyze ./my-project
code-intel serve ./my-project --port 4747

Then open http://localhost:4747 in your browser — the Web UI auto-connects and loads the graph.

After analysis

code-intel analyze automatically generates or updates:

• AGENTS.md + CLAUDE.md — AI context files with stats, CLI reference, and skill links. These files are managed with surgical precision:
  • File does not exist → created from a template with a managed block and a clearly marked section for your own notes
  • File exists with markers → only the <!-- code-intel:start -->…<!-- code-intel:end --> block is updated; all your custom content is preserved untouched
  • File exists without markers → the block is appended at the end; existing content is never overwritten
• .claude/skills/code-intel/ — per-cluster SKILL.md files with hot symbols, entry points, and impact guidance

Exclude directories

Create a .codeintelignore file in your project root:

# one directory name per line
vendor
generated
fixtures

🤖 MCP Setup (one-time)

Run the one-time setup command to configure the MCP server and install agent hooks:

code-intel setup

This does two things:

1. MCP server — writes ~/.config/claude/claude_desktop_config.json so your editor can start the MCP server automatically:

{
  "mcpServers": {
    "code-intel": {
      "command": "npx",
      "args": ["@vohongtho.infotech/code-intel", "mcp", "."]
    }
  }
}

2. Agent hooks — installs PreToolUse hooks for every supported AI agent (idempotent, always safe to re-run):

| Agent | Hook type | What it does | |-------|-----------|--------------| | Claude Code | ~/.claude/settings.json PreToolUse | Auto-rewrites grep/cat → code-intel search/inspect | | Cursor | ~/.cursor/hooks.json preToolUse | Auto-rewrites grep/cat → code-intel search/inspect | | Gemini CLI | ~/.gemini/settings.json BeforeTool | Auto-rewrites grep/cat → code-intel search/inspect | | GitHub Copilot | .github/hooks/code-intel-rewrite.json | VS Code Chat: transparent rewrite; CLI: deny + suggestion | | OpenCode | ~/.config/opencode/plugins/code-intel.ts | Plugin: intercepts before tool execution | | OpenClaw | ~/.openclaw/extensions/code-intel/ | Plugin: before_tool_call intercept | | Cline / Roo Code | .clinerules | Prompt-level policy (also written by analyze) | | Windsurf | .windsurfrules | Prompt-level policy (also written by analyze) | | Kilo Code | .kilocode/rules/code-intel-rules.md | Prompt-level policy (also written by analyze) | | Antigravity | .agents/rules/code-intel-rules.md | Prompt-level policy (also written by analyze) | | Codex CLI | AGENTS.md (appended) | Prompt-level policy (also written by analyze) |

How hooks work: The code-intel-hook binary (~10KB, ~50ms startup) intercepts every Bash tool call. When the agent tries to run grep MyClass src/, the hook silently rewrites it to code-intel search "MyClass" — saving ~3,000 tokens per lookup and returning structured graph results instead of raw text.

After setup, the MCP server starts automatically when your AI editor launches, giving it direct access to all code-intel tools.

🖥️ Web UI

| Panel | Description | |-------|-------------| | Explorer | Graph composition stats, search results, overview counters | | Filters | Toggle node/edge types, set focus depth | | Files | Recursive file tree with search filter and file icons | | Group | Multi-repo group view with contracts and cross-repo links (visible when in group mode) | | Graph Canvas | Force-directed graph, click nodes to inspect, hover to highlight neighbors | | Code AI | Chat with grounded answers citing source file locations |

Search Modes

• Keyword (default) — BM25-like text search across node names and content
• ⚡ vec — Semantic vector search using embeddings (auto-built in background after server starts)

Toggle between modes using the vec button in the header search bar.

📦 Architecture

code-intel-platform/
├── code-intel/
│   ├── shared/                    # Shared types published alongside core
│   │   └── src/
│   │       ├── graph-types.ts     # CodeNode, CodeEdge, NodeKind, EdgeKind
│   │       ├── languages.ts       # Language enum (14 languages)
│   │       ├── pipeline-types.ts  # PipelineContext, PhaseResult
│   │       └── detection.ts       # Language detection helpers
│   │
│   ├── core/                      # Backend: pipeline, parsers, HTTP API, MCP, CLI, storage
│   │   └── src/
│   │       ├── pipeline/          # 6-phase DAG orchestrator + DAG validator
│   │       │   └── phases/        # scan · structure · parse · resolve · cluster · flow
│   │       │
│   │       ├── parsing/           # Tree-sitter AST parsing layer
│   │       │   ├── parser-manager.ts   # Loads + caches tree-sitter parsers
│   │       │   ├── ast-cache.ts        # AST memoization
│   │       │   ├── query-runner.ts     # Executes tree-sitter queries
│   │       │   └── queries/            # Per-language query files (14 languages)
│   │       │
│   │       ├── languages/         # Language registry + per-language extraction modules
│   │       │   ├── registry.ts         # Maps file extension → language module
│   │       │   └── modules/            # ts · js · py · java · go · rs · c · cpp · cs
│   │       │                           # php · kt · rb · swift · dart
│   │       │
│   │       ├── resolver/          # Import resolution (edges between files/symbols)
│   │       │   ├── import-resolver.ts
│   │       │   ├── binding-tracker.ts
│   │       │   └── strategies/    # relative-path · package-lookup · namespace-alias · wildcard-expand
│   │       │
│   │       ├── call-graph/        # Call edge builder + call classifier
│   │       ├── inheritance/       # Heritage builder, MRO walker, override detector
│   │       ├── scope-analysis/    # Scope builder (variable / binding scope trees)
│   │       ├── clustering/        # Directory-based community detection
│   │       ├── flow-detection/    # Entry-point finder + execution flow tracer
│   │       │
│   │       ├── graph/             # In-memory knowledge graph (O(1) node/edge lookup)
│   │       ├── search/            # BM25 text search · vector embedder · vector index (LadybugDB)
│   │       ├── storage/           # LadybugDB graph persistence · repo registry · metadata
│   │       │
│   │       ├── multi-repo/        # Repository groups, contract extraction, cross-repo linking
│   │       │   ├── group-registry.ts   # Load/save group configs + sync results
│   │       │   ├── group-sync.ts       # Extract contracts + match via RRF
│   │       │   ├── group-query.ts      # Cross-repo BM25 search with RRF merge
│   │       │   └── types.ts            # RepoGroup, Contract, ContractLink, GroupSyncResult
│   │       │
│   │       ├── http/              # Express REST API + static web UI serving
│   │       ├── mcp-server/        # MCP stdio transport + all tool/resource handlers
│   │       ├── shared/            # Logger (winston, sensitive-data masking, ~/.code-intel/logs/)
│   │       └── cli/               # Commander CLI (progress bars, spinners)
│   │           ├── main.ts              # All CLI commands
│   │           ├── skill-writer.ts      # Generates .claude/skills/code-intel/ SKILL.md files
│   │           └── context-writer.ts    # Upserts AGENTS.md + CLAUDE.md blocks
│   │
│   └── web/                       # React + Sigma.js frontend
│       └── src/
│           ├── pages/             # ConnectPage · LoadingPage · ExplorerPage
│           ├── components/
│           │   ├── graph/         # GraphView (Sigma.js force-directed canvas)
│           │   ├── panels/        # NodeDetail · SearchBar · SidebarChat · SidebarFiles · SidebarFilters
│           │   └── shared/        # Header · StatusFooter · KeyboardShortcutsModal
│           ├── ai/                # Chat agent with intent parsing + tool calls
│           ├── api/               # ApiClient (search, vector-search, inspect, blast-radius, flows, clusters)
│           ├── graph/             # Node color palette + ForceAtlas2 layout utilities
│           └── state/             # React context + reducer (AppContext, AppState)
│
├── .code-intel/                   # Generated per-repo: graph.db · vector.db · meta.json
└── .codeintelignore               # Optional: directories to exclude (like .gitignore)

Pipeline Phases

| Phase | Description | |-------|-------------| | scan | Walk filesystem, collect source files (parallel batch I/O, 512 KB limit), ignore node_modules, dist, .venv, etc. | | structure | Create file and directory nodes in the graph | | parse | Read files in parallel batches of 64, extract symbols (functions, classes, etc.), build per-file sorted function index | | resolve | Resolve imports → edges, build call graph (O(log n) binary-search lookup), detect heritage (extends/implements) | | cluster | Directory-based community detection, add cluster nodes | | flow | Detect entry points, trace execution flows | | summarize | (opt-in) Generate 1–2 sentence AI summaries for function/class/method/interface nodes via OpenAI, Anthropic, or Ollama; skips unchanged nodes (code-hash cache) |

Each phase streams live progress to the CLI via animated █░ progress bars:

  [parse    ] ████████████████░░░░░░░░░░░░░░  53% (80/151)

Post-pipeline steps (DB persist, skill files, context files) show a braille spinner:

  ⠹ Persisting graph to DB…

📋 Logging

Logs are written to ~/.code-intel/logs/ using daily rotation (powered by winston):

| Setting | Default | Override | |---------|---------|----------| | Log directory | ~/.code-intel/logs/ | — | | Log file pattern | YYYY-MM-DD-code-intel.log | — | | Max file size | 20 MB | — | | Retention | 14 days | — | | Log level | info | LOG_LEVEL=debug\|info\|warn\|error\|silent | | Production mode | Console only | NODE_ENV=production |

Sensitive data (passwords, tokens, API keys, emails, credit cards, etc.) is automatically masked before writing — only the first and last character are visible.

🛠️ CLI Commands

Setup

code-intel setup                         # Register the MCP server in your editor config (one-time)

Analyze

code-intel analyze [path]                # Parse source code and build the knowledge graph
code-intel analyze --force               # Discard existing index and perform a full re-analysis
code-intel analyze --skills              # Emit per-cluster SKILL.md files under .claude/skills/code-intel/
code-intel analyze --embeddings          # Build a vector index for semantic (natural-language) search
code-intel analyze --skip-embeddings     # Omit embedding generation for a significantly faster run
code-intel analyze --skip-agents-md      # Preserve any hand-edited content in AGENTS.md / CLAUDE.md
code-intel analyze --skip-git            # Allow analysis of directories that are not Git repositories
code-intel analyze --verbose             # Print every file skipped due to an unsupported parser

Server

code-intel mcp [path]                    # Launch the MCP stdio server consumed by AI-enabled editors
code-intel serve [path] --port <n>       # Start the HTTP API and serve the interactive web UI (default :4747)
code-intel watch [path] --port <n>       # Start HTTP server + file watcher (auto-reindex on file saves)

Query (GQL)

code-intel query "<gql>"                 # Run a GQL query (FIND / TRAVERSE / PATH / COUNT GROUP BY)
code-intel query "<gql>" --format table|json|csv   # Output format (default: table)
code-intel query --file <path.gql>       # Load query from file
code-intel query "<gql>" --limit <n>     # Override LIMIT in the query
code-intel query --save <name> "<gql>"   # Save a named query to .code-intel/queries/
code-intel query --run <name>            # Run a saved query by name
code-intel query --list                  # List all saved queries
code-intel query --delete <name>         # Delete a saved query

Health

code-intel health [path]                 # Show health score + dead code / cycles / god nodes / orphans
code-intel health --dead-code            # List all dead-code symbols
code-intel health --cycles               # List all circular dependency cycles
code-intel health --orphans              # List all orphan files
code-intel health --json                 # Machine-readable JSON output

Registry

code-intel list                          # Display all repositories that have been indexed
code-intel status [path]                 # Report index freshness, symbol counts, and last-run duration
code-intel clean [path]                  # Remove the .code-intel/ index for the specified repository
code-intel clean --all --force           # Permanently remove all indexed repositories (requires --force)

Exploration

code-intel search <query>                # Execute a BM25 keyword search across all indexed symbols
code-intel search <query> --limit <n>    # Limit number of results (default: 20)
code-intel inspect <symbol>              # Show callers, callees, import edges, and source location
code-intel impact <symbol>               # Compute the transitive blast radius of a change to a symbol
code-intel impact <symbol> --depth <n>   # Set maximum traversal depth / hops (default: 5)

Groups (multi-repo / monorepo service tracking)

code-intel group create <name>                                              # Create a named group to track multiple repositories together
code-intel group add <group> <groupPath> <registryName>                    # Enroll an indexed repo in a group under the given hierarchy path
code-intel group remove <group> <groupPath>                                # Remove a repository from a group by its hierarchy path
code-intel group list [name]                                               # List all groups, or print the full membership of one group
code-intel group sync <name>                                               # Extract cross-repo contracts and resolve provider/consumer links
code-intel group contracts <name> [--kind] [--repo] [--min-confidence]    # Inspect extracted contracts and confidence-ranked cross-links
code-intel group query <name> <q>                                          # Run a merged RRF search across every repository in a group
code-intel group status <name>                                             # Audit index freshness and sync staleness for all group members

group add parameters:

• <group> — name of the group
• <groupPath> — hierarchy path (e.g. hr/hiring/backend)
• <registryName> — the repo's name as shown by code-intel list

group contracts options:

• --kind <kind> — filter by contract kind: export | route | schema | event
• --repo <repo> — filter by registry name
• --min-confidence <pct> — minimum link confidence 0–100 (default: 0)

🌐 HTTP API

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/health | Server status, graph size, watcher state | | GET | /api/v1/repos | List indexed repos | | GET | /api/v1/graph/:repo | Full graph (nodes + edges) | | POST | /api/v1/search | BM25 / hybrid text + vector search | | POST | /api/v1/vector-search | Semantic vector search | | GET | /api/v1/vector-status | Vector index ready/building status | | GET | /api/v1/nodes/:id | Node detail (callers, callees, imports, etc.) | | POST | /api/v1/blast-radius | Impact analysis | | POST | /api/v1/query | Execute a GQL query string; returns nodes/edges/groups + executionTimeMs | | POST | /api/v1/query/explain | Return query plan without executing | | GET | /api/v1/source | Fetch file content with ±20 lines context; path-traversal protected | | POST | /api/v1/grep | Regex search in file content | | GET | /api/v1/flows | List detected flows | | GET | /api/v1/clusters | List clusters |

🤖 MCP Server Tools

All tools are available to any MCP-capable editor (Claude Desktop, Claude Code, VS Code, Cursor, etc.) after running code-intel setup.

Core Tools

| Tool | Input | Description | |------|-------|-------------| | repos | (none) | List all indexed repositories with path, indexedAt, and node/edge counts | | overview | (none) | Repository summary: total nodes/edges + full breakdown by kind. Use this first to understand the codebase shape. | | search | query (string), limit (number, default 20) | BM25 / hybrid keyword + semantic search across all symbols | | inspect | symbol_name (string) | 360° view of a symbol: definition, callers, callees, imports, heritage (extends/implements), members, cluster, and source preview | | blast_radius | target (string), direction (callers|callees|both), max_hops (number, default 5) | Impact analysis: traverse the call/import graph to find all affected symbols. Returns a riskLevel (LOW / MEDIUM / HIGH). | | file_symbols | file_path (string, partial match) | List all symbols defined in a file, ordered by line number. Avoids having to read raw source. | | find_path | from (string), to (string), max_hops (number, default 8) | Find the shortest call/import path between two symbols via BFS. | | list_exports | kind (string, optional), limit (number, default 100) | List all exported symbols — the public API surface of the codebase. Filter by kind: function, class, interface, etc. | | routes | (none) | List all HTTP route handler mappings detected in the codebase | | clusters | limit (number, default 50) | List detected code clusters (directory-based communities) with member counts and top 10 symbols each | | flows | limit (number, default 50) | List detected execution flows with entry points, steps, and step counts | | query | gql (string), limit (number, optional) | Execute a GQL query (FIND, TRAVERSE, PATH, COUNT GROUP BY) against the live graph; returns nodes/edges/groups + executionTimeMs | | detect_changes | base_ref (string, default HEAD), diff_text (string, optional) | Git-diff impact analysis: maps changed lines to graph symbols and computes combined blast radius. Ideal for PR review or pre-commit checks. | | raw_query | cypher (string) | (deprecated — use query instead) Simplified Cypher-like graph query: name='X' or :kind |

Group / Multi-Repo Tools

| Tool | Input | Description | |------|-------|-------------| | group_list | name (string, optional) | List all configured repository groups, or show full membership of one group | | group_sync | name (string) | Extract contracts (exports, routes, schemas, events) from all member repos and detect cross-repo provider→consumer links via name matching + RRF scoring | | group_contracts | name (string), kind (export|route|schema|event, optional), repo (string, optional), min_confidence (number 0–1, optional) | Inspect extracted contracts and confidence-ranked cross-repo links from the last sync | | group_query | name (string), query (string), limit (number, default 10) | BM25 search across all repos in a group, merged via Reciprocal Rank Fusion. Returns unified ranked list + per-repo breakdown. | | group_status | name (string) | Check index freshness and sync staleness for all repos in a group. Flags repos as OK, STALE (>24h), or NOT_INDEXED. |

Resources

MCP resources are readable via ReadResource — your editor can pull them as structured context.

| URI | Description | |-----|-------------| | codeintel://repo/<name>/overview | Repository stats: total nodes, edges, and per-kind node counts | | codeintel://repo/<name>/clusters | All cluster nodes with member counts | | codeintel://repo/<name>/flows | All detected execution flows with entry points and steps |

💾 Storage

All generated files are stored locally — nothing is sent to external servers.

| Path | Contents | |------|----------| | .code-intel/graph.db | LadybugDB knowledge graph | | .code-intel/vector.db | LadybugDB vector index | | .code-intel/meta.json | Index metadata (timestamp, stats) | | ~/.code-intel/registry.json | Global registry of all indexed repos | | ~/.code-intel/groups/<name>.json | Repository group configuration | | ~/.code-intel/groups/<name>.sync.json | Last group sync results (contracts + cross-repo links) | | ~/.code-intel/logs/YYYY-MM-DD-code-intel.log | Daily-rotating application logs (14-day retention) |

🧪 Testing

npm run test

46 tests across unit + integration suites covering:

• Knowledge graph operations
• Language detection
• Call classifier
• MRO computation
• Scope analysis
• Text search
• Pipeline integration (parse → resolve)

📊 Benchmark / Eval

Measure accuracy of the knowledge graph, skill files, MCP tools, and context file generation:

# Single-language fixture (TypeScript)
npm run eval

# Multi-language fixture (Python + TypeScript)
npm run eval:multi

# Run all fixtures
npm run eval:all

# Save results as JSON
npm run eval:json

Results are written to eval/results/. Each run scores:

| Phase | What is tested | |-------|---------------| | Analysis | Symbol count, edge count, exit code | | Search | BM25 keyword search accuracy | | Inspect | Symbol detail retrieval | | Impact | Blast radius correctness | | Skill Files | SKILL.md generation, hot symbols, frontmatter | | Context Files | AGENTS.md / CLAUDE.md upsert + idempotency | | Status | Index freshness reporting | | Clean | Index removal |

Current score: 25/25 (100%) TypeScript · 15/15 (100%) multi-lang

Agent Benchmark (Before vs After)

The bench command simulates an AI agent answering code questions with and without code-intel:

npm run bench

Latest results on the TypeScript fixture (6 tasks):

| Metric | Baseline (grep + read files) | Enhanced (code-intel tools) | Δ | |--------|-----------------------------|-----------------------------|---| | Accuracy | 58% | 100% | +42pp | | Tool calls/task | 2.0 | 1.0 | −50% | | Response size | 1023 chars | 189 chars | −82% token cost |

MCP Server Benchmark

Test all MCP tools directly over the JSON-RPC stdio transport:

npm run bench:mcp

Latest results (16 cases, TypeScript fixture):

| Metric | Result | |--------|--------| | Score | 16/16 (100%) | | Avg tool latency | 39ms/call |

Tools tested: repos, search, inspect, blast_radius, routes, raw_query + ListTools, ListResources, ReadResource

🔧 Technical Implementation Details

web-tree-sitter v0.26 API

• Parser.SyntaxNode → Node (named export)
• Parser.Language → Language (named export)
• language.query(src) → new Query(language, src)
• Parser.Language.load() → Language.load()

GraphView (Sigma.js)

• Graph built once from data; Sigma nodeReducer/edgeReducer used for filter/selection/hover changes (no remount)
• stateRef/dispatchRef pattern to avoid stale closures in event handlers
• suppressNextStage guard ensures clickNode event wins over clickStage
• Camera fly-to uses renderer.getNodeDisplayData(id) for normalized coordinates (NOT raw graphology attributes)
• ForceAtlas2 layout applied synchronously after graph build

Multi-repo Groups

• Contract kinds: export, route, schema, event
• Cross-repo matching via Reciprocal Rank Fusion (RRF)
• Confidence scoring for cross-repo links

Build System

• Core: tsup bundler → dist/cli/main.js + dist/index.js
• Web: Vite + Tailwind CSS v4
• esbuild and vite must be in root devDependencies to be hoisted for monorepo npm workspaces

🚢 CI/CD

GitHub Actions Workflows

| Workflow | Trigger | Steps | |----------|---------|-------| | test.yml | PRs | npm ci --legacy-peer-deps + npm test | | quality.yml | PRs | Typecheck shared + core + web | | publish.yml | v*.*.* tags | Typecheck → Test → npm audit → License gate → Build core → Build web → npm publish --provenance → Build + push multi-arch Docker (linux/amd64 + linux/arm64) → Trivy CRITICAL CVE gate → cosign keyless sign → GitHub Release with CycloneDX SBOM → Discord notification |

Publishing a New Version

# Bump version in code-intel/core/package.json, then:
git tag v0.1.5
git push origin v0.1.5

The publish workflow automatically runs all checks, builds the packages, publishes to npm, and sends a Discord notification (📦 success or ❌ failure).

Required GitHub Secrets:

| Secret | Purpose | |--------|---------| | NPM_TOKEN | npm access token with publish rights | | DISCORD_WEBHOOK | Discord webhook URL for deploy notifications |

Local CI Simulation

docker compose -f docker-compose.build.yml build

Uses node:22-bookworm-slim — the same base image as GitHub Actions.

📄 License

MIT © 2024