Skip to main content

CodeGraphy Lite 🌐

PyPI License: MIT Python 3.9+ MCP Spec

🚀 Try the Live Interactive Playground in your browser: codegraphy.software/#playground (No install required — runs 100% locally in web assembly)

CodeGraphy Lite is the standalone open-source distribution of CodeGraphy. It provides an interactive visual architecture canvas, living dependency graphs, and Model Context Protocol (MCP) server for Python and modern software codebases.

Built for developers and AI agents (Claude Code, Cursor, Windsurf, Cline), CodeGraphy Lite turns messy codebases into an intuitive, navigable 2D architectural map while slashing LLM context input tokens by -75.5%.


🚀 Quickstart

1. Installation

Install via pip:

pip install codegraphy-lite

Or install from source for development:

git clone https://github.com/codegraphy-dev/codegraphy-lite.git
cd codegraphy-lite
pip install -e .

2. Launch the Web UI

Run codegraphy-lite pointing to any project directory:

# Scan and visualize the current directory
codegraphy-lite

# Or specify a directory and custom port
codegraphy-lite /path/to/my-project --port 8000

The server automatically scans the project (up to 35 files) and opens http://127.0.0.1:8000 in your default web browser.


🤖 Model Context Protocol (MCP) Setup

CodeGraphy Lite includes a built-in MCP server that communicates over STDIO via codegraphy-mcp (JSON-RPC 2.0 / MCP 2024-11-05 standard).

Available MCP Tools

  1. list_workspace_topics: Lists all architectural topics, status, lane, file counts, and descriptions.
  2. get_topic_context: Fetches topic details, 1-hop connected dependencies, and AST-extracted class/function signatures.
  3. get_architecture_summary: Returns project architecture metrics, dependency statistics, and status distribution.

Configuration for Cursor

In Cursor settings (Cursor Settings -> Features -> MCP -> Add new MCP server):

  • Name: codegraphy
  • Type: command
  • Command: codegraphy-mcp

Or add directly to your project's .cursor/mcp.json or global configuration:

{
  "mcpServers": {
    "codegraphy": {
      "command": "codegraphy-mcp"
    }
  }
}

Configuration for Claude Code

Add the following to your Claude Code configuration (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "codegraphy": {
      "command": "codegraphy-mcp",
      "env": {
        "CODEGRAPHY_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

📊 Empirical Token Benchmark (-75.5% Context Savings)

In an isolated comparative benchmark across 6 real-world closed bugfixes in major Python repositories (encode/httpx, tiangolo/typer, Textualize/rich), CodeGraphy Lite reduced agent context input tokens by 75.5% (4.08x savings) compared to standard keyword grep and whole-file reading:

Mode Input Tokens (cl100k_base) Context Reduction Acceptance Pass Rate Tokens / Solved Task
Baseline (Grep + Whole Files) 144,686 0.0% (ref) 100.0% (6/6) 24,114
CodeGraphy Lite MCP 35,457 -75.5% (4.1x savings) 100.0% (6/6) 5,909
CodeGraphy Pro (Desktop Ref)* 64,348 -55.5% (2.25x savings) 100.0% (6/6) 10,724

*CodeGraphy Pro numbers reflect deep symbol graph index lookups and blast-radius impact analysis.

👉 Read the full benchmark methodology, task breakdowns, and honest limitations analysis in benchmarks/BENCHMARK.md.


⚖️ Lite vs Pro Comparison

CodeGraphy Lite is free and open-source (MIT). For larger codebases, polyglot repositories, and architectural drift protection, check out CodeGraphy Pro:

Capability CodeGraphy Lite (Free / OSS) CodeGraphy Pro ($19 Lifetime)
Pricing & License Free (MIT License) $19 Lifetime License
Visual Architecture Canvas ✅ Interactive 2D Canvas ✅ Interactive 2D Canvas
Workspace Export / Import ✅ Human-readable .cg.md ✅ Human-readable .cg.md
Project File Limit 35 files (Ideal for packages & services) Unlimited (Enterprise mono-repos)
Supported Languages Python AST (ast.parse()) Polyglot (Python, TS, JS, Go, Rust, C#, Java)
MCP Server Tools 3 Core Tools 11 Industrial Intelligence Tools
Blast Radius & Impact Analysis ❌ None ✅ Direct & Transitive Blast Radius Scoring
Symbol Indexer Top-level signatures ✅ Project-wide FQN symbol & reference index
Architecture Linter & Drift ❌ None ✅ Tarjan cycle detection & layer boundary checks
Git Architecture Diff ❌ None ✅ Visual PR & Branch architecture diff overlay

👉 Compare all features or get a license at codegraphy.software/#compare.


✨ Features

  • 🗺️ Unified Architecture Graph: Interactive React Flow graph displaying modules, services, and dependency edges with real-time drag-and-drop layout.
  • 🗂️ Split Layers & Lanes: Group architectural topics by workflow stage (Planning, Development, Testing, Done).
  • 🔍 Semantic Zoom: Multi-level zoom with automatic Level-of-Detail (LOD)—zoom in to inspect function signatures and attached files, zoom out for high-level module topology.
  • 📝 Portable .cg.md Workspaces: Human-readable Markdown workspace specification format with two-way import/export.
  • ⚡ Lightweight AST Scanner: Fast project scanner using Python's standard library ast.parse() and regex import matching (scans up to 35 files).
  • 🤖 STDIO MCP Server (codegraphy-mcp): Exposes 3 essential architectural intelligence tools to AI assistants via JSON-RPC 2.0.
  • 🔒 100% Local-First & Private: No cloud telemetry, no code uploads. Your codebase never leaves your machine.

🛠️ CLI Reference

usage: codegraphy-lite [-h] [--port PORT] [--host HOST] [--no-browser] [--scan] [-v] [path]

CodeGraphy Lite — Standalone Open-Source Visual Architecture Graph & MCP Server

positional arguments:
  path                  Target project directory to visualize (default: current directory)

options:
  -h, --help            Show this help message and exit
  --port PORT           HTTP server port (default: 8000)
  --host HOST           HTTP server bind host (default: 127.0.0.1)
  --no-browser          Do not automatically launch the browser
  --scan                Force automatic project directory scan on startup (up to 35 files)
  -v, --version         Show program's version number and exit

📁 Repository Structure

codegraphy-lite/
├── LICENSE                 # MIT License
├── README.md               # Documentation
├── pyproject.toml          # PEP 517/621 package metadata & entrypoints
├── MANIFEST.in             # Manifest for sdist packaging
├── .gitignore              # Git ignore rules
├── benchmarks/             # Reproducible architecture benchmarks
│   ├── BENCHMARK.md        # Comprehensive 6-bug benchmark report
│   ├── run_benchmark.py    # Standalone benchmark runner (no machine-specific paths)
│   └── benchmark_results.json
├── codegraphy_lite/        # Core Python package
│   ├── __init__.py         # Version definition (1.0.1)
│   ├── cli.py              # `codegraphy-lite` CLI entrypoint
│   ├── mcp.py              # `codegraphy-mcp` STDIO JSON-RPC 2.0 server
│   ├── models.py           # Pydantic models for graph & workspace
│   ├── scanner.py          # Safe stdlib AST scanner (max 35 files)
│   ├── server.py           # FastAPI REST & WebSocket server
│   ├── storage.py          # Local persistence & .cg.md codec
│   └── web/                # Bundled visual UI assets
└── tests/                  # Unit test suite
    ├── test_scanner.py
    ├── test_mcp.py
    └── test_server.py

🧪 Running Tests

pip install -e ".[test]"
pytest tests/ -v

📄 License

CodeGraphy Lite is licensed under the MIT License.

Metadata

Release files for codegraphy-lite 1.0.1

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-lite 1.0.1
File Size Uploaded Provenance Actions
codegraphy_lite-1.0.1.tar.gz 592.7 kB Without provenance Details for codegraphy_lite-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codegraphy-lite 1.0.1
File Interpreter ABI Platform Actions
codegraphy_lite-1.0.1-py3-none-any.whl Python 3 none any Details for codegraphy_lite-1.0.1-py3-none-any.whl

Total release size: 1.2 MB

Release files / codegraphy_lite-1.0.1.tar.gz

Download URL codegraphy_lite-1.0.1.tar.gz
Size 592.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ecbfabf90988c488b2d206e3d9550f5378d2bfeb311d6ad8353f0796e585ab9a
BLAKE2b-256 checksum
How to use checksums
1ae5130dc2841c7369c9ee2ab1547f66497b915ee74d247a6ddb998fe323baaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Release files / codegraphy_lite-1.0.1-py3-none-any.whl

Download URL codegraphy_lite-1.0.1-py3-none-any.whl
Size 594.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
caeb484e731f87147e0b2041625cc164b111088294c7250d77e073470e5d4ac6
BLAKE2b-256 checksum
How to use checksums
6c1d43548d4031880a31a99cc0794a093bcbb3524c14a3879ef552c5c1b07d58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Security for codegraphy-lite 1.0.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

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