Metadata-Version: 2.4
Name: codetrace-ai
Version: 1.0.2
Summary: Local-first AI codebase intelligence: call graphs, blast radius analysis, SHA-256 delta sync — zero cloud dependency
Author-email: Viraj Sawant <sawantviraj465@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Viraj465/codetrace-ai
Project-URL: Repository, https://github.com/Viraj465/codetrace-ai
Project-URL: Bug Tracker, https://github.com/Viraj465/codetrace-ai/issues
Project-URL: Changelog, https://github.com/Viraj465/codetrace-ai/releases
Keywords: cli,ai,llm,rag,agent,mcp,static-analysis,reverse-engineering,code-visualization,call-graph,ast,tree-sitter,chromadb,hybrid-search,code-intelligence,developer-tools,architecture
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: rich>=14.3.3
Requires-Dist: pydantic>=2.12.5
Requires-Dist: typer[all]>=0.24.1
Requires-Dist: httpx>=0.28.0
Requires-Dist: pathspec
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-typescript
Requires-Dist: tree-sitter-java
Requires-Dist: tree-sitter-go
Requires-Dist: tree-sitter-c
Requires-Dist: litellm
Requires-Dist: tree-sitter-cpp
Requires-Dist: tree-sitter-rust
Requires-Dist: tree-sitter-php
Requires-Dist: tree-sitter-html
Requires-Dist: tree-sitter-json
Requires-Dist: tree-sitter-css
Requires-Dist: tree-sitter-c-sharp
Requires-Dist: tree-sitter-swift
Requires-Dist: tree-sitter-kotlin
Requires-Dist: tree-sitter-bash
Requires-Dist: torch==2.5.1
Requires-Dist: sentence-transformers==3.4.1
Requires-Dist: transformers==4.48.3
Requires-Dist: chromadb>=1.5.2
Requires-Dist: networkx>=3.6.1
Requires-Dist: fastapi>=0.134.0
Requires-Dist: watchfiles>=1.1.1
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: uvicorn>=0.41.0
Requires-Dist: markitdown>=0.1.5
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: flashrank>=0.2.10
Requires-Dist: mcp>=1.26.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlglot>=25.0.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"

<p align="center">
  <img src="Logos/CodetraceAI-banner.png" alt="Codetrace-ai Banner" width="100%"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/codetrace-ai/"><img src="https://img.shields.io/pypi/v/codetrace-ai?color=orange&label=PyPI&logo=pypi&logoColor=white" alt="PyPI Version"/></a>
  <a href="https://pepy.tech/projects/codetrace-ai"><img src="https://static.pepy.tech/badge/codetrace-ai" alt="Total Downloads"/></a>
  <a href="https://pepy.tech/projects/codetrace-ai"><img src="https://static.pepy.tech/badge/codetrace-ai/month" alt="Monthly Downloads"/></a>
  <a href="https://github.com/Viraj465/CodeTrace-ai/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License"/></a>
  <a href="https://github.com/Viraj465/CodeTrace-ai/stargazers"><img src="https://img.shields.io/github/stars/Viraj465/CodeTrace-ai?style=social" alt="GitHub Stars"/></a>
  <a href="https://github.com/Viraj465/CodeTrace-ai/issues"><img src="https://img.shields.io/github/issues/Viraj465/CodeTrace-ai" alt="Open Issues"/></a>
  <a href="https://github.com/Viraj465/CodeTrace-ai/pulls"><img src="https://img.shields.io/github/issues-pr/Viraj465/CodeTrace-ai" alt="Open Pull Requests"/></a>
  <a href="https://github.com/Viraj465/CodeTrace-ai/actions"><img src="https://img.shields.io/github/actions/workflow/status/Viraj465/CodeTrace-ai/main.yml?branch=main" alt="Build Status"/></a>
  <a href="https://join.slack.com/t/codetraceaicommunity/shared_invite/zt-426wp89up-7bgYODTfYeKLE~psG5Jy8Q"><img src="https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack&logoColor=white" alt="Join Slack"/></a>
  <a href="https://github.com/Viraj465/CodeTrace-ai/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"/></a>
</p>

<h1 align="center">🧠 CodeTrace AI</h1>

<p align="center">
  <strong>Give your AI coding agent X-ray vision into your codebase — call graphs, blast radius, and architecture maps, 100% local.</strong>
</p>

<p align="center">
  CodeTrace AI gives your AI coding agent a complete map of your codebase — blast radius, call graphs, architecture boundaries — served 100% locally, zero cloud.
  <br/>
  <a href="https://codetraceai.in">Website</a> · <a href="https://pypi.org/project/codetrace-ai/">PyPI</a> · <a href="https://dev.to/viraj465/codetrace-ai-v101-ai-powered-code-intelligence-with-sha-256-delta-sync-interactive-code-graphs-257i">Blog Post</a>
</p>

---

## 🎥 See it in Action

[![Watch Demo](https://img.youtube.com/vi/2RbFVw-wfgE/0.jpg)](https://youtu.be/2RbFVw-wfgE)

---

## 💡 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**

```bash
pip install codetrace-ai
```
```bash
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

```bash
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`:
```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](CONTRIBUTING.md) for guidelines.

💬 **Help shape Codetrace:** [Join the discussion →](https://github.com/Viraj465/CodeTrace-ai/discussions/5#discussion-9684949)

---

## 📄 License

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