v1.0.3Hardware-aware Ollama · stdio MCP server · any LLM endpoint→

The Governed Code Intelligence Layer for AI Agents & Engineers

CodeTrace AI turns your repository into a deterministic call graph and makes the agent prove every claim — verified blast radius and exact file:line citations before any edit. Parsing, embeddings and the graph run on your machine; bring any LLM, or pair it with Ollama and nothing leaves it at all.

Explore Governed Protocol →View GitHub ▶ Watch Demo (Video)

Evidence Graded Protocol

Runtime Blast Radius

21 Languages

Local-First · Air-Gap Ready

Claude Code · Cursor · VS Code MCP

Real CodeTrace session: indexing pallets/itsdangerous, then answering 'What breaks if I change Signer.get_signature?' with a local qwen3.5:4b model on a 6 GB laptop GPU

Real session · shown at 2× speed · qwen3.5:4b via Ollama on a 6 GB laptop GPU · nothing left the machine

What's new in v1.0.3

Built to run on your laptop, talk to any model, and plug into your IDE.

The biggest release since launch: roughly 4,100 lines of new code across the agent loop, token manager, MCP server and indexer.

Local models

Ollama that sizes itself to your GPU

Native Ollama API, VRAM detection on NVIDIA and Apple Silicon, and a num_ctx that shrinks on memory pressure instead of hanging.

codetrace set-ctx --backoff 0.75

IDE

A real MCP server, registered per project

Stdio server your IDE launches, with one entry per project in .mcp.json, .cursor/mcp.json and .vscode/mcp.json.

codetrace register-mcp .

Any LLM

Bring any endpoint

The custom provider speaks both the OpenAI and Anthropic protocols — DeepSeek, vLLM, LM Studio, corporate gateways. Keys optional for local servers.

codetrace config # → custom

Governance

Answers that cite or abstain

Every structural claim is graded CONFIRMED, INFERRED or UNRESOLVED and carries a live file:line citation. Output is normalized across providers.

codetrace chat

Security

Hardened by default

API-key config written atomically and owner-only, stricter project-path checks, writes outside the project refused before you're asked.

~/.codetrace/config.json (0600)

Reliability

Fixes that matter day to day

git_diff no longer returns empty, re-indexing keeps inbound call edges, timeouts show a real error, and CPU-only machines stop running out of memory while re-ranking.

pytest # 55 passing

Install: pip install — no Docker, no graph server
Models: 6 providers + any OpenAI/Anthropic-style endpoint
Local: GPU-aware context sizing for Ollama

100% Local Sandbox

Governed Pipeline Protocol

Moving AI Coding from Hallucinated Guessing
to Governed Deterministic Execution.

AI coding agents break production systems because they operate on unverified assumptions. CodeTrace AI enforces a formal evidence governance layer at the agent-loop level: every structural assertion must carry live verification.

● CONFIRMED

Live Tool Verified

Established directly by a live AST, symbol relation, or file snapshot tool execution in the active session.

Rule: Must cite exact file:line from tool output. No tool call = strictly prohibited from asserting as fact.

[CONFIRMED] auth/jwt.py:42
def verify(token: str, secret: str) -> dict:
  # Established via live get_symbol_relations() call
  # Callers: middleware/auth.py:18, api/routes/users.py:88

● INFERRED

Structural Deduction

Logical deduction derived from confirmed call patterns and graph topologies — strictly transparent.

Rule: Always prefixed with 'Based on the call pattern…' so developers know it is derived reasoning, not direct AST.

[INFERRED] Based on the call pattern between auth/jwt.py and
middleware/auth.py: modifying verify() parameter signature
will cascade an authentication bypass exception across all protected routes.

● UNRESOLVED

Zero-Guessing Abstention

Insufficient or ambiguous evidence — the agent explicitly refuses to guess and specifies what is missing.

Rule: Halts speculation. Informs the user exactly which files are un-indexed or what symbol is unresolved.

[UNRESOLVED] Symbol 'OAuthCallbackHandler' is referenced in routes/auth.py:14
but definition is not found in local index.
Action: Run 'codetrace index --fast' to include external vendor packages.

● Live CLI Session

Autonomous AI Architect Booting with Hardware Context Sizing

💻~/projects/codetrace · codetrace chat

Evidence Governed

⚡16 CPU Cores Detected

🔒Local Graph & Index

CodeTrace Live Governed Chat Session in CLI

Real capture of `codetrace chat` session with environment auto-sizing and session persistence.Click image to zoom ↗

🏛️ The 5-Stage Autonomous Investigation Loop

Applied in the narrowest sequence necessary. Enforced in the agent loop, not just the prompt: no tool evidence, no structural claim.

STEP 01

search_codebase

Hybrid semantic search (BGE + E5 + RRF + FlashRank reranker) retrieves candidate files.

➔

STEP 02

get_symbol_relations

Traverses SQLite + NetworkX call graph to identify callers, callees, and imports.

➔

STEP 03

read_file

Reads exact line ranges from indexed DB snapshots with path traversal safeguards.

➔

STEP 04

analyze_impact

Calculates transitive blast radius across modules, routes, and test suites.

➔

STEP 05

governed_report

Compiles evidence-graded response with mandatory file:line citations & output normalization.

No Tool, No Claim: Framework conventions and pre-training data are not evidence. Facts must originate from live AST tool executions.

Mandatory Citations: Every structural assertion carries an exact file:line citation from tool output. No citation → no claim.

Memory Is Context: Prior session summaries are context, never evidence. Recalled citations are invalid until re-verified live.

Output Normalizer: Response consistency layer normalizes markdown, code fences (`py` → `python`), and bullets across 7B Ollama to frontier models.

Interactive Product Tour

Interactive CLI Command Center

Explore CodeTrace AI's real developer terminal interface, hardware detection, dynamic model discovery, and IDE integration live.

Hardware AwareCapture #1 of 6

Autonomous AI Architect Session (`codetrace chat`)

CodeTrace AI boots in your terminal or IDE with automatic hardware resource detection (CPU cores, RAM, GPU context window), persistent session management, and governed evidence reasoning.

$ codetrace chat

✓Hardware-aware context auto-detection (RAM + CPU / GPU VRAM)

✓Zero cloud egress — runs entirely inside your local sandbox

✓Session history persistence across terminal restarts

✓Evidence-governed verification on every structural response

💻CodeTrace AI · 🧠 AI Architect Chat

Hardware Aware

⚡16 CPU Cores & RAM Auto-Detected

💾Session e6035c08 Persisted

CodeTrace Chat AI Architect Terminal Session

Autonomous AI Architect Session (`codetrace chat`)Click image to zoom ↗

Core Features

Engineered for Deep Structural Code Understanding

From first clone to confident shipping — everything you and your AI agent need to inspect, query, and refactor code safely.

Autonomous Code Research

Exact Line Citations Across Files

Ask complex engineering questions in natural language. The agent executes hybrid search, navigates AST symbols, and reads file ranges to formulate grounded answers with verified file:line citations.

# Query: "Where is UserToken issued and verified?"
auth/jwt.py:42 issues JWT tokens via create_token()
middleware/auth.py:18 verifies tokens via verify()
tests/test_auth.py:64 validates cryptographic signatures
Coverage: 3 references, 6 active callers [CONFIRMED]

Runtime Blast Radius Analysis

Know What Breaks Before You Edit

Maps exact caller/callee relationships across 21 languages using Tree-sitter ASTs. See every downstream function, route, database model, and test suite affected by a planned change.

● auth/jwt.py (Target Symbol: verify)
  ├── 1-hop: middleware/auth.py:18 (Auth Guard)
  ├── 1-hop: api/routes/users.py:42 (User Profile)
  ├── 2-hop: api/routes/admin.py:91 (Admin Dashboard)
  └── Test: tests/test_auth.py (14 test cases impacted)

Interactive Architecture Map

codetrace visualize (Self-contained HTML)

Generate an offline, interactive 3D/2D visual graph of your codebase architecture. Features collapsible directory trees, hover symbol inspectors, live filter search, and cross-folder call edges.

$ codetrace visualize
✓ Generated .codetrace/graph_visualization.html
✓ 142 Nodes, 4,891 Edges rendered
✓ Cross-folder dependency linkages mapped
Opening in default browser...

Human-in-the-Loop Safe Edits

Unified Diff Previews & Path Protection

Code modifications are proposed as clean unified diffs with built-in path-traversal protection. Nothing is ever written to disk without explicit developer confirmation.

--- a/middleware/auth.py
+++ b/middleware/auth.py
@@ -18,3 +18,4 @@
-    token = request.headers.get("Authorization")
+    token = sanitize_bearer(request.headers.get("Authorization"))
+    claims = verify(token, config.SECRET_KEY)
[Apply this diff to disk? (y/n/review)]:

SHA-256 Smart Delta Sync

Sub-Second Incremental Re-Indexing

Tracks file checksums to only re-parse files that actually changed. Subsequent runs complete in milliseconds even on million-line monolithic repositories.

$ codetrace index .
[Delta Sync] 139 files unchanged (hash match)
[Delta Sync] 3 files modified → re-indexed in 0.38s
[Vector Sync] ChromaDB delta updated successfully

Output Normalizer Layer

Provider-Agnostic Response Consistency

Normalizes headings, list symbols, code-fence aliases (`py` → `python`), and spacing across all models — from local 7B Ollama to frontier cloud LLMs, ensuring a uniform CLI aesthetic.

# output_normalizer.py in agent loop
def normalize_response(raw_text: str) -> str:
  # Normalizes code fences, heading levels,
  # removes markdown artifacts, enforces uniform CLI styling
  return normalized_rich_text

Architecture

The 8-Stage Local Intelligence Pipeline

From raw source files to governed AI reasoning and MCP IDE integration. Every layer is inspectable, modular, and 100% offline-first.

STEP 01

📂

Source Ingestion

STEP 02

🌲

Tree-sitter AST

STEP 03

📊

Call Graph

STEP 04

🧠

Local Embeddings

STEP 05

🔍

Hybrid Search

STEP 06

⚡

Token Budget

STEP 07

🏛️

Governed Loop

STEP 08

🔌

MCP & CLI

1. Repository & Git Delta Ingestion

Ingests any local directory or clones a GitHub URL. Computes SHA-256 delta hashes per file to bypass unchanged files during incremental sync.

✓Zero network telemetry — 100% offline parsing

✓Git-aware branch and ignore resolution (.gitignore)

✓Supports local directories or direct GitHub URL clones

Pipeline Execution Trace

[Ingestion Engine]
Hashing repository tree...
Checked 142 files via SHA-256
Unmodified: 139 files (cached)
Changed: 3 files scheduled for AST pass

● Architecture Design

Deterministic Code Intelligence Graph Architecture

Hybrid Brain Engine

Multi-layer symbol graph interconnecting Tree-sitter ASTs, BGE/E5 dense embeddings, SQLite relational tables, NetworkX call graphs, and live MCP reasoning sessions.

Agentic Tool Suite

7 Autonomous Tools for Complete Code Mastery

The AI Architect and external MCP clients invoke these 7 tools autonomously to search, inspect, traverse, and propose changes without guessing.

search_codebaseChromaDB + FlashRank

Executes dense vector embedding search + sparse BM25 retrieval merged via Reciprocal Rank Fusion (RRF) and scored with local FlashRank neural reranking.

Parameters

Param	Type	Description
query	string	Natural language query describing symbol, behavior, or feature
limit	int	Maximum precision candidate snippets to return (default: 5)

Invocation

search_codebase(query="rate limiting token bucket", limit=3)

Live Response Sandbox● Structured JSON / Diff

[
  {
    "file": "middleware/rate_limiter.py",
    "lines": "24-58",
    "score": 0.942,
    "snippet": "class TokenBucketLimiter:\n    def allow_request(self, key): ..."
  },
  {
    "file": "config/limits.yaml",
    "lines": "1-15",
    "score": 0.887,
    "snippet": "rate_limits:\n  api_v1: 100/min\n  admin: 500/min"
  }
]

IDE Integration (MCP)

Native Model Context Protocol (MCP)

codetrace init automatically registers the MCP server in Cursor, Claude Code, and VS Code. Your favorite editor instantly gains access to all 7 tools for in-editor AI assistance.

Cursor IDE

Auto-Registered

CodeTrace automatically injects the MCP server configuration into your Cursor settings during `codetrace init`.

Config Target: ~/.cursor/mcp.json

MCP CONFIGURATIONCopy

{
  "mcpServers": {
    "codetrace": {
      "command": "python",
      "args": ["-m", "codetrace_mcp.server", "--project", "/path/to/your/project"]
    }
  }
}

● Real MCP Server Execution

Automatic Registration & Standalone MCP Server

codetrace register-mcp .

💻VS Code Terminal · codetrace register-mcp .

Auto-Registration Active

✓✓ Cursor Config Written

🔌✓ Claude Code Connected

Automatic registration in Cursor, Claude Code, and VS Code during initialization.Click image to zoom ↗

LLM Ecosystem

Connect Any Model. From 7B Local to Frontier Cloud.

CodeTrace ships with six native providers out of the box plus a universal custom option for self-hosted vLLM, LM Studio, DeepSeek, or corporate proxies.

●Anthropic(Native Messages API)

●OpenAI(OpenAI-compatible)

●Ollama (Local)(100% Offline & Free)

●Groq(Ultra-Fast Inference)

●Google Gemini(1M+ Context)

●OpenRouter(Unified Router)

●Custom Endpoint(Any OpenAI / Anthropic API)

🛠️ Interactive Custom Endpoint Configurator

Test your endpoint settings. CodeTrace prompts for these during codetrace config and stores them at ~/.codetrace/config.json.

API Style

API Base URL

Model Name

API Key (Optional for local/self-hosted endpoints)

~/.codetrace/config.jsonLive Generated

{
  "provider": "custom",
  "api_style": "openai",
  "base_url": "https://api.deepseek.com/v1",
  "model_name": "deepseek-chat"
}

💡 Verified Working Endpoints:

DeepSeek (deepseek-chat), LM Studio (localhost:1234), vLLM (localhost:8000), Fireworks, Mistral, Together, Cerebras, Nebius, and internal enterprise gateways.

● Real Configuration & Model Enumeration

Dynamic Endpoint Setup & Live API Model Querying

💻Terminal · codetrace config --custom

Custom Nvidia NIM Gateway

🌐Nvidia API Base Configured

⚡Context Window Auto-Detect

CodeTrace Config Custom Nvidia Provider CLI

Configure custom provider endpoints and authenticate securely.Click image to zoom ↗

🔒 Privacy-First & Hardware-Aware Ollama Recommendations

CodeTrace automatically detects your GPU VRAM, sizes num_ctx safely, and backs off on CPU memory pressure so your system never hangs.

8 GB RAMEntry Level

Fast inference on ultrabooks and standard laptops.

• qwen2.5-coder:7b
• deepseek-r1:7b
• phi4-mini

16 GB RAM★ Sweet Spot

Optimal balance of speed and deep structural reasoning.

• qwen2.5-coder:14b
• deepseek-r1:14b
• gemma3:12b

32 GB+ RAMPro / Frontier Local

Near frontier-level reasoning entirely on your workstation.

• qwen2.5-coder:32b
• deepseek-r1:32b
• devstral:24b

Language Ecosystem

Native Support for 21 Programming & Config Languages

17 parsed with native Tree-sitter grammars into complete symbol + call graphs; 4 config and data formats parsed into structural symbol hierarchies.

Python

Tree-sitter AST + Call Graph

.py

TypeScript

Tree-sitter AST + Call Graph

.ts, .tsx

JavaScript

Tree-sitter AST + Call Graph

.js, .jsx

Rust

Tree-sitter AST + Call Graph

.rs

Tree-sitter AST + Call Graph

.go

Java

Tree-sitter AST + Call Graph

.java

C++

Tree-sitter AST + Call Graph

.cpp, .hpp

Tree-sitter AST + Call Graph

.c, .h

Tree-sitter AST + Call Graph

.cs

PHP

Tree-sitter AST + Call Graph

.php

Swift

Tree-sitter AST + Call Graph

.swift

Kotlin

Tree-sitter AST + Call Graph

.kt

Bash

Tree-sitter AST + Call Graph

.sh

HTML

Tree-sitter AST + Call Graph

.html

CSS

Tree-sitter AST + Call Graph

.css

JSON

Tree-sitter AST + Call Graph

.json

YAML

Structural Symbol Indexer

.yaml, .yml

TOML

Structural Symbol Indexer

.toml

SQL

Structural Symbol Indexer

.sql

Dockerfile

Structural Symbol Indexer

Dockerfile

Live Playground

Interactive Blast Radius & Governed Diff Engine

Click any file below to inspect its live call-graph dependents, blast radius impact score, and proposed safe diff preview.

CodeTrace Dynamic Blast Radius & Diff Inspector

● Deterministic AST

Repository Files

📄auth/jwt.py

📄middleware/auth.py

📄api/routes/users.py

📄tests/test_auth.py

auth/jwt.py

8 Symbols Indexed · Call graph node verified

Blast Radius

Tests Affected

DOWNSTREAM DEPENDENTS

↳ middleware/auth.py

↳ api/routes/users.py

↳ api/routes/admin.py

EXTRACTED SYMBOLS

● create_token()

● verify()

● decode_header()

Human-in-the-Loop Diff ProposalRefactor: Enforce strict RS256 algorithm verification to eliminate fallback CVEs

--- a/auth/jwt.py
+++ b/auth/jwt.py
@@ -42,4 +42,5 @@
-def verify(token: str, secret: str) -> dict:
-    return jwt.decode(token, secret)
+def verify(token: str, secret: str, algorithms: list = ["RS256"]) -> dict:
+    return jwt.decode(token, secret, algorithms=algorithms)
 [Awaiting Human Approval]

CLI Reference

Clean, Intuitive Command Line Interface

Everything in CodeTrace AI is accessible through intuitive CLI commands with rich shell output, progress indicators, and flags.

codetrace init

One-command setup: configure LLM provider, download embedding models, index repository, and register MCP in Cursor, Claude Code, and VS Code.

codetrace init [PATH]

Command Flags

--offlineStrict air-gapped mode (blocks external calls)

--fastUse smaller embedding models for lower RAM usage

--llm <provider>Pre-select provider: anthropic, openai, gemini, groq, openrouter, ollama, custom

Terminal Example

cd /path/to/my-project
codetrace init
# Or air-gapped mode:
codetrace init --offline

● Comprehensive CLI Reference Manual

Complete `codetrace --help` Options & Commands

💻VS Code Terminal · codetrace --help

CLI Manual v1.0.3

⚙️12 Commands Documented

📖Detailed Options & Flags

Complete CLI help output showing all options, subcommands, and flags.Click image to zoom ↗

Release Changelog

Continuous Evolution & Releases

CodeTrace AI is actively developed with rapid improvements in deterministic AST parsing, local agent governance, and IDE integration.

v1.0.3· September 2026

Latest

•NEW: codetrace mcp (stdio) and codetrace register-mcp — per-project MCP registration for Claude Code, Cursor and VS Code.

•NEW: Governed Pipeline Protocol — every structural claim carries a live file:line citation and is graded CONFIRMED / INFERRED / UNRESOLVED.

•NEW: Hardware-aware Ollama — native API, GPU memory detection, automatic num_ctx sizing and back-off (set-ctx --backoff).

•NEW: Custom provider for any OpenAI- or Anthropic-compatible endpoint; set-default-ctx and set-model-limits for unknown cloud models.

•NEW: Output Normalizer — answers render identically across every provider.

•SECURITY: API-key config written atomically with owner-only permissions; stricter project-path checks; writes outside the project refused.

•FIXED: git_diff returned empty diffs; re-indexing dropped inbound call edges; blank error messages on timeouts; Ollama startup crash.

•IMPROVED: Thread-safe parsing, chunked vector upserts, batched re-ranking for CPU-only machines, first automated test suite in CI.

v1.0.2· July 2026

Update

•NEW: Dynamic model context window resolution via LiteLLM token counting.

•NEW: Ollama loaded context window (num_ctx) runtime detection.

•FIXED: PyPI packaging wheel includes all Tree-sitter .scm queries and database modules.

•IMPROVED: Dynamic conversation history compression preventing out-of-memory crashes.

v1.0.1· June 2026

Feature Release

•NEW: Interactive Architecture Visualizer (codetrace visualize) with collapsible tree and cross-folder edges.

•NEW: Expanded language support to 21 total languages (C#, Swift, Kotlin, Bash, HTML, CSS, JSON, SQL, YAML, TOML, Dockerfile).

•NEW: 3-Tier Token Budget Manager & pure httpx multi-provider agent loop.

•IMPROVED: Parallel file AST parsing with ThreadPoolExecutor for 4x faster indexing.

Pricing & Access

100% Free & Open Source CLI.
Optimized Team Tier Coming Soon.

The core codetrace-ai package is completely free, MIT licensed, and runs entirely on your hardware. Join our waitlist for first access to the upcoming hosted team engine.

Available on PyPI

Community CLI

Full-featured local governed code intelligence for individual developers and air-gapped systems.

$0/ free forever (MIT)

100% Local & Air-Gapped (Zero cloud telemetry)

Governed Pipeline Protocol with mandatory citations

21 Language AST & Call Graph parsing

Deterministic SQLite + NetworkX graph builder

Automatic MCP registration (Cursor, Claude, VS Code)

ChromaDB + FlashRank hybrid neural search

SHA-256 Smart Delta Sync engine

Interactive Architecture Visualizer (HTML map)

Hardware-aware Ollama dynamic token budgeting

✨ Coming Soon

CodeTrace AI · Optimized

High-throughput cloud-accelerated repository indexing, multi-repo workspaces, and collaborative team intelligence.

Early Access/ waitlist open

Multi-repo cross-repository dependency tracing

Real-time team call graphs & shared diff reviews

Cloud-accelerated GPU embedding clusters

Automated PR Blast Radius checks in CI/CD

Private VPC / Enterprise SOC2 compliance

Dedicated custom Tree-sitter AST grammar support

The Governed Code Intelligence Layer for AI Agents & Engineers

Built to run on your laptop, talk to any model, and plug into your IDE.

Ollama that sizes itself to your GPU

A real MCP server, registered per project

Bring any endpoint

Answers that cite or abstain

Hardened by default

Fixes that matter day to day

Moving AI Coding from Hallucinated Guessingto Governed Deterministic Execution.

Live Tool Verified

Structural Deduction

Zero-Guessing Abstention

Autonomous AI Architect Booting with Hardware Context Sizing

Interactive CLI Command Center

Autonomous AI Architect Session (`codetrace chat`)

Engineered for Deep Structural Code Understanding

Autonomous Code Research

Runtime Blast Radius Analysis

Interactive Architecture Map

Human-in-the-Loop Safe Edits

SHA-256 Smart Delta Sync

Output Normalizer Layer

The 8-Stage Local Intelligence Pipeline

1. Repository & Git Delta Ingestion

Deterministic Code Intelligence Graph Architecture

7 Autonomous Tools for Complete Code Mastery

Native Model Context Protocol (MCP)

Cursor IDE

Automatic Registration & Standalone MCP Server

Connect Any Model. From 7B Local to Frontier Cloud.

🛠️ Interactive Custom Endpoint Configurator

Dynamic Endpoint Setup & Live API Model Querying

🔒 Privacy-First & Hardware-Aware Ollama Recommendations

Native Support for 21 Programming & Config Languages

Interactive Blast Radius & Governed Diff Engine

auth/jwt.py

Clean, Intuitive Command Line Interface

codetrace init

Complete `codetrace --help` Options & Commands

Continuous Evolution & Releases

100% Free & Open Source CLI.Optimized Team Tier Coming Soon.

Community CLI

CodeTrace AI · Optimized

Moving AI Coding from Hallucinated Guessing
to Governed Deterministic Execution.

100% Free & Open Source CLI.
Optimized Team Tier Coming Soon.