Context Zero Engine

A local code-intelligence engine for AI agents. ContextZero indexes a repository into a PostgreSQL-backed code graph and serves structured, token-budgeted context — symbols, dependencies, effects, contracts, similar code, and blast radius — over MCP and HTTP. The engine and its database run locally and do not require an external analysis or embedding API. If an operator enables repository validation commands, those commands inherit the repository's own behavior and may access the network.

Built by ClassEve. Licensed under Apache-2.0.

Official repository. This is the only official repository for Context Zero Engine. ClassEve's complete list of official accounts is at classeve.com/official. The GitHub account github.com/ClassEve is an unrelated third party, not affiliated with ClassEve.

The Problem

Coding agents and developer tools usually inspect source one file at a time. On a non-trivial codebase that means opening dozens of files, re-reading the same code across tasks, manually tracing transitive effects — and still missing contract assumptions or behaviorally similar code elsewhere in the repository.

ContextZero indexes the repository once and answers the same investigation with targeted queries: give me this symbol with its dependencies and contracts, what breaks if I change it, where else does this logic exist, which tests cover it.

An AI assistant asked to change one function has to see three things: the function, the code it uses from other files, and the code that calls it. Measured across 955 jobs on 18 public repositories, the typical job costs:

83% fewer tokens — 10.1× fewer across the whole run. And it costs less without knowing less: given the same tokens to spend, searching contains the function you asked about only 1 time in 9, while ContextZero has it every time; it finds the code that calls it 50% of the time against 25%, 6 in 10 of the helpers the code uses from other files against almost none, and a covering test for 1 job in 4.

Searching for a name finds the places that mention it, not the things it needs. BENCHMARKS.md has the method, a worked example, a second codebase, and what the engine still does badly. Reproduce on your own repository with node scripts/bench-context-quality.mjs.

What It Computes

Languages

TypeScript, JavaScript, Python, C, C++, CUDA-flavored .cu/.cuh, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, Bash — 32 file extensions across 13 parsers, since C, C++ and CUDA share the C++ parser.

TypeScript and JavaScript use full AST analysis through the TypeScript Compiler API. Python uses LibCST with 60+ behavioral patterns. The remaining languages use tree-sitter with language-specific walkers. CUDA files are indexed for structure; kernel-specific semantics are not modelled separately.

How It Works

MCP-compatible client (Claude Desktop, Claude Code, Codex, Cursor, ...)
    |
    | MCP protocol (stdio)            HTTP clients
    |                                     |
ContextZero MCP Bridge (61 tools)    REST API (62 routes)
    |                                     |
    +------------------+------------------+
    |
    +-- Ingestor (13 language parsers, delta ingestion)
    +-- 13 Analysis Engines
    |     Behavioral | Contract | Deep Contract | Blast Radius
    |     Effect | Dispatch | Concept Families | Temporal
    |     Symbol Lineage | Runtime Evidence | Uncertainty
    |     Structural Graph | Capsule Compiler
    +-- Semantic Engine (TF-IDF, MinHash LSH, cosine similarity)
    +-- Homolog Engine (7-dimensional scoring)
    +-- Transactional Editor (opt-in constrained validation, rollback)
    +-- Service Layer (transport-agnostic services)
    +-- Database Driver (circuit breaker, batch loader, advisory locks)
    |
PostgreSQL (all data local, nothing leaves your machine)

The scg_ prefix on tools and environment variables comes from the engine's internal name for its data model — the structural code graph.

Deep dives: ARCHITECTURE.md (subsystems and tool registry) and TECHNICAL_DESIGN.md (data structures, algorithms, engine internals).

Install

Prerequisites

• Node.js 20+ (22 recommended)

• PostgreSQL 14 or newer (17 recommended) with the pg_trgm extension

• Python 3 with libcst (optional — only for Python source analysis)

Bootstrap (recommended)

git clone https://github.com/Classevelabs/context-zero-engine.git context-zero-engine
cd context-zero-engine

Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Client claude

macOS / Linux:

scripts/bootstrap.sh --client claude

The bootstrap installs dependencies, creates .env, builds, runs database migrations, runs diagnostics (npm run doctor), and optionally writes the MCP config for your client (claude, codex, cursor, or all).

Manual install

npm ci

createdb scg_v2
psql -d scg_v2 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

cp .env.example .env    # set DB_USER / DB_PASSWORD / SCG_ALLOWED_BASE_PATHS

npm run build
npm run db:migrate
npm run doctor          # verifies node, database, python, env

Full options, client config paths, and troubleshooting: docs/INSTALL.md and docs/OPERATIONS.md.

Quickstart

1. Wire it into an MCP client

The bundled installer writes the config (with a timestamped backup of the existing file) for Claude Desktop, Codex, or Cursor:

npm run mcp:install -- --client claude

Or generate config snippets without touching client files (npm run mcp:config), or register manually — for example with the Claude Code CLI:

claude mcp add contextzero -s user \
  -e CONTEXTZERO_ENV_FILE=/absolute/path/to/context-zero-engine/.env \
  -- node /absolute/path/to/context-zero-engine/dist/mcp-bridge/index.js

Any MCP client that speaks stdio works: the server is node dist/mcp-bridge/index.js with the DB_*/SCG_* environment (or a single CONTEXTZERO_ENV_FILE pointing at your .env).

MCP uses a trusted local stdio child-process boundary; it is not a remote network authentication layer. The 43 read tools are listed by default. The 18 tools that ingest, edit, run retention cleanup, or validate are listed only after a local operator sets SCG_MCP_MUTATIONS_ENABLED=true; until then the session is told once, at connect, that they exist and where the switch is. Validation commands additionally require SCG_ALLOW_UNSANDBOXED_EXECUTION=true and should run only on trusted repositories under a restricted operating-system account.

2. Index a repository

From the MCP client, call:

scg_health_check                      → should report status: healthy
scg_register_repo / scg_ingest_repo   → index a repo under SCG_ALLOWED_BASE_PATHS

Then start asking: scg_smart_context, scg_blast_radius, scg_compile_context_capsule, scg_find_homologs, scg_semantic_search, ...

Three native tools (scg_native_codebase_overview, scg_native_symbol_search, scg_native_search_code) work immediately without a database — they analyze the filesystem directly.

3. Keep it current

npm run watch

Watches every registered repository and folds each change into its snapshot as it happens, so the graph describes the code as it is rather than as it was at the last ingest. Set SCG_WATCH=true to start it with the MCP server instead.

It watches the filesystem and nothing else — the same behaviour whether the code is edited by an IDE, a coding agent, a script, or a branch switch.

4. Or run it as an HTTP server

npm run build
npm start          # HTTP server on port 3100

curl http://localhost:3100/health
curl -X POST http://localhost:3100/scg_codebase_overview \
  -H "X-API-Key: <your key>" -H "Content-Type: application/json" \
  -d '{"repo_id": "..."}'

62 routes (9 GET + 53 POST) mirror the MCP tool surface plus health, readiness, Prometheus metrics, cache, and admin endpoints. All non-health routes require API-key authentication (X-API-Key or Authorization: Bearer). State-changing, repository-registration, and validation-command routes require a distinct SCG_ADMIN_API_KEYS credential.

Docker (self-hosted server + bundled PostgreSQL)

cp .env.docker.example .env
# Set DB_PASSWORD, SCG_API_KEYS, and a distinct SCG_ADMIN_API_KEYS value.
docker compose up -d

When registering repositories from Docker, use paths under /repos — that is where SCG_REPOS_PATH is mounted inside the container.

MCP Tool Surface (61 tools)

A session lists the 43 read tools by default; the 18 that mutate appear once SCG_MCP_MUTATIONS_ENABLED=true is set. The complete registry is in ARCHITECTURE.md.

Security

• Local by design — no telemetry or required external analysis APIs; opt-in repository commands retain their own network capabilities

• SQL injection protection — parameterized queries plus table/column allowlists for dynamic queries

• 5-layer path traversal protection — null bytes, URL encoding, backslash handling, symlink escape checks, base-path boundary enforcement

• Fail-closed authentication — timing-safe comparison, 32-character minimum keys, per-IP brute-force lockout, and separate production admin credentials for privileged HTTP routes

• Constrained validation runner — disabled by default; applies time/output/resource limits, process groups, SIGKILL escalation, and environment sanitization, but does not isolate filesystem or network access

• Hardened HTTP surface — per-route rate limits and body-size limits, input validation on every route, sanitized error responses (no stack traces, paths, or SQL)

See SECURITY.md for the deployment hardening checklist and how to report a vulnerability.

Historical Benchmarks

These are author-reported historical results; raw machine-readable run outputs are not committed. Methodology, reproduction scripts, and cases where the gain is small: BENCHMARKS.md.

Testing

npm test              # full unit suite
npm run test:db       # opt-in integration test against a real PostgreSQL
npm run test:ci       # with coverage
npm run typecheck     # TypeScript strict mode
npm run lint

Documentation

About

Built and maintained by ClassEve — engineering for AI agents and developer tooling. Project page: classeve.com/public/context-zero-engine.

License

Apache License 2.0 — see LICENSE. Copyright 2026 ClassEve.