codegraphy
Standalone Python package that parses a codebase into a knowledge graph (PostgreSQL or SQLite) and exposes it as an MCP server for Claude Code. Claude calls graph tools instead of Read + Bash(grep) — cuts exploration token cost by 5–10×.
PyPI: https://pypi.org/project/codegraphy/
Python: 3.10+
License: MIT
Why
Claude exploring an unfamiliar codebase today:
| Task | Without codegraphy | With codegraphy |
|---|---|---|
Find where Something is defined |
Read 10 files (~15k tokens) | search_symbol("Something") (~200 tokens) |
| Understand a file's structure | Read full file (~3k tokens) | get_file_summary("views.py") (~300 tokens) |
Installation
# SQLite-only install (default, zero config):
pip install codegraphy
# For PostgreSQL support:
pip install codegraphy[postgres]
# For JS/TS parsing (planned):
pip install codegraphy[js]
# Everything:
pip install codegraphy[all]
The base PyPI package keeps SQLite support in the standard library path, so PostgreSQL stays opt-in.
PostgreSQL
Install PostgreSQL support:
pip install 'codegraphy[postgres]'
Initialize with a PostgreSQL URL:
codegraphy init --db postgresql://USER:PASSWORD@HOST:PORT/DBNAME
Example:
codegraphy init --db postgresql://postgres:postgres@localhost:5432/codegraphy
Or set DATABASE_URL once and reuse it:
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/codegraphy
codegraphy init
codegraphy index .
codegraphy serve
Quickstart
# 1. Initialize the database (SQLite by default)
codegraphy init
# 2. Index your project
codegraphy index .
# 3. Start the MCP server (stdio, for Claude Code)
codegraphy serve
That's it. Claude can now query your codebase graph instead of reading files.
CLI Reference
codegraphy init [--db URL] # Create tables (SQLite default, or pass Postgres URL)
codegraphy index PATH [--exclude] # Full index of a directory
codegraphy update # Incremental re-index via git diff
codegraphy serve # Start MCP server over stdio
codegraphy search NAME # Search symbols (debug, not MCP)
codegraphy usages QUALIFIED_NAME # Find usages (debug, not MCP)
codegraphy stats # Show graph statistics
codegraphy index and codegraphy update show progress while they run, then print a summary with files scanned, files indexed, and elapsed time. codegraphy serve also shows startup progress and then reports when the MCP server is ready and waiting for a stdio client.
MCP Tools
When running as an MCP server, codegraphy exposes these tools to Claude:
| Tool | Description |
|---|---|
search_symbol(name, kind?, limit?, fallback_grep?) |
Find symbols by name — exact, then substring, then grep fallback |
get_file_summary(file_path) |
Classes, functions, imports in a file without reading it |
find_usages(qualified_name, limit?, fallback_grep?) |
Who imports/calls/references this symbol |
get_context(file_path, line, radius?) |
Read N lines around a line number |
path_between(from_qualified, to_qualified, max_depth?) |
BFS shortest path between two symbols |
grep_search(pattern, include?, exclude?, limit?) |
Direct grep — bypass the graph |
graph_stats() |
File/symbol/edge counts, backend type |
what_touches_model(model_name) |
Django: views, admin, signals referencing a model |
search_semantic(query, limit?) |
pgvector semantic search (Postgres only, planned) |
All tools return a source field ("graph" or "grep") so Claude can gauge confidence.
Configuration
Priority: CLI flag → environment variable → codegraphy.toml → defaults.
Environment Variables
DATABASE_URL=sqlite:///codegraphy.db # or postgresql://localhost/codegraphy
CODEGRAPHY_ROOT=. # project root for grep fallback
CODEGRAPHY_PLUGINS=codegraphy.plugins.django
Config File (optional)
# codegraphy.toml (place at project root)
database_url = "postgresql://localhost/codegraphy"
root = "."
exclude = ["migrations", "node_modules", ".venv", "__pycache__"]
plugins = ["codegraphy.plugins.django"]
Claude Code Integration
Register the MCP server
// .claude/settings.json
{
"mcpServers": {
"codegraphy": {
"command": "codegraphy",
"args": ["serve"],
"env": {
"DATABASE_URL": "sqlite:///codegraphy.db"
}
}
}
}
Auto-update on session end (optional)
// .claude/settings.json
{
"hooks": {
"Stop": [{
"type": "command",
"command": "codegraphy update"
}]
}
}
Architecture
codegraphy/
├── cli.py # Click CLI entry points
├── config.py # DATABASE_URL, CODEGRAPHY_ROOT, plugin list
├── db/
│ ├── schema.py # CREATE TABLE statements (PG + SQLite)
│ └── store.py # upsert_symbol, upsert_edge, query helpers
├── indexer/
│ ├── base.py # BaseIndexer ABC, Symbol/Edge dataclasses
│ ├── python.py # ast-based Python indexer
│ └── walker.py # Filesystem walk + git-diff incremental
├── mcp/
│ └── server.py # FastMCP server + all tool definitions
├── plugins/
│ ├── base.py # BasePlugin ABC
│ └── django.py # Django-aware: models, views, signals
└── session/ # (planned) git-diff hook + memory write
Database Schema
Three tables power the graph:
cg_files— indexed files with git hash for deduplicationcg_symbols— every class, function, method, import with location + summarycg_edges— relationships:imports,calls,inherits,references,registers,handles_signal
Indexing Strategy
- Walk files via
git ls-files(falls back toos.walk) - SHA-256 content hash skips unchanged files
- AST parsing extracts symbols and edges
- Plugins post-process symbols (e.g., Django re-tags
class→model) - Upsert into database with cascade delete for clean re-indexing
Plugin System
Plugins implement two hooks:
class BasePlugin:
def on_symbol(self, symbol: Symbol) -> Symbol:
"""Mutate or re-tag a symbol after parsing."""
return symbol
def extra_edges(self, symbols: list[Symbol]) -> list[Edge]:
"""Derive additional edges from the symbol list."""
return []
Built-in: Django Plugin
Detects Django patterns by file naming convention:
- Classes in
models.py→kind = "model" - Classes/functions in
views.py→kind = "view"
Enable via environment variable:
CODEGRAPHY_PLUGINS=codegraphy.plugins.django
Current Status
| Milestone | Status |
|---|---|
M1 — Schema + Python indexer + codegraphy index |
✅ Complete |
M2 — search_symbol + get_file_summary + MCP serve |
✅ Complete |
M3 — find_usages + path_between + get_context + grep fallback |
✅ Complete |
M4 — codegraphy update (incremental) |
✅ Complete |
| M5 — Django plugin | 🔶 Partial (symbol re-tagging, no admin/signal edges) |
| M6 — Semantic search (pgvector) | ⬜ Stub only |
| M7 — JS/TS indexer (tree-sitter) | ⬜ Planned |
| M8 — HTML/Template indexer | ⬜ Planned |
M9 — grep_search tool + cross-language edges |
🔶 grep_search done, cross-lang edges planned |
Development
# Clone and install in editable mode
git clone <repo-url> && cd codegraphy
python -m venv .venv && source .venv/bin/activate
pip install -e .
# Initialize local DB and index this project
codegraphy init
codegraphy index .
# Check stats
codegraphy stats
Publishing
codegraphy is configured to build as a standard PyPI distribution from pyproject.toml.
For PyPI trusted publishing, use publish.yml as the workflow name. The workflow file lives at .github/workflows/publish.yml.
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
What It Is NOT
- Not a code execution sandbox
- Not a test runner or linter
- Not a replacement for LSP/IDE features
- Not AI-generated summaries by default (uses docstrings; AI summaries are opt-in future)
Metadata
Release files for codegraphy 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codegraphy-2.0.0.tar.gz | 20.0 kB | With provenance | Details for codegraphy-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codegraphy-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for codegraphy-2.0.0-py3-none-any.whl |
Total release size: 40.1 kB
Release files / codegraphy-2.0.0.tar.gz
| Download URL | codegraphy-2.0.0.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
060fafc2011750636f5d4fb2bf53bc149329236e0f1f77252f1b950108b4e841
|
|
BLAKE2b-256 checksum How to use checksums |
7cbe779d075d87e0d6b4387dc5dd812c094da1b265061fdaa01ad0fd863d9c4f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 19, 2026.
Transparency logRelease files / codegraphy-2.0.0-py3-none-any.whl
| Download URL | codegraphy-2.0.0-py3-none-any.whl |
|---|---|
| Size | 20.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63d1b127bad881c399d56e79ae4e99ea081c6ef4d5e8f890461f08cbf81e3f16
|
|
BLAKE2b-256 checksum How to use checksums |
dbe81420d2c6fab3fd94eb956e445fce1927d69da327db4e2d587704a81c5744
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 19, 2026.
Transparency logSecurity for codegraphy 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for codegraphy-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.