CodeExplorer (ce) — Architecture Intelligence for AI Agents & Engineers

Core Architecture

Built for Polyglot Repositories

CodeExplorer indexes source files into a local SQLite property graph with zero external database dependencies.

Embedded SQLite Graph Engine

No Neo4j or Docker containers required. Translates OpenCypher 9 AST queries into parameterized SQLite joins and recursive CTEs with indexed B-Tree lookups.

engine: SqliteCompiler.cs

VS Code Architecture & Gates UI

Inspect services across 5 concentric tiers, view C1/C2 project flows, and evaluate or ratchet Semantic Invariant Gates directly from the VS Code sidebar and dock panel.

views: Cytoscape.js + Webview

Transitive Broker Contraction

Hide intermediate message topics (Kafka, RabbitMQ, SQS) and synthesize direct dashed [SUBSCRIBES (via Topic)] edges between producer and consumer services.

feature: Transitive Edge Synthesis

CLI & MCP Server for AI Agents

Provide Claude Code, Cursor, Codex, and terminal agents with deterministic call chains, impact analysis, and data lineage via direct CLI commands or local MCP over stdio.

interfaces: CLI + MCP (stdio JSON-RPC)

Polyglot Tree-sitter AST

In-memory AST extraction for C#, Java, Kotlin (Android/KMP), TypeScript, JavaScript, Go, Python, ColdFusion, and T-SQL. Resolves classes, functions, HTTP routes, ORM entities, and CQRS handlers.

ast: Tree-sitter + T-SQL ScriptDom

Optional Local GGUF Inference

Optionally enriches graph nodes with business domain tags and intent summaries using embedded llama.cpp (Vulkan GPU / CPU). Caches results by file SHA-256 hash.

inference: Local llama.cpp (Optional)

Embedded Query Engine

Query Architectural Topology with Cypher

Test real architectural inquiries against the graph database. Fast, declarative, and structured.

Cypher Input dialect: openCypher 9

// Find all downstream services impacted by OrderPlaced event
MATCH (p:Service {name: 'OrderService'})-[r:EMITS]->(e:DomainEvent)
MATCH (e)<-[:SUBSCRIBES]-(downstream:Service)
OPTIONAL MATCH (downstream)-[:WRITES_TO]->(tbl:Table)
RETURN
    p.name AS Producer,
    e.name AS EventName,
    downstream.name AS Consumer,
    tbl.name AS TargetTable
ORDER BY Consumer

Execution Output ● Completed in 14.2ms

Rows: 4

Scanned: 18 nodes

Optimizer: Indexed SQLite B-Tree

Producer	EventName	Consumer	TargetTable
OrderService	`OrderPlacedEvent`	BillingService	`invoices`
OrderService	`OrderPlacedEvent`	InventoryService	`stock_items`
OrderService	`OrderPlacedEvent`	NotificationHub	null
OrderService	`OrderPlacedEvent`	ShippingGateway	`shipments`

Architecture Governance & CI/CD

Semantic Invariant Gates

Define architectural rules as declarative OpenCypher queries in YAML. Enforce layer boundaries, block circular dependencies, and baseline existing technical debt in CI pipelines and VS Code.

Scope & Dimension Taxonomy

5 Scopes × 4 Dimensions

Gates are organized across 5 hierarchical Scopes (System, Service, Module, Class, Method) and 4 architectural Dimensions (Boundaries, Contract, Rules, Resources), covering multi-service topologies down to AST call arguments.

Identifier: SIG-<Scope>-<Dimension>-<Index3Digits>

Evaluation Contract

Zero-Match Query Evaluation

Each gate runs an OpenCypher query against the indexed graph: 0 rows returned = PASS; 1 or more rows = VIOLATION. Every match projects source coordinates (file:line:column), offending symbol, target, and remediation guidance.

RETURN file, line, column, symbol, target, message

Baseline Fingerprinting

Line-Shift Resilient Ratchets

Violations are fingerprinted by semantic identity and per-file occurrence index rather than volatile line numbers. Formatting code or adding imports above a baselined violation never triggers false positives in pull requests.

SHA256(GateId + FilePath + Symbol + Target + Occurrence)

Scope & Level	Granularity & Graph Entities	Dimension Focus	Example Invariant & Purpose
System (A)	`:Service`, `:Topic`, `:Database`, cross-service RPC	Boundaries & Topology	Prevent circular distributed event publish/subscribe chains; enforce API gateway single-entry ingress.
Service (S)	`:Service`, `:Worker`, `:App`, `:CliTool` executables	Resources & Boundaries	Forbid frontend apps or background workers from executing queries directly against foreign service databases.
Module (P)	`:Project`, `:Library`, compilation units, NuGet / npm packages	Layer Boundaries	Enforce unidirectional layer hierarchy: Domain and Application core libraries must not reference Infrastructure or UI packages.
Class (C)	`:Type`, classes, interfaces, structs, visitor hierarchies	Rules & Implementation	Keep AST visitors and compiler passes pure: disallow direct invocation of filesystem (`File`, `Directory`) or network I/O.
Method (M)	`:Function`, `:Endpoint`, constructors, `:CallLiteral`	Contract & Rules	Detect hardcoded string literals passed to domain methods; verify public API endpoints return typed DTOs instead of ORM entities.

Dimension: Boundaries

Layer Isolation

Enforce Clean Architecture and bounded context isolation. Prohibit Domain and Core layers from referencing Web, UI, or persistence drivers.

:Library -[:DEPENDS_ON]-> :Package

Dimension: Topology

Acyclic Project Graph

Detect direct and transitive circular references across modules (A ➔ B ➔ A) to preserve an acyclic project dependency graph.

(a:Project)-[:DEPENDS_ON*2..6]->(a)

Dimension: Contracts

API & Schema Integrity

Detect unversioned route changes and direct exposure of internal ORM entity types on public REST or gRPC endpoints.

:Endpoint -[:RETURNS]-> :Entity

Dimension: Resources

Data Access Guardrails

Catch controller handlers issuing raw SQL queries directly against database tables instead of delegating to repositories or handlers.

:Endpoint -[:CALLS*]-> :Query

Gate Contract Definition .codeexplorer/gates/*.yaml

CLI & VS Code Gate Evaluation ● Evaluated in 11.2ms (Exit Code 1)

Status:

New: 1

Tolerated: 0

Engine: Ratchet SHA-256

Incremental Adoption

Baseline Ratcheting in CLI & VS Code

Adopt architectural rules in existing codebases without fixing hundreds of legacy violations upfront. Record current violations into SHA-256 baseline snapshots so CI passes existing debt while blocking any newly introduced violation.

1

Declare Gate Rule

Write an OpenCypher query in .codeexplorer/gates/*.yaml matching forbidden patterns with remediation guidance.

2

Record Baseline Snapshot

Run ce gate ratchet --update or click Ratchet Baseline in the VS Code Gates panel to freeze existing violations.

3

Enforce in CI & Agent Loops

ce gate check tolerates baselined items ([TOLERATED]) and exits non-zero on new violations ([FAIL]).

4

Tighten Baseline Over Time

As legacy violations are removed, updating the ratchet removes stale hashes so resolved debt cannot return.

.github/workflows/architecture-gates.yml

# Pull Request Architectural Guardrail
name: Architectural Invariant Gates
on: [pull_request]

jobs:
  verify-architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install CodeExplorer CLI
        run: curl -fsSL https://raw.githubusercontent.com/vmikhailov/code-explorer/main/cli/scripts/install.sh | bash
      - name: Scan AST & Compile SQLite Graph
        run: ce scan
      - name: Evaluate Semantic Invariant Gates
        run: ce gate check
      # Exits with code 1 if PR introduces any unbaselined violations

Rule Organization

Architectural vs. Platform Gates

Separate language-agnostic structural rules from ecosystem-specific package constraints.

.codeexplorer/gates/architectural/*.yaml Category: Architectural (platform: agnostic) — Structural patterns: layer separation, acyclic project graphs, CQRS handler rules, and AST visitor purity.

.codeexplorer/gates/platform/<platform>/*.yaml Category: Platform (platform: dotnet | node | go | python) — Ecosystem-specific rules: restricting Microsoft.Data.Sqlite or better-sqlite3 in domain packages.

ce gate check --category architectural --platform dotnet Filter gate evaluation by category, platform, scope, or severity in polyglot builds.

CLI & Editor Workflow

CI Pipelines, AI Agents & VS Code UI

Verify structural constraints from the terminal, automated agent loops, or the interactive Gates panel in VS Code.

ce gate check --format json Outputs structured JSON diagnostics with file:line:col and remediation instructions for coding agents.

ce gate ratchet --update -g <gate-id> Updates baseline snapshots for specific gates via CLI or the VS Code Gates view.

ce gate violations --group-by file Lists active violations grouped by source file, gate, or category.

How to Use

CLI & MCP Integration for AI and Engineers

Two complementary interfaces to access deterministic codebase ground truth: direct CLI execution for engineers, autonomous agents, and CI pipelines, plus a standard MCP server for desktop IDEs.

Terminal-First Agents

Native CLI for Coding Agents

Autonomous coding agents (Claude Code, OpenAI Codex, OpenCode, Aider, Hermes) execute ce directly in bash without JSON-RPC overhead or background daemons. Structured JSON and Markdown outputs provide maximum architectural signal in minimum tokens.

ce init [name] — Initialize .codeexplorer/ workspace and SQLite knowledge graph.
ce scan — Parse Tree-sitter ASTs, extract dependencies, and resolve semantic layers.
ce query -n get_architecture_map_workspace -j — Macro topology, databases, and ingress in <1,000 tokens.
ce query -n get_project_entry_points -p <name> — Discover HTTP endpoints, gRPC routes, and event listeners.
ce query -n get_file_outline -f <path> — Low-token AST outline (classes, methods, signatures) without reading full file.
ce query "MATCH (s:Service)-[:CALLS*1..3]->(t) RETURN ..." — Ad-hoc multi-hop OpenCypher call graphs.
ce gate check --format markdown — Pre-commit validation of Semantic Invariant Gates and ratchets in CI.
ce export --format mermaid -o arch.mmd — Export C1/C2 diagrams and event pipelines from graph topology.

CLI Command Reference

Terminal AI Agent Session (Claude Code / Codex / Hermes)

# 1. Initialize & index repository
$ ce init && ce scan
Indexed 48 projects, 1,240 files, 18 databases in 1.4s.

# 2. Inspect architecture in <1,000 tokens
$ ce query -n get_architecture_map_workspace -j
{
  "projects": ["OrderService", "BillingCore", "AuthGateway"],
  "databases": ["orders_db", "billing_replica"],
  "entry_points": ["POST /api/v1/orders", "Topic: order-events"]
}

# 3. Trace multi-hop blast radius before editing
$ ce query "MATCH (t:Type {name: 'IOrderRepo'})<-[:CALLS]-(c) RETURN c.name"
[ "OrderController", "BillingListener", "InvoiceWorker" ]

# 4. Enforce architectural invariants before commit
$ ce gate check
✓ PASS: SIG-P-B-001 Clean Architecture Layer Isolation (0 violations)
✓ PASS: SIG-M-I-001 No Hardcoded Endpoint Literals (0 violations)
All 6 Semantic Invariant Gates passed in 11.2ms. Exit code: 0

IDE & Protocol Adapter

Model Context Protocol (MCP) Server

For desktop IDEs and AI assistants (Claude Code, Cursor, Claude Desktop, Roo Code, Cline), ce mcp exposes 23 architectural tools over zero-network local stdio JSON-RPC pipes.

get_architecture_map — Surface project boundaries, external dependencies, and ingress endpoints.
analyze_code_impact — Calculate downstream blast radius before refactoring types or interfaces.
inspect_data_lineage — Map ORM entities, SQL queries, and callers touching a database table.
execute_cypher_query — Run parameterized OpenCypher queries and saved domain queries.

Read MCP Specification

~/.cursor/mcp.json / claude_desktop_config.json

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

Semantic Structure

5-Layer Graph Ontology

34 node labels and 37 relationship types organized across five layers, linking physical source files to cross-service topology.

LAYER 5

Late-Bound Layer

Cross-project HTTP routes, message broker topics/queues, CQRS pipelines (MediatR/Spring), and interface implementations resolved via post-index graph passes.

:Service, :Topic, :Queue

LAYER 4

Semantic Layer

Inbound REST/gRPC/GraphQL endpoints, ORM entities mapped to database tables, raw SQL queries, and outbound HTTP clients.

:Endpoint, :Table, :Query

LAYER 3

Syntactic Layer

Tree-sitter AST declarations: classes, records, interfaces, methods, functions, fields, call literals, and intra-file call edges.

:Type, :Function, :CallLiteral

LAYER 2

Project Layer

Compilation units, project references, and third-party NuGet, Maven/Gradle, npm, Go, and Python package dependencies.

:Project, :Library, :Package

LAYER 1

Physical Layer

Workspace root, directory hierarchy, source files with SHA-256 content hashes, and configuration files (.env, appsettings.json, AndroidManifest.xml).

:Workspace, :Folder, :File

Supported Languages & AST Parsers

⚡

C# (.NET)

.NET 10 / ASP.NET

☕

Java

Spring / Maven / Gradle

KT

Kotlin

Android / Retrofit / Room

🔷

TypeScript

TS / TSX / NestJS

🟨

JavaScript

ES6 / Node / Express

🐹

Go

Go Modules / Gin / Chi

🐍

Python

FastAPI / Flask / SQLAlchemy

🗄️

SQL & CFML

T-SQL / ColdFusion

Quick Start

Install in Seconds

Single self-contained binaries for macOS, Linux, and Windows. No SDK required.

brew install vmikhailov/tap/ce

Installs the ce binary directly into your PATH with automatic shell completions.

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

Bundles pre-compiled native binaries for all platforms; no external CLI setup needed.

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

Downloads standalone self-contained ce.exe and registers in Windows User PATH.

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

Automated architecture detection (x64 / ARM64) and direct installation to ~/.local/bin.

dotnet tool install -g CodeExplorer.Cli

For developers with .NET 10 SDK already installed.

ce init

Initialize a .codeexplorer workspace configuration in current repository.

ce scan

Run AST visitors across all source files and compile the SQLite graph.

ce query "MATCH..."

Execute an arbitrary Cypher query and output structured JSON or table.

ce export -f mermaid

Export macro architecture or C4 container diagrams into Mermaid syntax.

ce mcp configure

Configure and start the local stdio Model Context Protocol server for AI coding agents.

ce status

Display indexed node and edge statistics by label and relationship type.

ce gate check

Evaluate semantic invariant gates against SQLite graph; exits non-zero on new debt.

ce gate ratchet --update

Record current violations into baseline snapshots so CI blocks only new violations.

ce gate violations -g <id>

Inspect, group by file, and export structured violation reports and remediation hints.

Architecture Intelligencefor AI Agents & Engineers