Skip to main content

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 deduplication
  • cg_symbols — every class, function, method, import with location + summary
  • cg_edges — relationships: imports, calls, inherits, references, registers, handles_signal

Indexing Strategy

  1. Walk files via git ls-files (falls back to os.walk)
  2. SHA-256 content hash skips unchanged files
  3. AST parsing extracts symbols and edges
  4. Plugins post-process symbols (e.g., Django re-tags class → model)
  5. 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)

Source distribution for codegraphy 2.0.0
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)

Table of built distributions (wheels) for codegraphy 2.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page