repo-codemind 1.0.0

Structured codebase intelligence for Claude and Copilot via MCP — dependency graphs, blast-radius analysis, and architecture diagrams for Python and C# repos.

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.

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

Install from source (for contributors)

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

---

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

# 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)

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:

[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

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.