agentgraph

# agentgraph [](https://github.com/Sup4ikX/agentgraph/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](LICENSE) [](https://docs.astral.sh/ruff/) A small, fast, language-aware code-graph tool. Parse a repository, build a directed graph of files → classes → functions → methods, edges for calls, imports, inheritance, and implementations, then query it from the CLI or from the Model Context Protocol (MCP) server inside an IDE/agent. 100% local, zero cloud, no telemetry, no network calls at runtime. ## Why agentgraph? | Tool | Multi-lang | MCP server | Local | Speed | Persistent cache | Impact analysis | Cycle detection | | -------------------------- | ---------- | ---------- | ----- | ----- | ---------------- | --------------- | --------------- | | **agentgraph** | 5 langs | ✅ 14 tools| ✅ | Fast | ✅ | ✅ | ✅ | | serena (LSP-based) | 10+ | ✅ | ✅ | Slow | ❌ | partial | ❌ | | pydeps | Python only| ❌ | ✅ | Fast | ❌ | ❌ | ❌ | | code-graph (Node) | JS/TS only | ❌ | ✅ | Fast | ❌ | ❌ | ❌ | | aider / Cursor / Cody | chat-based | n/a | ❌ | n/a | n/a | n/a | n/a | **What agentgraph gives you that the others don't:** - A single JSON graph file you can inspect, version-control, diff, and query offline — the whole pipeline is deterministic and reproducible. - 14 MCP tools, not just "search the codebase": full call-graph navigation, transitive impact analysis, structural cycle detection in imports, dead-code detection. - A persistent on-disk parse cache that makes repeat scans of unchanged repositories ~10× faster (the common case in a dev loop). - Tree-sitter under the hood — tolerant of syntax errors, fast on big codebases, no JVM, no Node, just one pure-Python dependency. ## Features - **Multi-language parsing** via [tree-sitter](https://tree-sitter.github.io/): **Python**, **JavaScript**, **TypeScript**, **Rust**, **Go**. - **Edges**: `defines`, `contains`, `calls`, `imports`, `inherits`, `implements`, `references`. - **Query API**: substring or `/regex/` matching, callers/callees, ancestors, imports, class hierarchy, implementations, dependents. - **Advanced traversals**: transitive `impact_analysis` (BFS, capped at `max_depth`), `circular_dependencies` (Tarjan SCC) and `find_unused` (orphan detection by kind). - **Renderers**: pretty text, JSON, Graphviz DOT. - **Persistent cache**: per-file `(mtime, size)` fingerprint stored under `<root>/.agentgraph/cache.json`; 10-100× speedup on repeat scans. - **CLI**: `agentgraph scan`, `stats`, `find`, `callers`, `callees`, `imports`, `tree`, `dot`, `mcp`. - **MCP server**: 14 tools exposing the query API to any MCP-aware client (Claude Desktop, Cursor, Zed, Cline, etc.). ## Install ```bash pip install -e ".[dev]" ``` Requires Python 3.11+. ## Quickstart ```bash # 1. Build a graph for a repository and dump it to JSON agentgraph scan ./myrepo -o myrepo.json # 2. Inspect summary statistics agentgraph stats myrepo.json # 3. Find every function/method/class matching a regex agentgraph find myrepo.json "make_.*" # 4. Who calls `greet`? agentgraph callers myrepo.json greet # 5. Render the imports of a file as a DOT graph agentgraph imports myrepo.json myrepo/app.py # 6. Print a nested containment tree of the repo agentgraph tree myrepo.json # 7. Render the entire graph as Graphviz DOT agentgraph dot myrepo.json > graph.dot && dot -Tsvg graph.dot > graph.svg ``` ## CLI ``` agentgraph scan PATH [-o OUT] [--ignore NAME]... [--follow-symlinks] [--max-file-size BYTES] [--cache-dir DIR | ""] [--json] agentgraph stats GRAPH_FILE [--json] agentgraph find GRAPH_FILE [--name PAT] [--regex PAT] [--kind KIND]... [--language LANG] [--file PATH]... [--limit N] [--json] agentgraph callers GRAPH_FILE TARGET [--kind KIND] [--json] agentgraph callees GRAPH_FILE TARGET [--kind KIND] [--json] agentgraph imports GRAPH_FILE [FILE] [--json] agentgraph tree GRAPH_FILE [FILE] [--json] agentgraph dot GRAPH_FILE [--node-kind KIND]... [--edge-kind KIND]... [-o OUT] agentgraph mcp [--root DIR] [--ignore NAME]... ``` Every subcommand supports `--json` for machine-readable output. ## MCP server ```bash agentgraph mcp --root ./myrepo ``` Configure your MCP client (Claude Desktop, Cursor, ...) to spawn `agentgraph mcp --root /path/to/project` and the following tools become available: | Tool | Purpose | | --------------------- | ---------------------------------------------------------- | | `scan` | (re)parse a directory and refresh the in-memory graph | | `find_nodes` | search by name (substring or `/regex/`), kind, language | | `callers_of` | list every incoming edge of the given kind for a target | | `callees_of` | list every outgoing edge of the given kind from a source | | `imports_of` | list outgoing `imports` edges of a file | | `dependents_of` | list incoming `imports` edges of a file or module | | `class_hierarchy` | base classes and subclasses of a class/interface/trait | | `stats` | graph summary statistics | | `languages` | languages present in the graph | | `files` | every file in the graph | | `tree` | containment tree of a file (or every file) | | `impact_analysis` | transitive callers/callees of a node up to `max_depth` | | `circular_dependencies` | cycles of project-internal `imports` between files | | `find_unused` | nodes with no incoming reference edge (dead-code hints) | ## Python API ```python from agentgraph import scan, QueryEngine result = scan("./myrepo") # full graph + stats + errors print(result.stats()) # {nodes, edges, files, ...} print(result.duration_seconds) # wall-clock scan time engine = QueryEngine(result.graph) for hit in engine.search("make_.*", kind="function", limit=20): print(hit.id, hit.location) print(engine.callers_of(hit)) # [CodeEdge, ...] print(engine.impact_analysis(hit, direction="callers", max_depth=4)) print(engine.circular_dependencies()) # list of cycles print(engine.find_unused(kind="function")) ``` ## Development ```bash git clone https://github.com/Sup4ikX/agentgraph cd agentgraph pip install -e ".[dev]" # Run the test suite pytest -q # Lint (ruff) ruff check src tests # Type-check mypy src # Build a wheel + sdist python -m build ``` Pre-commit hooks (optional but recommended): ```bash pip install pre-commit pre-commit install ``` ## License [MIT](LICENSE).