🧠 CodeTrace AI

Give your AI coding agent X-ray vision into your codebase — call graphs, blast radius, and architecture maps, 100% local.

CodeTrace AI gives your AI coding agent a complete map of your codebase — blast radius, call graphs, architecture boundaries — served 100% locally, zero cloud.
Website · PyPI · Blog Post

---

🎥 See it in Action

---

💡 Why CodeTrace AI?

AI coding agents are powerful — but they break things because they don't understand blast radius. They edit a function without knowing it's called by 12 other modules. They suggest refactors without seeing how execution flows through the entire system.

CodeTrace maps your entire codebase locally so your AI agent stops guessing and starts understanding — before it edits.

• No cloud. All parsing, embedding, and graph mapping runs on your machine.
• No guessing. The agent sees real call graphs, not just keyword matches.
• No surprises. Blast radius analysis shows exactly what breaks before you change it.

---

🚀 Installation

Requires Python 3.10–3.12

pip install codetrace-ai

uv pip install codetrace-ai

[!NOTE] Python 3.14 may have compatibility issues with some dependencies. Python 3.10–3.12 is recommended for the best experience. GPU users should ensure CUDA is installed.

---

⚡ 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 and Claude Code.

---

✨ Features

Feature	Description
🔍 Autonomous Code Research	Ask anything in natural language — the agent searches, reads files, and traverses the call graph to answer with citations to exact lines
🗺️ Interactive Architecture Map	codetrace visualize generates a self-contained interactive HTML graph of your entire code architecture
📊 Structural Call Graph	Maps class and function definitions across 15+ languages — see exactly how your application is wired
💥 Blast Radius Analysis	Before editing production code, see every file, test, and consumer that will be impacted
✍️ Human-in-the-Loop Edits	Proposes code changes with a rich diff preview — you approve or decline before anything is written to disk
⚡ SHA-256 Delta Sync	Re-indexes only files that changed. Lightning fast on every subsequent run
🔌 IDE Integration (MCP)	Connects the call graph directly into Cursor, Windsurf, or Claude Code for in-editor AI assistance
📜 Persistent Chat Sessions	All conversations are saved. Resume any past session by ID, or export to Markdown
🔒 100% Local & Air-Gapped	All parsing, embedding, and graph mapping happens on your machine. Zero data leaves without your consent

---

🔒 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.

[!WARNING] Ollama Users — Context Window & RAM The effective context window is directly limited by your available RAM. If the model's context exceeds available RAM, Ollama may hang or crash silently.

Recommendations:

• 8 GB RAM: qwen2.5-coder:7b · deepseek-r1:7b · phi4-mini
• 16 GB RAM: qwen2.5-coder:14b · deepseek-r1:14b · gemma3:12b (recommended sweet spot)
• 32 GB+ RAM: qwen2.5-coder:32b · deepseek-r1:32b · devstral:24b (near frontier-level locally)

If Codetrace hangs during chat while using Ollama, the most likely cause is the model running out of RAM. Switch to a smaller model with codetrace config.

---

🛠️ CLI Command Reference

Command	Description
codetrace init [PATH]	One-command setup: config → download models → index → register MCP
codetrace chat	Launch the interactive AI Architect chat loop
codetrace chat --resume <ID>	Resume a specific past chat session
codetrace index <PATH or URL>	Re-index a local directory or clone + index a GitHub URL
codetrace config	View or update your LLM provider and API key
codetrace visualize	Generate an interactive HTML architecture graph
codetrace history	List all past chat sessions for the current project
codetrace export <ID>	Export a chat session to Markdown

Flags:

• --offline — Strict air-gapped mode (blocks all external requests)
• --fast — Use smaller embedding models for lower RAM usage
• --llm <provider> — Pre-select provider: groq, openai, anthropic, gemini, ollama

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:

Tool	What it does
search_codebase	Hybrid semantic search (BGE + E5 + RRF + FlashRank reranker)
get_symbol_relations	Graph traversal — see callers and dependencies of any symbol
analyze_impact	Blast radius — find every downstream symbol affected by a change
read_file	Read full file content from the indexed DB snapshot
write_file	Propose a code change with a diff preview for your approval
inspect_index	List all indexed files and DB coverage metadata
git_diff	Run a safe, injection-protected git diff

---

🔌 IDE Integration (MCP)

codetrace init automatically registers the MCP server in Cursor and Claude Code. No manual configuration needed.

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

Using Windsurf? Add it manually to your mcp.json:

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

---

📂 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.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 (15+ 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.