Metadata-Version: 2.4
Name: repo-codemind
Version: 1.0.0
Summary: Structured codebase intelligence for Claude and Copilot via MCP — dependency graphs, blast-radius analysis, and architecture diagrams for Python and C# repos.
License: Proprietary
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.111
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: structlog>=24.0
Requires-Dist: tree-sitter-c-sharp>=0.21
Requires-Dist: tree-sitter-python>=0.21
Requires-Dist: tree-sitter>=0.21
Requires-Dist: uvicorn[standard]>=0.30
Description-Content-Type: text/markdown

# CodeMind

**Structured codebase intelligence for Claude and Copilot — via MCP.**

CodeMind indexes your Python and C# repositories into a local SQLite graph, then exposes that graph through a Model Context Protocol server. Instead of asking an AI to read dozens of files, you get single tool calls for dependency tracing, blast-radius analysis, architecture diagrams, and project planning — with a local web dashboard to explore everything visually.

---

## Why CodeMind

Every time you ask Claude to understand a codebase it re-reads the same files, burns tokens, and loses context. CodeMind replaces that pattern with a persistent, queryable knowledge graph that lives next to your code.

| Without CodeMind | With CodeMind |
|---|---|
| "Read `services/user.py`, then `db/queries.py`, then…" | `get_callers("UserService.authenticate")` |
| AI guesses at what calls what | Resolved dependency edges from tree-sitter |
| Context window fills with source code | File path + line range only |
| New conversation = cold start | Graph persists across sessions |

---

## Features

- **Dependency graph** — resolved call, import, inheritance, and usage edges via tree-sitter
- **Change impact** — find every caller of a function up to 3 hops away before you touch it
- **Dead code detection** — entities with zero inbound edges that aren't entrypoints
- **Architecture diagrams** — Mermaid graphs at module, class, or function scope
- **FastAPI route map** — routes → handlers → callees in one call
- **Task board** — Kanban tasks linked to code entities, queryable by AI
- **Document store** — ADRs, notes, and architecture overviews with full-text search
- **Token savings dashboard** — tracks how much context each tool call avoided reading
- **Web UI** — interactive graph, entity explorer, and task board at `localhost:7842`

Supports **Python** (FastAPI and general) and **C# (.NET)** out of the box.

---

## Installation

**Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/).**

```bash
# Install and register with Claude Code in one step
claude mcp add codemind -- uvx repo-codemind
```

That's it. `uvx` fetches and caches the package; no manual virtualenv or clone needed.

<details>
<summary>Install from source (for contributors)</summary>

```bash
git clone https://github.com/akshay-muglikar/codemind.git
cd codemind
uv sync
claude mcp add codemind -- uv run codemind
```

</details>

---

## Quick Start

**1. Index a repository**

In any Claude conversation with a codebase open:

```
index_repo("/path/to/your/project")
```

This walks the repo, parses every Python or C# file with tree-sitter, resolves dependencies, and writes everything to `.codemind/codemind.db` inside your project. Takes ~5 seconds for a 10k-line repo.

**2. Add the one-liner to CLAUDE.md**

```markdown
# Context via CodeMind MCP
Call `get_project_overview("/abs/path/to/project")` before reading any files.
```

From now on, every new conversation starts with a structured handoff instead of a file crawl.

**3. Open the dashboard (optional)**

```bash
codemind serve   # MCP stdio + web UI on http://localhost:7842
```

---

## Tool Reference

### Indexing

| Tool | When to use |
|---|---|
| `index_repo(repo_path)` | First index, or full refresh after many changes |
| `reindex_file(repo_path, file_path)` | After editing a single file (fast, <1s) |

### Dependency Analysis

| Tool | Returns |
|---|---|
| `get_callers(repo_path, qname, depth=1)` | Who calls this function/method |
| `get_callees(repo_path, qname, depth=1)` | What this function/method calls |
| `get_change_impact(repo_path, files[])` | Callers grouped by depth 1–3, capped at 50 |
| `get_dependency_path(repo_path, from, to)` | Shortest dependency path between two entities |
| `get_file_dependencies(repo_path, file)` | All imports for a file |
| `find_dead_code(repo_path)` | Entities with no callers that aren't entrypoints |

### Entity Lookup

| Tool | Returns |
|---|---|
| `find_entity(repo_path, query)` | Top matches by name (fuzzy) |
| `get_entity(repo_path, qualified_name)` | Full detail: loc, fan_in, fan_out, complexity, churn |
| `list_entities(repo_path, kind?, file_path?)` | Filtered entity list |

### Architecture

| Tool | Returns |
|---|---|
| `get_project_overview(repo_path)` | Saved overview document — **call this first** |
| `get_repo_structure(repo_path)` | Module/package tree with entity counts |
| `get_architecture_diagram(repo_path, scope)` | Mermaid `graph TD` at module, class, or function scope |
| `get_entity_diagram(repo_path, qname, depth=2)` | Mermaid subgraph around one entity |
| `get_route_map(repo_path)` | FastAPI routes → handlers → callees |

### Documents & Tasks

| Tool | Returns |
|---|---|
| `save_document(repo_path, kind, title, body)` | Save an ADR, note, or instruction |
| `search_documents(repo_path, query)` | Full-text search across all documents |
| `create_task(repo_path, title, ...)` | Task linked to code entities |
| `list_tasks(repo_path, status?, priority?)` | Filtered task list |
| `suggest_next_task(repo_path)` | Highest-priority task ranked by priority → fan_in → churn |

---

## How It Works

```
Your repo
   │
   ▼
tree-sitter parser          ← resolves entities and dependencies per file
   │
   ▼
SQLite graph (.codemind/)   ← entities, edges, documents, tasks
   │              │
   ▼              ▼
MCP stdio      FastAPI HTTP
(Claude/        (browser
 Copilot)        dashboard)
```

- **Parsing** uses tree-sitter grammars — no Python import execution, no reflection
- **Dependencies** are resolved to entity IDs where possible; unresolved edges are kept but flagged
- **Staleness** is checked on every query via `file_mtime`; changed files reindex inline
- **Storage** is a single SQLite file per repo at `<repo>/.codemind/codemind.db` — nothing leaves your machine

---

## Configuration

Create `.codemind/config.toml` in your repo to customize indexing:

```toml
[index]
ignore = ["migrations/**", "**/*.generated.py", "vendor/**"]
language = "python"   # force language if auto-detection is wrong
```

Environment variables:

| Variable | Default | Description |
|---|---|---|
| `LOG_FORMAT` | `pretty` | `pretty` for dev, `json` for prod |
| `CODEMIND_PORT` | `7842` | Port for the web dashboard |

---

## Development

```bash
git clone https://github.com/akshay-muglikar/codemind.git
cd codemind
uv sync
uv run pytest          # full test suite
uv run ruff check .    # lint
uv run mypy src        # type check
```

Tests use a minimal fixture FastAPI app (`tests/fixtures/python_fastapi/`) and a minimal C# solution (`tests/fixtures/dotnet/`) — no real repos required.

---

## Roadmap

- [ ] Publish to PyPI (`uvx repo-codemind`)
- [ ] TypeScript / JavaScript parser
- [ ] Go parser
- [ ] GitHub Actions integration (post impact analysis as PR comment)
- [ ] VS Code extension
- [ ] Embedding / vector search as an opt-in complement

---

## License

Copyright (c) 2026 Akshay Muglikar. All rights reserved.

This software is proprietary and may not be copied, modified, distributed, or used without explicit written permission from the author.
