Why CodeCortex?

A coding agent can read code. The harder problem is deciding what matters, what is connected, what can break, and how much context is actually worth sending to the model.

CodeCortex turns a repository into a query-specific evidence system for coding agents:

• Repository + symbol intelligence — structure, definitions, references, dependencies, and call relationships.
• Evidence-aware retrieval — lexical, semantic, structural, graph, Git, architecture, and memory signals are ranked together.
• Impact before edits — reverse dependencies, affected tests, ownership, and change risk are inspectable before mutation.
• Guarded changes — semantic edits and structural rewrite previews keep source boundaries and review steps explicit.
• Persistent project context — architecture, history, project/team memory, traces, and multi-repo workspaces survive beyond one chat.

Core rule: retrieve evidence before generating confidence.

60-second start

Requires Python 3.11–3.13.

python -m pip install --upgrade codecortex-context-engine
cortex init .
cortex index
cortex doctor

Then ask the repository useful questions:

cortex architecture
cortex semantic "authentication and session lifecycle"
cortex impact AuthService

Or expose the repository to an MCP-capable coding agent:

cortex mcp --path .

Works with coding agents

CodeCortex includes merge-safe project configuration for Claude Code, Codex, Cursor, Gemini CLI, and OpenCode.

cortex agents detect
cortex agents configure --dry-run
# or configure every supported target explicitly:
cortex agents configure --all

The configurator only manages CodeCortex-owned MCP entries and keeps user-owned configuration intact.

See it work locally

The repository ships a deterministic demo project and demo runner:

python scripts/demo.py

The demo indexes the fixture repository, analyzes the blast radius of AuthService, routes an evidence request, and reports measured context/trace data. It does not fabricate benchmark values.

Reproducible evidence snapshot

These are committed hardening measurements, not generalized performance promises:

See HARDENING_REPORT.md and benchmarks/ for scope, methodology, limitations, and reproducibility notes.

❤️ Support CodeCortex — If CodeCortex saves you time, consider supporting its continued open-source development. Crypto support →

🇬🇧 English

CodeCortex in one sentence

CodeCortex turns a software repository into a query-specific evidence system for AI coding agents.

It sits between an agent and a codebase. It builds durable intelligence about repository structure, symbols, relationships, Git history, ownership, architecture, team decisions, impact, and validation. For each task, it tries to return the smallest useful evidence package instead of forcing the model to reopen broad parts of the repository and reconstruct the same facts again.

CodeCortex is not another general chat UI. It is not a model provider. It does not claim that an agent becomes infallible. It is context infrastructure: a layer that improves what the agent gets to reason with.

Core rule: retrieve evidence before generating confidence.

Why this exists

A strong coding model can read code. The harder engineering problem is deciding what deserves attention, what is connected to it, what changed, what is ambiguous, who owns the area, and what can break after a change.

Without a context engine, the work often looks like this:

search filenames
→ open broad files
→ rediscover architecture
→ guess symbol ownership
→ infer references
→ inspect Git manually
→ guess blast radius
→ consume a large context window
→ edit
→ discover a hidden dependency later

CodeCortex changes the stream:

task
→ classify intent
→ gather repository evidence
→ rank evidence for this task
→ preserve provenance and uncertainty
→ fit evidence into a context budget
→ expose one agent-facing surface
→ validate the proposed change

The goal is not more context.

The goal is higher-value evidence per token.

Architecture

Live evidence stream

flowchart LR
    A[AI Coding Agent] --> G[CodeCortex Gateway]
    G --> R[Adaptive Router]

    R --> REP[Repository Intelligence]
    R --> SYM[Symbol Intelligence]
    R --> RET[Hybrid Retrieval]
    R --> GIT[Git + PR Intelligence]
    R --> MEM[Project + Team Memory]
    R --> ARC[Architecture + Drift]
    R --> IMP[Impact + Validation]

    REP --> E[Evidence Surface]
    SYM --> E
    RET --> E
    GIT --> E
    MEM --> E
    ARC --> E
    IMP --> E

    E --> C[Context Pipeline]
    C --> B[Rank + Dedup + Slice + Budget]
    B --> G
    G --> A

The repository remains the source of executable truth. Graphs, memory, semantic retrieval, architecture inference, and summaries help interpretation. They do not replace current source, configuration, and tests.

Current capability map