🧠 CodeTrace AI

The Governed Code Intelligence Layer for AI Agents — Deterministic Call Graphs, Blast Radius Verification, and Evidence-Backed Reasoning, 100% Local.

CodeTrace AI turns your codebase into a deterministic structural graph and enforces a Governed Pipeline Protocol — giving AI agents and developers verified blast radius and exact `file:line` citations. Parsing, embeddings and the graph run 100% on your machine; pair it with Ollama and nothing leaves it at all.
Website · PyPI · Blog Post

_{Real session, shown at 2× speed: blast-radius question on pallets/itsdangerous, answered by qwen3.5:4b via Ollama on a 6 GB laptop GPU. Nothing left the machine.}

🎥 See it in Action

💡 Why CodeTrace AI?

AI coding agents break production systems because they operate on unverified assumptions. They edit functions without understanding downstream callers, fabricate plausible-sounding file paths, and suffer from the self-correction blind spot — unable to detect structural errors in their own suggestions.

CodeTrace moves AI coding from guessing to governed, deterministic execution:

• 🏛️ Governed Pipeline Protocol. Every structural claim is evidence-graded (CONFIRMED, INFERRED, UNRESOLVED) and anchored to mandatory file:line citations. The agent abstains when evidence is missing rather than hallucinating.
• 💥 Runtime Blast Radius Verification. Maps exact caller/callee relationships across 21 languages using Tree-sitter ASTs so you see every affected module, test, and consumer before an edit commits.
• ✍️ Human-in-the-Loop Safe Edits. Code changes are proposed as unified diff previews with path-traversal protection — nothing writes to disk without explicit approval.
• 🎨 Provider-Agnostic Output Consistency. Built-in normalizer standardizes formatting, syntax blocks, and headings across any model — from local Ollama (7B) to frontier cloud LLMs.
• 🔒 100% Local & Air-Gapped. All parsing, vector embeddings, and graph traversal run entirely on your hardware. With Ollama (or --offline), zero code leaves your machine; with a cloud LLM, only the snippets the agent retrieves are sent to your provider.

🚀 Installation

Requires Python 3.10–3.12

pip install codetrace-ai

uv pip install codetrace-ai

⚡ Quick Start

cd /path/to/your/project
codetrace init       # configure LLM + download models + index + register MCP
codetrace chat       # start the AI Architect session

codetrace init does everything in one command: configures your LLM provider, downloads embedding models, indexes your codebase, and registers the MCP server for Cursor, Claude Code, and VS Code.

✨ Features

🏛️ Governed Pipeline Protocol

v1.0.3 ships a formal evidence governance layer baked into the system prompt and enforced at the agent-loop level. The agent operates under strict source-of-truth rules:

Evidence States — every claim carries one:

Structural Rules:

1. No structural fact may be asserted without a tool call that session. Framework conventions and training data are not evidence.
2. Every structural claim carries a file:line citation from tool output. No citation → no claim.
3. Memory (compressed summaries, prior sessions) is context, not evidence. A recalled citation is invalid until re-verified live.
4. If evidence is missing: the agent states exactly what's missing and what re-indexing is required — never inventing paths, symbols, or relationships.

Investigation Protocol — applied in the narrowest sequence the question needs:

search_codebase → get_symbol_relations → read_file → analyze_impact → report

This is not just prompt engineering — it's an architectural constraint. The output normalizer enforces consistent formatting, and the token manager adapts how much context each tier gets so the governance rules actually fit in the window.

🌍 Language Support

21 languages. 17 are parsed with Tree-sitter into a full symbol + call graph; 4 config/data formats are parsed into symbols for search and structure.

🧠 Connecting Any LLM

Codetrace ships with six providers configured out of the box, plus a custom option for everything else.

Using a provider that isn't listed

Pick custom during codetrace config and answer three questions — API style, base URL, and model name:

1. Choose your LLM Provider: custom
2. API style [openai/anthropic]: openai
2a. API base URL: https://api.deepseek.com/v1
2b. API key (leave blank for a local or unauthenticated endpoint): ****
3. Enter model name: deepseek-chat

Codetrace fetches the endpoint's model list automatically when it exposes one; otherwise you just type the model name.

Choosing the API style — this decides the request path, so it has to match your endpoint:

Verified examples:

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

// Self-hosted vLLM / LM Studio — no API key needed
{ "provider": "custom", "api_style": "openai",
  "base_url": "http://localhost:8000/v1", "model_name": "Qwen/Qwen2.5-Coder-32B" }

// An Anthropic-compatible gateway
{ "provider": "custom", "api_style": "anthropic",
  "base_url": "https://gateway.internal", "model_name": "claude-opus-5" }

The same shape works for Together, Fireworks, Mistral, Cerebras, DeepInfra, Nebius, corporate proxies — anything speaking either protocol. Config lives at ~/.codetrace/config.json.

🔒 Privacy-First Architecture

Codetrace can operate 100% offline with zero external dependencies:

1. Local LLM: Configure any local provider via Ollama (e.g., llama3.2, deepseek-coder, qwen2.5-coder).
2. Local Embeddings: Uses HuggingFace bge-small + e5-small models, downloaded once and cached.
3. True Air-Gap: Transfer the HuggingFace cache (~/.cache/huggingface/hub) via USB. Run codetrace init --offline to block all external calls permanently.

🛠️ CLI Command Reference

Flags:

In-chat commands:

• /clear — Start a fresh session without exiting
• exit / quit — Close the chat

🤖 Agentic Tool Suite

The AI has access to 7 specialized tools it invokes autonomously:

🔌 IDE Integration (MCP)

codetrace init automatically registers the MCP server for Claude Code, Cursor, and VS Code in the project's own config files — .mcp.json, .cursor/mcp.json, and .vscode/mcp.json — so each project's server points at that project's index. Existing entries in those files are kept; a file that isn't plain JSON (for example, one with comments) is left untouched and reported so you can add the entry by hand. Re-run codetrace register-mcp any time. These files contain absolute paths for your machine, so you may want to keep them out of version control.

Your IDE instantly gains access to all 7 tools above for in-editor AI assistance.

Running the MCP Server directly via CLI

You can also start the MCP server yourself for any indexed project. It speaks MCP over stdio, so it's meant to be launched by an IDE or agent, which then talks to it over stdin/stdout:

codetrace mcp .                         # start MCP server on current directory
codetrace mcp /path/to/project          # start MCP server on a specific project

Using Windsurf? Add it manually to your mcp.json. The server ships inside the installed package, so point at that — not at your project:

"codetrace": {
  "command": "/path/to/your/python",
  "args": [
    "/path/to/site-packages/codetrace_mcp/server.py",
    "--project",
    "/absolute/path/to/your/project"
  ]
}

Find both paths with:

python -c "import sys, codetrace_mcp, pathlib; print(sys.executable); print(pathlib.Path(codetrace_mcp.__file__).parent / 'server.py')"

📂 File Structure

After codetrace init, your project will have:

your-project/
├── .codetrace/
│   ├── chroma/                ← vector embeddings (ChromaDB)
│   ├── graph_metadata.db      ← code call graph (SQLite + NetworkX)
│   ├── sync_metadata.db       ← SHA-256 delta sync state
│   ├── chat_history.db        ← persistent chat sessions
│   └── graph_visualization.html  ← generated by `codetrace visualize`
├── src/
└── your code files

Global config is stored at ~/.codetrace/config.json

🆕 Changelog

v1.0.3 — September 2026

• ✅ NEW: codetrace mcp [PATH] — start the MCP server (stdio) straight from the CLI, and codetrace register-mcp to (re)register it per project for Claude Code, Cursor and VS Code
• ✅ NEW: Governed Pipeline Protocol — every structural claim must carry a live file:line citation and is graded CONFIRMED / INFERRED / UNRESOLVED; memory is treated as context, never as evidence
• ✅ NEW: Output Normalizer — normalizes headings, bullet styles, code-fence language tags and spacing so answers render the same whichever provider you use
• ✅ NEW: The custom provider connects to any OpenAI- or Anthropic-compatible endpoint (DeepSeek, vLLM, LM Studio, gateways). API keys are optional for local endpoints
• ✅ NEW: Hardware-aware Ollama — native Ollama API, GPU memory detection (NVIDIA / Apple Silicon), automatic num_ctx sizing, and auto-lowering under memory pressure. Tune with codetrace set-ctx [TOKENS] --backoff 0.75
• ✅ NEW: codetrace set-default-ctx and codetrace set-model-limits for cloud models LiteLLM doesn't know
• ✅ NEW: Indexing a GitHub/GitLab URL keeps the clone under ~/.codetrace/repos/, so re-indexing is incremental and you can codetrace chat against it
• ✅ SECURITY: ~/.codetrace/config.json (holds your API key) is now written atomically with owner-only permissions
• ✅ SECURITY: read_file / write_file path checks use is_relative_to, so a sibling folder like project-secret no longer passes for project; writes outside the project are refused before the approval prompt
• ✅ FIXED: git_diff always returned an empty diff (the revision was passed after --, so git treated HEAD as a filename)
• ✅ FIXED: Blank "Architect Error:" messages — timeouts and other empty exceptions now show a readable cause
• ✅ FIXED: Re-indexing a file dropped inbound call edges from other files; calls no longer resolve across unrelated languages
• ✅ FIXED: API-key leak detector no longer flags commit SHAs and long identifiers as keys
• ✅ FIXED: NameError: logger that crashed every Ollama session at startup
• ✅ FIXED: MCP auto-registration pointed at the indexed project instead of the installed package; it now registers the current interpreter
• ✅ FIXED: Gemini 400 errors from stream_options; Gemini now always runs at temperature 1.0
• ✅ IMPROVED: Thread-safe Tree-sitter parsing, chunked ChromaDB upserts, batched FlashRank re-ranking (no more OOM on CPU-only machines), SQLite-safe chunked deletes, case-insensitive paths on Windows
• ✅ IMPROVED: Built-in ignore list (node_modules, virtualenvs, IDE folders, …) and correct handling of nested .gitignore files
• ✅ TESTS: First automated test suite (indexing regressions, MCP server, output normalizer, safety & config, token manager) running in CI

v1.0.2 — July 2026

• ✅ FIXED: PyPI packaging bug — 4 missing __init__.py files caused src/cli, src/backend, src/core/agents, and src/core/database to be silently excluded from the wheel, making the installed package non-functional
• ✅ FIXED: Tree-sitter .scm query files were not included in the PyPI wheel, causing parser failures on a fresh install
• ✅ NEW: Dynamic model context window resolution via litellm — the token budget manager now auto-detects the correct context window for any model at runtime, eliminating the need for a hardcoded tier registry
• ✅ NEW: Ollama context window detection — queries the local Ollama API to get the actual loaded context size for your model
• ✅ IMPROVED: Token counting now uses litellm.token_counter with provider-specific tokenizers for accurate budgeting across all models
• ✅ IMPROVED: Context compression is now dynamic — automatically reduces keep_turns if a compressed history still exceeds the hard context limit, preventing OOM errors

v1.0.1 — June 2026

• ✅ NEW: Interactive Architecture Visualizer (codetrace visualize) with collapsible tree, hover panels, search, and cross-folder call edges
• ✅ NEW: Expanded language support — C#, Swift, Kotlin, Bash, HTML, JSON, CSS, YAML, SQL, TOML, Dockerfile (21 languages total)
• ✅ NEW: Token Budget Manager — 3-tier context window management with auto-history compression
• ✅ NEW: Multi-provider Agent Loop via pure httpx (zero LangChain dependency)
• ✅ NEW: Live model listing during codetrace config — fetches available models from your provider's API
• ✅ IMPROVED: Parallel file parsing with ThreadPoolExecutor for significantly faster indexing
• ✅ IMPROVED: Path traversal protection on read_file and write_file tools

v0.1.2 — Initial Release

• Initial public release with Hybrid Brain engine (BGE + E5 + ChromaDB + NetworkX)
• Core agentic tool suite (search_codebase, analyze_impact, write_file, git_diff)
• MCP auto-registration for Cursor and Claude Code
• SHA-256 Smart Delta Sync
• GitHub URL cloning + indexing support
• Persistent chat sessions with history and export

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

💬 Help shape Codetrace: Join the discussion →

📄 License

MIT License — Copyright (c) 2026 Viraaj Sawant. See LICENSE for details.