Graphlens

Documentation · Repository · Issues

Architecture

Repository → Language Adapter → GraphLens (IR) → Graph Backend

Adapters are pure data producers — they never write to any backend. The graph is the only output.

Why graph IR?

• Language-agnostic — one shared model for Python, TypeScript, Go, Rust, PHP, …
• Plugin-based adapters — each language is a separate package, registered via Python entry points
• Tree-sitter powered — all adapters use tree-sitter for CST parsing and exact span positions, combined with type-aware resolution (ty for Python, TypeScript Compiler API for TypeScript, gopls for Go, rust-analyzer for Rust, Intelephense for PHP)
• Cross-language aware — adapters emit language-agnostic BOUNDARY ports (HTTP, queues, gRPC, Temporal); graphlens-link connects a consumer in one language to a provider in another
• Monorepo aware — can_handle() and find_*_roots() handle multi-language repos correctly
• Deterministic node IDs — SHA-256 hash of project::kind::qualified_name → stable across re-scans

Benchmarks

Analysis throughput on large real-world projects, refreshed automatically on every release — one cold run per project inside the published Docker image (so the numbers reflect exactly the toolchain users get). See benchmarks/ to reproduce locally or add a project.

Last run: 2026-07-09 15:58 UTC · image latest · runner Linux x86_64 · single cold run, indicative only.

Peak RSS measured via cgroup.v2 (whole process tree, incl. LSP resolver subprocesses). KLOC/s = analysed thousands-of-lines per second. Generated by benchmarks/run_benchmarks.py.

Documentation

Full product documentation lives at https://Neko1313.github.io/graphlens/ (built with Docusaurus from website/):

• Getting Started — install, quick start, core concepts
• Guides — library API, CLI, querying, visualization, Neo4j, cross-language
• CI Integration — strict mode, GitHub Actions, Docker, local hooks
• Adapters — Python, TypeScript, Go, Rust, PHP, and writing your own
• Graph Model — nodes, relations, boundaries, serialization
• API Reference — exact signatures

To run the docs locally: cd website && pnpm install && pnpm start.

Installation

# Core library only (models, contracts, registry)
pip install graphlens

# Core + Python adapter
pip install "graphlens[python]"

# Core + TypeScript adapter
pip install "graphlens[typescript]"

# Core + Go / Rust / PHP adapters
pip install "graphlens[go]"
pip install "graphlens[rust]"
pip install "graphlens[php]"

# CLI (graphlens analyze / visualize / query / neo4j)
pip install "graphlens-cli[python]"          # with Python adapter
pip install "graphlens-cli[all]"             # Python + TS + Go + Rust + PHP + Neo4j

With uv:

uv add graphlens
uv add "graphlens[python]"
uv add "graphlens[typescript]"
uv add "graphlens-cli[all]"

Docker (all adapters + toolchains pre-installed)

For CI, the published image bundles the CLI with every adapter and the toolchains their resolvers drive (ty, Node, Go + gopls, Rust + rust-analyzer, PHP + Intelephense) — no local setup required, and the supported way to get the Go, Rust and PHP adapters (which are not published to PyPI). Mount your project at /workspace:

docker run --rm -v "$PWD:/workspace" ghcr.io/neko1313/graphlens \
    analyze /workspace --output /workspace/graph.json

The image is published to the GitHub Container Registry on each release (:latest plus :X.Y.Z / :X.Y version tags).

Quick start

from pathlib import Path
from graphlens import adapter_registry

# Load and instantiate the Python adapter
adapter = adapter_registry.load("python")()

# Analyze a project — returns a GraphLens
graph = adapter.analyze(Path("./my-project"))

print(f"Nodes:     {len(graph.nodes)}")
print(f"Relations: {len(graph.relations)}")

# Inspect nodes by kind
from graphlens import NodeKind

modules = [n for n in graph.nodes.values() if n.kind == NodeKind.MODULE]
classes = [n for n in graph.nodes.values() if n.kind == NodeKind.CLASS]

# Check the resolver actually ran (don't trust a silently degraded graph)
from graphlens import RESOLVER_STATUS_KEY
assert graph.metadata[RESOLVER_STATUS_KEY] == "ok"

# Query the graph (indexed lookups, no manual scanning)
fn = next(n for n in graph.nodes.values() if n.name == "my_function")
callers = graph.callers(fn.id)          # who calls it
callees = graph.callees(fn.id)          # what it calls
near = graph.neighbors(fn.id, depth=2)  # 2-hop neighbourhood

# Serialize for pipelines / agents (round-trippable JSON), then reload
text = graph.to_json(indent=2)
graph2 = type(graph).from_json(text)

# Diff two scans (e.g. before/after a change)
diff = old_graph.diff(graph)
print(diff.added_nodes, diff.removed_relations, diff.is_empty)

CLI (graphlens-cli)

Install graphlens-cli to get the graphlens entry point:

# Print node/relation statistics
graphlens analyze <project_root>
graphlens analyze ~/myrepo --lang python,typescript,go,rust

# Serialize the graph to JSON (CI indexing step); --strict fails on a
# degraded resolver so a pipeline never feeds agents an incomplete graph
graphlens analyze ~/myrepo --output graph.json
graphlens analyze ~/myrepo --format json
graphlens analyze ~/myrepo --strict

# Query a saved graph (callers | callees | references | neighbors)
graphlens query my_function --graph graph.json --op callers
graphlens query MyClass.method --graph graph.json --op neighbors --depth 2

# Interactive HTML graph viewer (opens in browser)
graphlens visualize <project_root>
graphlens visualize ~/myrepo --lang python --show-external --max-nodes 500
graphlens visualize . --output graph.html --no-open

# Export to Neo4j
graphlens neo4j <project_root> --uri bolt://localhost:7687 --user neo4j --password secret
graphlens neo4j . --wipe --batch-size 200

Serving a graph to agents (MCP)

graphlens is only an analysis engine and ships no MCP server of its own. To serve the graph to coding agents (Claude Code, Cursor, …) over the Model Context Protocol, use graphlens-mcp — a separate, MIT-licensed server built on top of this engine (docs):

uv tool install graphlens-mcp
cd your-project && graphlens-mcp init

It is also a worked example of how to consume the engine: driving the adapter registry, persisting and refreshing the graph, and exposing it to a client.

visualize — interactive HTML graph viewer

Produces a self-contained HTML file powered by vis.js and opens it in the browser.

Click behaviour — click any node to see its info panel. For FUNCTION and METHOD nodes the panel has a "Show callers" button that switches the graph into focus mode: only the selected node and every node that calls or references it are shown, with the caller list in the sidebar. Click empty space or ← Back to return to the full graph.

neo4j — export to Neo4j

Uses UNWIND … MERGE Cypher (no APOC required). Every node gets a :Code label plus a kind-specific label (:Function, :ExternalSymbol, …). Relations are created grouped by type. Install the optional neo4j extra:

pip install "graphlens-cli[neo4j]"

Graph model

Node kinds

Relation kinds

Cross-language boundaries

Adapters emit BOUNDARY ports for the interfaces a service exposes or consumes — HTTP/REST routes and clients, message-queue topics, gRPC methods, and Temporal activities. Each port has a language-agnostic id (make_boundary_id(mechanism, key)), so a Python FastAPI route and a TypeScript fetch call to the same path collapse onto one BOUNDARY node when their graphs are merged. The graphlens-link package then pairs CONSUMES with EXPOSES into COMMUNICATES_WITH edges:

from graphlens_link import link_graph

merged = python_graph.merge(ts_graph, allow_shared=True)
result = link_graph(merged)          # adds COMMUNICATES_WITH edges

See examples/demo_cross_language.py for a Python-server ↔ TypeScript-client walkthrough.

Adapter plugin system

Language adapters register themselves via Python entry points — no changes to the core needed:

# packages/graphlens-python/pyproject.toml
[project.entry-points."graphlens.adapters"]
python = "graphlens_python:PythonAdapter"

The registry discovers installed adapters automatically at runtime:

from graphlens import adapter_registry

adapter_registry.available()          # ["python", ...]
adapter_cls = adapter_registry.load("python")
adapter = adapter_cls()

Adapters can also be registered manually (useful for testing):

adapter_registry.register("python", MyPythonAdapter)

Implementing an adapter

Subclass LanguageAdapter and implement four methods:

from pathlib import Path
from graphlens import GraphLens, LanguageAdapter

class MyLangAdapter(LanguageAdapter):
    def language(self) -> str:
        return "mylang"

    def file_extensions(self) -> set[str]:
        return {".ml", ".mli"}

    def can_handle(self, project_root: Path) -> bool:
        return (project_root / "dune-project").exists()

    def analyze(
        self, project_root: Path, files: list[Path] | None = None
    ) -> GraphLens:
        graph = GraphLens()
        files = files or self.collect_files(project_root)
        # ... parse and populate graph ...
        return graph

Register in pyproject.toml and the core registry finds it automatically.

Project structure

graphlens/                      ← uv workspace root (core library)
  src/graphlens/                ← models, contracts, registry, exceptions, utils
  packages/
    graphlens-python/           ← Python adapter (tree-sitter + ty)
    graphlens-typescript/       ← TypeScript adapter (tree-sitter + Compiler API)
    graphlens-go/               ← Go adapter (tree-sitter + gopls)
    graphlens-rust/             ← Rust adapter (tree-sitter + rust-analyzer)
    graphlens-php/              ← PHP adapter (tree-sitter + Intelephense)
    graphlens-link/             ← cross-language linker (COMMUNICATES_WITH)
    graphlens-cli/              ← CLI (typer): analyze, query, visualize, neo4j
  tests/                         ← core tests (100% coverage)
  examples/                      ← standalone usage examples

Development

Requires Python 3.13+, uv, task.

task install        # uv sync --all-groups
task lint           # ruff + ty + bandit for all packages
task tests          # all tests with coverage

Individual package tasks:

task core:lint           task core:test
task python:lint         task python:test
task typescript:lint     task typescript:test
task cli:lint            task cli:test

License

MIT