CodeScope

CodeScope — Project Truth Engine

CodeScope does not understand code. It verifies code.

It transforms source code into verifiable facts, understandable models, and inspectable evidence — enabling AI to validate claims against reality instead of hallucinating.

Version: v0.2.3 | License: Apache 2.0

---

1. What Is CodeScope?

CodeScope is a Project Truth Engine that answers one question:

> "Does the code actually do what you claim?"

Not "what does this code mean", but "does the code actually do what you claim?"

It indexes source code into a structured code graph (call graph + reference graph + module knowledge), then exposes 42 MCP tools that let AI agents locate symbols, trace call paths, verify claims, detect documentation drift, and analyze architecture — all with ~98.9% token savings vs reading raw source files.

Supported Languages (8)

| Language | Parser | IR Translator | Verified | |----------|--------|---------------|----------| | Python | ✅ | ✅ | ✅ | | Go | ✅ | ✅ | ✅ | | C | ✅ | ✅ | ✅ | | C++ | ✅ | ✅ | ✅ | | Rust | ✅ | ✅ | ✅ | | JavaScript | ✅ | ✅ | ✅ | | TypeScript | ✅ | ✅ | ✅ | | Java | ✅ | ✅ | ✅ |

Tech Stack

| Layer | Technology | |-------|-----------| | Parser | tree-sitter (unified AST IR, 8 languages) | | Indexer | C++23 (Clang 17+), SQLite (WAL mode, FTS5) | | Server | Rust 2024 Edition, MCP Protocol (JSON-RPC 2.0, stdio transport) | | Graph Storage | SQLite (primary) + optional LadybugDB (Cypher queries) | | Scheduler | Built-in multi-process parallel indexer (chunk-level work-stealing) | | Build | CMake 3.30+ (C++), Cargo (Rust) |

---

2. Architecture

graph TB
    subgraph "AI Client"
        Client["Claude Desktop / Cursor / Any MCP Client"]
    end

    subgraph "Rust MCP Server"
        MCP["MCP Protocol (JSON-RPC 2.0)42 tools / stdio transport"]
        DISPATCH["Tool Dispatchproject_id auto-restore"]
    end

    subgraph "C++ Core Engine"
        PARSER["Parsertree-sitter → unified IR8 languages"]
        FACTS["Facts Repositoryentity / reference / scope / import"]
        RESOLVER["Resolver PipelineConstraint Chain"]
        MODEL["Model EngineWorkflow / CapabilityArchitecture / Contract"]
        INSPECTOR["InspectorDeadCodeInspector / verify_integrity"]
    end

    subgraph "SQLite (WAL mode)"
        F_STORE["Facts Storeentity / reference / scope / import"]
        S_STORE["Semantic Storeresolved_reference / relation"]
        M_STORE["Model Storeworkflow / capabilityarchitecture / contract"]
        E_STORE["Evidence Storeclaim / evidence / finding"]
    end

    Client -->|"MCP stdio"| MCP
    MCP --> DISPATCH
    DISPATCH -->|"FFI"| PARSER
    DISPATCH -->|"FFI"| FACTS
    DISPATCH -->|"FFI"| RESOLVER
    DISPATCH -->|"FFI"| MODEL
    DISPATCH -->|"FFI"| INSPECTOR

    PARSER -->|"writes"| F_STORE
    F_STORE -->|"reads"| RESOLVER
    RESOLVER -->|"writes"| S_STORE
    S_STORE -->|"reads"| MODEL
    MODEL -->|"writes"| M_STORE
    M_STORE -->|"reads"| INSPECTOR
    INSPECTOR -->|"writes"| E_STORE

Pipeline

Source Code
    |
    v
Parser ------------ entity / reference / scope / import
    |
    v
Resolver ---------- resolved_reference / relation
    |
    v
Model Engine ------ workflow / capability / architecture / contract
    |
    v
Inspector --------- evidence / finding

Query Flow

flowchart LR
    Q["MCP Clienttool call"] --> Q1["Server receivesproject_id auto-restore"]
    Q1 --> Q2{"Tool type?"}
    Q2 -->|"index_project"| Q3["Spawn worker subprocess→ memory isolated→ exits after done"]
    Q2 -->|"query tools"| Q4["C++ FFI → SQLite querygraph_nodes, graph_edgessearch_index, ..."]
    Q2 -->|"get_communities"| Q5["Load full graphLabel Propagation→ JSON with max_communities limit"]
    Q2 -->|"get_hotspots"| Q6["SQL: COUNT(ge.id) JOINgraph_edges edge_type=1ORDER BY caller_count"]
    Q4 --> R["Result JSONback to MCP Client"]
    Q5 --> R
    Q6 --> R

Two-Phase Indexing

flowchart LR
    subgraph A["Phase A: Fast Scan (ms)"]
        S1["scan_project"]
        S2["total_symbols"]
        S3["module_tree"]
        S4["entry_points"]
    end

    subgraph B["Phase B: Background Enhance (async, seconds)"]
        E1["enhance_project"]
        E2["full tree-sitter"]
        E3["call graph"]
        E4["complexity metrics"]
        E5["embeddings + FTS"]
    end

    A -->|"trigger"| B

---

3. 8-Layer Smart Filtering: Why Only 6,029 of 36,919 Files Are Indexed

CodeScope does not index every file in a project. Instead, it applies an 8-layer cascade that strips away noise so you only see what matters: the core source code.

The Problem

A typical project looks like this (rustc, the Rust compiler):

Total source files:  36,919
  tests/            26,293  ← 71%: test suites
  src/tools/*/test/  3,802  ← 10%: embedded test directories
  library/*/test/      339  ←  1%: library tests
  compiler/*/test/     118  ←  **macOS code signing issue**: If the binary is killed immediately on launch (exit code 137 / SIGKILL), re-sign it locally:
> ```bash
> codesign --sign - --force ~/.codescope/bin/codescope
> ```
> This happens because the CI-built binary uses ad-hoc signing, which newer macOS versions may reject. Re-signing with your local machine's identity resolves it.

### Build from Source

```bash
git clone https://github.com/Timwood0x10/CodeScope.git
cd CodeScope

# macOS:
brew install llvm@21 cmake pkg-config
cargo build --release

# Linux (Ubuntu):
sudo apt-get install -y build-essential cmake llvm-dev libclang-dev
cargo build --release

Index and Query

# Index a project
codescope cli index_project '{"project_path":"/path/to/your/project"}'

# Quick overview
codescope cli project_overview '{}'

# Start MCP server (for AI clients)
codescope

Large Projects

For projects with thousands of files, use the built-in parallel scheduler:

codescope index-parallel /path/to/large/project

---

4. MCP Tools (42 Tools)

Indexing

| Tool | Description | Parameters | |------|-------------|------------| | index_project | Index a project directory: parse all source files, build IR, and construct the code graph. | {"project_path": "string (required)", "language_filter": "string (optional)"} | | index_file | Index a single source file. | {"file_path": "string (required)"} | | force_index_files | Force-index files/dirs bypassing default skip rules (test/, docs/, node_modules/, .gitignore, etc.). | {"paths": ["string (required)"], "language_filter": "string (optional)"} |

Project Overview

| Tool | Description | Parameters | |------|-------------|------------| | project_overview | Primary — comprehensive project overview: languages, modules, symbols, entry points, analysis progress. | {} | | get_graph_stats | Quick statistics: nodes, edges, files. | {} | | get_module_tree | Hierarchical module/directory tree. | {} | | get_entry_points | Find entry points (main/init/setup/run/handler). | {} | | get_routes | Get registered HTTP routes (Gin/Echo/Chi/net/http). | {} | | get_type_info | Query type definitions (struct/enum/trait) with reference counts. | {"type_name": "string (optional)"} |

Symbol Lookup

| Tool | Description | Parameters | |------|-------------|------------| | find_symbol | Recommended — find symbol by exact name (kind, file, line/col). | {"symbol_name": "string (required)"} | | find_references | Find all locations referencing a symbol. | {"symbol_name": "string (required)", "file_filter": "string (optional)"} | | explain_symbol | Get comprehensive symbol info: definition, callers, callees, dependencies. | {"symbol_name": "string (required)"} | | find_definition | [DEPRECATED — use find_symbol] | {"symbol_name": "string (required)"} |

Call Graph

| Tool | Description | Parameters | |------|-------------|------------| | find_callers | Find who calls a function. | {"symbol_name": "string (required)", "file_filter": "string (optional)"} | | find_callees | Find what a function calls. | {"symbol_name": "string (required)", "file_filter": "string (optional)"} | | codescope_trace | Interactive recursive call exploration (depth + direction) or shortest path. | {"function_name": "string", "depth": "integer (default 1, max 5)", "direction": "callers|callees|both", "from": "string", "to": "string"} | | trace_flow | Recursive execution flow tracing (caller→callee chain). | {"function_name": "string (required)", "depth": "integer (default 3, max 10)"} | | shortest_path | Shortest call path between two functions (BFS). | {"from": "string", "to": "string", "from_id": "integer", "to_id": "integer"} | | connected_components | Connected components in the call graph. | {} |

Graph Query

| Tool | Description | Parameters | |------|-------------|------------| | graph_query | Cypher-like DSL query: MATCH (Function:main)-[Calls]->(Method). | {"dsl": "string (required)"} | | get_graph | Retrieve the complete code graph in paginated pages. | {"node_offset": "integer", "node_limit": "integer (max 50000)", "edge_offset": "integer", "edge_limit": "integer (max 200000)", "node_types": "string", "edge_types": "string"} | | get_subgraph | Fetch a local region centered on a node (1-hop). | {"node_id": "integer (required)", "radius": "integer", "node_types": "string", "edge_types": "string"} | | get_neighbors | Fetch direct neighbors (callers + callees) of a graph node. | {"node_id": "integer (required)", "edge_type": "integer (default -1)", "radius": "integer"} |

Search

| Tool | Description | Parameters | |------|-------------|------------| | search | Recommended — unified search (auto-selects FTS5 or semantic). | {"query": "string (required)", "limit": "integer (default 20, max 100)"} | | search_code | [DEPRECATED — use search] | {"query": "string (required)", "limit": "integer"} |

Verification

| Tool | Description | Parameters | |------|-------------|------------| | verify_integrity | Check README-promised features actually exist in code. | {} | | verify_claim | Verify a single claim (capabilityexists / contractholds / architecture_follows). | {"claim": "string (required)"} | | verify_summary | Parse natural-language summary and verify each claim. | {"text": "string (required)"} | | verify_review | Verify code review comment claims. | {"text": "string (required)"} | | verify_reality | Verify a single AI statement against code evidence. | {"text": "string (required)"} |

Evidence Pipeline (v0.3)

The v0.3 Evidence Pipeline transforms indexed code into verifiable evidence and project health snapshots. Flow: Facts → SemanticFacts → Evidence → Verification → ProjectState. Semantic facts are extracted by enhance_project (Step 1.5); evidence is built by applying declarative rule files (engine/src/evidence/rules/*.json) to the semantic_fact table.

| Tool | Description | Parameters | |------|-------------|------------| | enhance_project | Run background enhancement: full tree-sitter parse, call graph, metrics, FTS, and v0.3 semanticfact extraction. Prerequisite for build_evidence to produce non-empty findings. | {} | | build_evidence | Build evidence findings by applying the rule set (sync/memory/error/pattern/framework/ffi) to the project's semanticfact rows. Each rule declares fact needs + a combine mode (Collect / MissingMatch / MissingMatchPerFunction / Count). Returns a JSON array of Evidence objects. Run after enhance_project so semantic facts are populated. | {"category": "string (optional, one of: sync|memory|error|pattern|framework|ffi)"} | | verify_statement | Verify a natural-language claim against the project's indexed evidence. Pipeline: IntentParser → Planner → EvidenceBuilder → VerdictBuilder. Returns JSON with verdict (Supported\|Contradicted\|PartiallyVerified\|Unknown), confidence, requirements[], and evidence[]. Use this for yes/no questions about code behavior (e.g. "does this project safely handle CString?"). | {"claim": "string (required)"} | | build_project_state | Build (or rebuild) and persist the project state snapshot. Runs the full v0.3 Evidence Pipeline (evidence aggregation + state queries) and UPSERTs the result into the project_state table. Returns the snapshot JSON: overall confidence, capability/architecture/workflow/dead_code scores, per-category issue counts, and last_updated timestamp. | {} | | get_project_state | Get the previously persisted project state snapshot (without rebuilding). Returns the snapshot_json string for the project, or a JSON error object if no snapshot exists yet (run build_project_state first). Use this for fast reads of the latest health snapshot. | {} |

Drift Detection

| Tool | Description | Parameters | |------|-------------|------------| | detect_drift | Scan all declared capabilities & contracts for doc-vs-code drift. | {} | | detect_documentation_drift | Check README language claims vs actual code entities. | {} | | detect_capability_drift | Check declared capabilities have implementing entities. | {} | | detect_architecture_drift | Check call edges for layer violations (Repository→Controller). | {} |

Change Impact & Module

| Tool | Description | Parameters | |------|-------------|------------| | detect_changes | Analyze impact of modified files: direct/indirect callers. | {"modified_files": "string (required)"} | | explain_module | Build module knowledge card: entities, capabilities, integrity score. | {"module_name": "string (required)"} |

Utilities

| Tool | Description | Parameters | |------|-------------|------------| | detect_ffi_boundaries | Detect FFI boundaries (extern/C, JNI, WASM, C ABI). | {} | | count_tokens | Estimate token count (DeepSeek formula). | {"text": "string (required)"} |

Quick Decision Guide

New project       → project_overview
Module structure  → get_module_tree
Entry points      → get_entry_points
Search code       → search
Call chain        → find_callers / find_callees
Deep dive symbol  → explain_symbol
HTTP routes       → get_routes
Type info         → get_type_info
Verify claim      → verify_claim
Enhance project   → enhance_project
Verify statement  → verify_statement
Build evidence    → build_evidence
Project health    → build_project_state
Detect drift      → detect_documentation_drift
Change impact     → detect_changes

---

5. Knowledge Graph

CodeScope builds a module-level knowledge graph as a side product of the verification pipeline. It learns structured metadata about how the project is organized, what's important, what's redundant, and what it promises:

| Layer | Table | What it tells you | |-------|-------|-------------------| | Call graph | relation, architecture_edge | Cross-module call dependencies; drives detect_architecture_drift | | Module health | module_summary | Per-module incoming_count / outgoing_count / dead_entities / utilization / role | | Module dependency | architecture_edge, module_edge | "Change module A → these modules depend on it" | | Documented capability | capability + document | README-extracted capabilities; drives detect_capability_drift / verify_claim |

All knowledge-layer tables are directly queryable via get_knowledge_graph:

get_knowledge_graph {"table":"architecture_edge","limit":5}
// → {"table":"architecture_edge","rows":[...],"total":3351}

get_knowledge_graph {"table":"capability","limit":10}
// → {"table":"capability","rows":[...],"total":3}

Supported tables: entity, relation, architecture_edge, module_edge, capability, document, module_summary.

---

6. Benchmark

All benchmarks measured on Apple M3 Max (36 GB RAM). Other hardware will produce different results — expect slower performance on less capable machines.

##

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Timwood0x10
• Source: Timwood0x10/CodeScope
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.