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, HTML (15 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, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/code-intel.mdc, .kiro/steering/code-intel.md, .clinerules, .windsurfrules, .kilocode/rules/code-intel-rules.md, and .agents/rules/code-intel-rules.md after every analysis — supporting Amp, Claude Code, Codex, Copilot, Cursor, Aider, Gemini, Kiro, Trae, Hermes, Factory, OpenCode, 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

• 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

  • OpenAPI note: contract extraction currently parses JSON OpenAPI/Swagger specs. YAML filenames are discovered, but YAML parsing is not implemented in v1.0.4.

• Multi-Layer Exclusion System — exclude files and folders from analysis with .codeintelignore (team, tracked), .codeintelignore.local (personal, gitignored), or CLI flags --skip-folders / --skip-files (per-run); supports basename matching (tests), path matching (src/legacy), and glob patterns (**/*.generated.ts)

• 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; LRU-capped hot-query cache for repeated searches

• 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

  • Worker note for v1.0.4: parallel analysis retries worker crashes, but v1.0.4 does not introduce a new user-facing worker timeout control. Treat long/stalled analysis as runtime investigation, not documented timeout recovery behavior.

• 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

Related MCP server: CodeAtlas MCP Server

🚀 Quick Start

Requirements

• Node.js 22.17+

• npm 10+

Option A — Install globally from npm (recommended)

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

Default secret storage: the CLI stores secrets in the encrypted .code-intel/.secrets file backend. No OS keychain package is required for the default install.

Upgrade note for v1.0.4: After upgrading, re-build the local index before comparing results or using serve/status against old data:

code-intel analyze --force

This refreshes .code-intel/graph.db and .code-intel/meta.json. Comparing fresh CLI behavior against stale indexes can look like a regression when it is only old index state.

Upgrade note for sticky embeddings: if a repo was previously indexed with semantic search, the next code-intel analyze will detect legacy vector.db state, normalize .code-intel/meta.json, and keep embeddings up to date automatically. Older CLI builds may ignore the remembered preference until upgraded, but they should continue to tolerate the extra metadata fields.

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

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/). The core build also copies bundled tree-sitter WASM grammars, including tree-sitter-html.wasm, into code-intel/core/dist/wasm/ for packaged installs.

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

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 && \
  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 && \
    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

# Or assign a stable unique repo name
code-intel analyze ./my-project --name api-core

# 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

Stable repository names and IDs

Indexed repositories now have:

• a stable internal id

• a unique user-facing name

• a mutable filesystem path

Use names for lookup. IDs stay stable across rename and relink operations.

code-intel repo list
code-intel repo show api-core
code-intel repo rename api-core api-platform
code-intel repo relink api-platform ../new-location

code-intel analyze naming rules:

• new path + new --name creates a named repo entry

• existing path + same --name refreshes that repo

• existing path + different --name fails; use code-intel repo rename

• new path + existing --name fails; use code-intel repo relink

Legacy registries without repo IDs migrate automatically on load. If old entries share the same basename-derived name, the migration repairs duplicates deterministically and prints a warning so you can rename them later.

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

If no admin account exists yet, the first-run setup screen appears. The login and bootstrap forms include eye-icon password visibility toggles, and the username input placeholder reads User Name.

Authenticated users can open Settings from the profile menu in the Web UI to inspect global server configuration. Admin users can edit routed settings sections for LLM, embeddings, analysis, server, authentication, updates, and telemetry. These settings are server-global and complement the CLI flows (code-intel init and code-intel config *) rather than replacing editor/MCP setup.

After analysis

code-intel analyze automatically generates or updates:

• AGENTS.md + CLAUDE.md — AI context files with a concise code-intel guidance block. 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

Exclude files and folders from analysis

Code-intel provides a multi-layer exclusion system for fine-grained control over what gets analyzed:

1. .codeintelignore (team-level, tracked)

Create a .codeintelignore file in your project root for team-wide exclusions:

# Exclude specific folders
vendor
generated
fixtures

# Exclude specific files
config.generated.ts
schema.proto.ts

# Exclude by pattern (glob)
*.min.js
**/*.test.ts
src/legacy/**

Pattern types:

• Basename match: tests → matches any file or folder named "tests" anywhere

• Path match: src/legacy → matches only that specific path from workspace root

• Glob match: **/*.generated.ts → matches all generated TypeScript files at any depth

2. .codeintelignore.local (personal preferences, gitignored)

Create a .codeintelignore.local file for personal exclusions that won't be committed:

# My personal preferences (not tracked in git)
examples
docs
tutorials

This file is automatically added to .gitignore when you run code-intel analyze.

3. CLI flags (one-off exclusions)

For temporary or experimental exclusions, use CLI flags:

# Exclude specific folders for this run only
code-intel analyze --skip-folders tests,examples

# Exclude files by pattern
code-intel analyze --skip-files "*.generated.ts,*.proto.ts"

# Combine multiple exclusions
code-intel analyze --skip-folders src/legacy --skip-files config.gen.ts

# Repeatable flags (alternative syntax)
code-intel analyze --skip-folders tests --skip-folders examples

All layers combine additively — an entry excluded by any layer is excluded from analysis.

🤖 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):

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

Settings

• Open Settings from the profile menu in the top-right header, above Sign out.

• Settings routes use /settings/:section with browser back/forward support instead of #fragment anchors.

• Settings are server-global for the connected code-intel instance, not per-user preferences.

• Authenticated viewers can inspect masked config values; admins can save edits.

• code-intel init and code-intel config * remain the CLI source for first-run setup and editor/MCP registration. The Web UI settings screen complements those commands; it does not replace editor/MCP setup in v1.

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
│   │           └── 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

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

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

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

  ⠹ Persisting graph to DB…

📋 Logging

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

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 auto-use incremental mode when prior metadata makes it safe
code-intel analyze --force               # Discard existing index and perform a full re-analysis
code-intel analyze --embeddings          # Build a vector index and remember embeddings for this repo
code-intel analyze --skip-embeddings     # Skip embedding generation for this run only
code-intel analyze --skip-agents-md      # Preserve any hand-edited content in AGENTS.md / CLAUDE.md

Sticky embeddings behavior:

• The first successful code-intel analyze --embeddings run stores the repo preference in .code-intel/meta.json.

• Later code-intel analyze, code-intel analyze --incremental, and code-intel analyze --force runs auto-enable embeddings for that repo unless you pass --skip-embeddings.

• Plain code-intel analyze now auto-attempts incremental graph reindexing when valid prior .code-intel/meta.json exists and incremental safety checks pass; otherwise it falls back to full analysis.

• If vector.db is missing, stale, corrupted, or incompatible with the current embedding fingerprint, code-intel analyze rebuilds the full vector index automatically.

• --skip-embeddings does not forget the repo preference; it skips vectors for that run and marks remembered embeddings stale until the next normal analyze.

• Previously indexed repos with only a legacy vector.db upgrade in place on the next analyze; no manual migration command is required.

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 intent-aware symbol search
code-intel search <query> --limit <n>    # Limit number of results (default: 20)
code-intel search <query> --json         # Include machine-readable qualified selectors
code-intel inspect <symbol>              # Inspect a unique symbol; lists candidates when ambiguous
code-intel inspect <selector>            # Inspect an exact qualified result from search/inspect
code-intel inspect <symbol> --json       # Structured result; ambiguity exits with status 2
code-intel impact <symbol-or-selector>   # Compute the transitive blast radius of a selected symbol
code-intel impact <symbol> --depth <n>   # Set maximum traversal depth / hops (default: 5)

Qualified selectors use <kind>:<percent-encoded-name>@<path>[:line]; path separators remain readable. Copy selectors from command output; for example:

code-intel search "how to login portal"
code-intel inspect "login"               # Ambiguous names print ranked selectors
code-intel inspect "method:login@code-intel/web/src/api/client.ts:84"
code-intel impact "method:login@code-intel/web/src/api/client.ts:84"

# Relevance/performance regression check (from code-intel/core)
npm run build && node tests/perf/search-relevance-bench.mjs

The benchmark uses 10,003 symbols. Budgets: cold search <250ms; warm cached search <25ms.

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

🤖 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

Reasoning Tools

Security & Quality Tools

Group / Multi-Repo Tools

Resources

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

💾 Storage

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

🧪 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, 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:

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):

MCP Server Benchmark

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

npm run bench:mcp

Latest results (19 cases, TypeScript fixture):

Tools tested: repos, search (default / bm25 / vector), context, 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

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:

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