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

• 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

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

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

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

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

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

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

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 (16 cases, TypeScript fixture):

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

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