CodeExplorer.Cli 1.39.0

CodeExplorer (ce)

CodeExplorer (ce) is a static analysis engine and embedded graph database for polyglot codebases. It parses source files, project manifests, HTTP endpoints, message broker topologies, and SQL schemas into a local SQLite graph (graph.db) with a built-in OpenCypher-to-SQL compiler.

It is designed for three workflows:

1. Model Context Protocol (MCP) Server: Gives coding agents (Claude Code, Cursor, GitHub Copilot, Cline) direct access to call chains, cross-service dependencies, data lineage, and impact analysis without reading entire repositories into context.
2. Semantic Invariant Gates (SIG): Enforces architectural boundaries in CI and in the IDE using declarative OpenCypher rules and SHA-256 ratchet baselines.
3. VS Code Architecture Explorer: Visualizes service topologies, project dependency flows, and bounded contexts with direct navigation to source files.

<p align="center"> <img src="docs/all_services.png" alt="CodeExplorer Service Topology" width="100%" /> </p> <p align="center"> <em>Service topology projected across concentric architectural tiers (Ingress, Public Services, Message Brokers, Domain Services, and Databases).</em> </p>

<p align="center"> <a href="#installation">Installation</a> • <a href="#quick-start">Quick Start</a> • <a href="#mcp-server">MCP Server</a> • <a href="#semantic-invariant-gates">Invariant Gates</a> • <a href="#vs-code-extension">VS Code Extension</a> • <a href="#supported-languages--frameworks">Languages</a> • <a href="#graph-ontology">Ontology</a> • <a href="#cli-reference">CLI Reference</a> • <a href="#mcp-tools">MCP Tools</a> </p>

Installation

CodeExplorer is distributed as a self-contained single-file binary (ce / ce.exe) with embedded Tree-sitter grammars and SQLite, and as a VS Code extension that bundles the native binary for your platform.

Homebrew (macOS & Linux)

brew install vmikhailov/tap/ce

VS Code Extension

Install from the Visual Studio Marketplace or Open VSX Registry:

code --install-extension vmikhailov.code-explorer-vscode

Install Script

macOS & Linux:

curl -fsSL https://raw.githubusercontent.com/vmikhailov/code-explorer/main/cli/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/vmikhailov/code-explorer/main/cli/scripts/install.ps1 | iex

.NET Global Tool

dotnet tool install -g CodeExplorer.Cli

Prebuilt Binaries

Standalone archives are available on GitHub Releases:

Quick Start

# 1. Initialize .codeexplorer/ in your repository
ce init

# 2. Parse ASTs, project references, endpoints, and cross-service links
ce scan

# 3. Inspect workspace summary and node/edge counts
ce status

# 4. Run a built-in or ad-hoc OpenCypher query
ce query -n get_architecture_map_workspace
ce query "MATCH (s:Service)-[:CALLS]->(t:Service) RETURN s.name, t.name"

# 5. Evaluate architectural gates
ce gate check

# 6. Start the MCP server (stdio)
ce mcp

MCP Server

Text search (grep, ripgrep) works well for finding literals, but it cannot reliably trace interface implementations, cross-service HTTP/gRPC calls, message queue publishers/consumers, or SQL table usage across projects. Reading dozens of files to reconstruct call graphs consumes context window budget and degrades agent accuracy.

Running ce mcp exposes the indexed SQLite graph over the Model Context Protocol:

• Architecture & Entry Points: Query projects, dependencies, HTTP/gRPC/GraphQL endpoints, and message consumers via get_architecture_map and get_project_entry_points.
• Low-Token File Outlines: Inspect classes, methods, and line ranges in a file via get_file_outline before reading full source text.
• Impact & Lineage Analysis: Trace downstream callers of a symbol (analyze_code_impact) or all SQL/ORM readers and writers of a database table (inspect_data_lineage).
• OpenCypher Queries: Execute read-only Cypher queries (execute_custom_read_cypher) and save reusable project queries in .codeexplorer/queries/.

Client Configuration

Add ce to your MCP client configuration (.cursor/mcp.json, claude_desktop_config.json, or VS Code MCP settings):

{
  "mcpServers": {
    "code-explorer": {
      "command": "ce",
      "args": ["mcp"]
    }
  }
}

For HTTP/SSE transport:

ce mcp --port 8085

Recommended AGENTS.md / CLAUDE.md Snippet

## CodeExplorer (`ce`) MCP Guidelines
- Start architectural exploration with `get_architecture_map` and `get_project_dependencies` instead of broad file searches.
- Use `find_symbol` and `get_file_outline` to locate declarations and line ranges before reading large files.
- Run `analyze_code_impact` or `get_call_chain` before changing shared interfaces or methods.
- Run `inspect_data_lineage` before modifying database tables or ORM entities.
- Use `execute_custom_read_cypher` for multi-hop structural queries.

Semantic Invariant Gates

Linters validate syntax and style within single files. Semantic Invariant Gates (SIG) validate structural and architectural rules across the entire repository by executing OpenCypher queries against the graph.

How Gates Work

Every gate follows a Zero-Match Contract:

• 0 rows returned: Gate passes.
• 1 or more rows returned: Each returned row is a violation with file:line:column coordinates, offending symbol, target, and remediation message.

FAIL: SIG-P-B-001 [Clean Architecture Layer Isolation]
  src/Core/Services/OrderService.cs:42:15: OrderService -> SqliteConnection
    Domain Core module directly references Infrastructure driver.

Defining a Gate (.codeexplorer/gates/*.yaml)

id: SIG-P-B-001
name: Clean Architecture Layer Isolation
category: Architectural
platform: agnostic
scope: Module
dimension: Boundaries
severity: Error
description: Domain Core projects must not reference Infrastructure or UI projects.
remediation: Invert the dependency by introducing an interface in Core and implementing it in Infrastructure.
query: |
  MATCH (source:Project)-[:DEPENDS_ON]->(target:Project)
  WHERE source.name CONTAINS "Core" AND target.name CONTAINS "Infrastructure"
  RETURN
    coalesce(source.path, "workspace") AS file,
    1 AS line,
    1 AS column,
    source.name AS symbol,
    target.name AS target,
    "Core project '" + source.name + "' cannot depend on '" + target.name + "'" AS message

Ratchet Baselines for Existing Codebases

To introduce strict rules into an existing repository without fixing every legacy violation upfront, gates support ratchet baselines (.codeexplorer/baselines/*.json):

1. Baseline Existing Debt: ce gate ratchet --update records SHA-256 fingerprints of current violations as tolerated baseline debt.
2. Block Regressions: ce gate check passes if only baselined violations exist, and fails immediately if any new violation is introduced.
3. Ratchet Down: When legacy violations are fixed, running ce gate ratchet --update tightens the baseline so debt cannot be reintroduced.

CI Usage

- name: Run Architectural Gates
  run: |
    ce scan
    ce gate check --format markdown >> $GITHUB_STEP_SUMMARY

VS Code Extension

The VS Code extension provides an interactive workspace for exploring the graph, inspecting dependencies, and managing architectural gates.

<p align="center"> <img src="docs/selected_services.png" alt="Focused Sub-Graph and Inspector" width="100%" /> </p> <p align="center"> <em>Focused service neighborhood with transitive broker links and the unified right-hand inspector panel.</em> </p>

Capabilities

• Multiple Views:
  • Domain Microservice Map: Interactive graph with Concentric Orbits, Swimlanes, Domain Islands, Hive Plot, Grid, and Dependency Matrix modes.
  • Architecture Tiers: Layered view across Presentation, Application, Domain, and Infrastructure tiers.
  • Project Flow: Upstream/downstream dependency columns for a selected project, showing endpoints, database tables, and message topics.
  • Bounded Context Map: Visualizes domain groupings, capabilities, and domain entities.
• Transitive Broker Contraction: When message broker nodes (Kafka, RabbitMQ, SQS) are hidden, the graph automatically synthesizes dashed producer-to-consumer edges (PUBLISHES_TO (via Topic)) so asynchronous flows remain visible.
• Unified Right-Hand Dock Panel:
  • Info: Displays inbound/outbound calls, database dependencies, topics, and source links for the selected node or edge.
  • Orbits: Reorders concentric tiers and toggles tier visibility.
  • Hidden: Lists filtered nodes with search and one-click restore.
  • Gates: Evaluates Semantic Invariant Gates, displays new vs. tolerated violations, ratchets baselines, and jumps directly to offending lines of code.
• Sidebar TreeView: Browse Architecture Diagrams, Ontology Layers (Layers 1–5), Domains & Bounded Contexts, Semantic Invariant Gates, and Server/Graph status from the VS Code activity bar.

<p align="center"> <img src="docs/project_flow.png" alt="Project Flow View" width="100%" /> </p> <p align="center"> <em>Project Flow view showing service cards, inbound/outbound dependencies, database links, and source navigation.</em> </p>

Supported Languages & Frameworks

CodeExplorer combines Tree-sitter grammars, Microsoft SQL ScriptDom, and framework-specific semantic analyzers (ISemanticExtension):

Graph Ontology

The graph schema is organized into five decoupled layers (see docs/ontology.md for the full node and relationship specification):

1. Layer 1 — Physical: Workspace, Folder, File, ConfigurationFile, Document, Script.
2. Layer 2 — Project: Project, Service, App, Worker, Library, Package, ExternalDependencies.
3. Layer 3 — Syntactic: Namespace, Type (class, interface, struct, record, enum), Function (method, constructor), Variable, Field, CallLiteral.
4. Layer 4 — Semantic: Endpoint (REST, gRPC, GraphQL, WebSocket), ExternalService, Database, Table, Query, Topic, Queue.
5. Layer 5 — Cross-Project & Analytical: Late-bound cross-project CALLS, IMPLEMENTS, USES_TYPE, PUBLISHES_TO, SUBSCRIBES_TO, READS_FROM, WRITES_TO, and optional LLM-distilled Domain / BoundedContext classifications.

CLI Reference

MCP Tools

Repository Layout

├── cli/
│   ├── src/
│   │   ├── Core/CodeExplorer.Core/        # Graph storage (SQLite), 5-layer indexer, SIG engine, MCP tools
│   │   ├── Cypher/CodeExplorer.Cypher/    # OpenCypher parser, AST, and SQLite SQL compiler
│   │   ├── Parsers/                       # Language parsers (C#, TS/JS, Java, Kotlin, Android, Go, Python, SQL, CF)
│   │   ├── Tools/CodeExplorer.OntologyGen/# Generates docs/ontology.md from C# node/edge attributes
│   │   └── UI/CodeExplorer/               # 'ce' CLI, WebSocket/HTTP server, and MCP host
│   ├── tests/
│   │   ├── CodeExplorer.Cypher.Tests/     # OpenCypher parser & SQL compiler test suite
│   │   └── CodeExplorer.Tests/            # Indexing, cross-service, gate, and MCP integration tests
│   └── CodeExplorer.slnx
├── vscode-extension/                      # VS Code extension (TreeView, Webview UI, bundled binary manager)
├── proto/                                 # Shared WebSocket & REST protocol contracts
└── docs/                                  # Auto-generated ontology reference and diagrams

License

MIT License