Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codegraph show callers of validate_order"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Blast-radius enforcement for coding agents. codegraph builds an AST call/dependency graph of your repo (tree-sitter, 7 languages) and injects a symbol's callers into the agent's context at the moment it edits the file:
codegraph BLAST RADIUS - includes/checkout.php has 47 caller(s) across 12 file(s).
Audit these before changing signatures/behavior:
- process_order (includes/orders.php:81)
- Cart.finalize (includes/cart.php:210)
...Code graphs already exist. They answer questions, which assumes someone asks. An LLM mid-task has usually decided the edit is small and doesn't ask - then breaks callers it never opened. codegraph doesn't wait to be queried; a hook fires on every file edit and puts the dependency list in front of the model, unprompted. Works on any model, since reading a caller list requires no particular capability.
The hooks are warn-only and fail open. A warning never blocks an edit, and any failure in the hook path exits silently. The graph is regenerated from source incrementally, so it can't drift from the code.
Requirements: macOS or Linux, Python 3.10+. Claude Code for the hook integration; the MCP server itself works with any MCP client.
git clone https://github.com/Doublehead/codegraph
cd codegraph
./install.shThen restart Claude Code and run /codegraph-reindex inside a project to build its
graph. Verify with:
claude mcp get codegraph # should say: ConnectedThe installer copies the engine to ~/.local/lib/codegraph, creates a venv with
pinned dependencies, runs the full test suite to verify the install, copies the
hooks, and registers the MCP server and hooks in Claude Code's config. It's
idempotent, backs up every config file it touches, and never clobbers existing
servers or hooks. Details in INSTALL.md.
Per-project graph data lives in <project>/.codegraph/ - add that to the project's
.gitignore.
Using another MCP client: skip the hook parts and register the stdio server binary
directly - ~/.local/lib/codegraph/.venv/bin/codegraph.
Uninstall: install/uninstall.sh. Removes the server, hooks, and command
registration; leaves per-project .codegraph/ dirs alone.
Related MCP server: oxcode
Tool | Answers |
| Build/refresh the graph. Incremental by content hash; honours .gitignore. |
| Counts and resolution quality, by language and symbol kind. |
| Where is this symbol defined? |
| Reverse reachability - who breaks if this changes. |
| Forward reachability - what it depends on. |
| Direct callers and callees with call-site lines. |
| Impact set of a symbol or a whole file, grouped by file. |
| Shortest call path between two symbols. |
| Circular dependencies. Exact edges only, so a report is trustworthy. |
| Load-bearing symbols by call-site fan-in, distinct dependents, betweenness. |
| String-dispatch coupling: listeners, fire sites, entry points, unauthenticated surface. |
| Edge drift from uncommitted edits, including cross-file resolution flips. |
| Scope a vendor monorepo down to your code. No args = dry-run suggestion. |
symbol accepts Class.method to disambiguate. On a large unscoped repo, index
returns a scope suggestion and the server instructions direct the agent to apply it;
nobody hand-writes config.
A call resolves by its shape, derived from the receiver - never by name alone:
Call shape | Targets | Example |
bare | a free function; locals/params mask same-named globals |
|
| a method of the same class |
|
| a method of a parent class |
|
| that class's method |
|
|
|
|
|
|
|
| a free function in that module's file |
|
| same-named methods, low confidence |
|
Every edge carries a confidence tier:
exact - the call shape proves a single target. Trustworthy.
inferred - a single plausible target, receiver type unverified. Disclosed, never
silently exact.
ambiguous - multiple candidates, edges to all. A real caller is never dropped.
Calls with no in-repo target are recorded unresolved, not faked.
The bias is recall over precision: an uncertain edge is kept and labelled, never
dropped, because a missed caller is the failure this tool exists to prevent. Two
invariants hold throughout - no wrong exact edge, no dropped caller - and the
regression suite enforces both. Ruby mixins (include/extend/prepend) are part
of bare-call lookup; the js/ts/tsx dialects share one resolution namespace.
Most framework wiring never appears as a call. codegraph extracts it as a separate
evidence-gated hook edge tier:
WordPress: add_action/add_filter/do_action/apply_filters/register_rest_route.
hooks(entry_points=true) maps the ajax/REST attack surface with unauthenticated
endpoints flagged. All callback forms resolve; a collision resolves to nothing
rather than the wrong symbol.
Django signals: @receiver/.connect paired with .send/.send_robust. Evidence-
gated, so a socket's .connect/.send can't fabricate an edge.
Celery: @task/@shared_task paired with .delay/.apply_async.
Web routes: Flask/FastAPI decorators, Django path()/re_path(), as entry points.
React: JSX <Component/> usage becomes a caller edge; HOC-wrapped components
register as definitions.
Distinct mechanisms never cross-link. Blind spots that static analysis can't see (interpolated hook names, variable callbacks, closures) resolve to nothing and are disclosed, never faked.
Language | Extensions |
Python |
|
JavaScript |
|
TypeScript |
|
TSX |
|
PHP |
|
Ruby |
|
Go |
|
A grammar that fails to load degrades that one language, not the server. Want another? Open an issue.
The graph always reflects the current working tree. File discovery is git ls-files -co (tracked plus untracked, minus ignored) and every file is read and hashed off
disk, not from git objects. So the graph sees whatever branch is checked out plus any
uncommitted or unmerged edits sitting on top of it.
Branch switches self-heal. git checkout rewrites the mtime on every file that
differs between branches, so the incremental pass re-parses exactly those and skips
the rest; the background watcher, SessionStart, and the post-edit hook all trigger it,
so the graph is current within a couple seconds of a checkout.
One caveat: there is a single .codegraph/graph.db per project directory, shared
across branches. It mirrors what is checked out right now, not all branches at once.
In the brief window between a git checkout and the next reindex tick, a query can
still reflect the branch you just left; run /codegraph-reindex (or index(force=True))
to make it current immediately.
For true parallel branches, use git worktrees. Each worktree is its own directory and
the graph resolution walks up to the nearest .codegraph/, so two worktrees get two
independent graphs that never touch each other.
codegraph is a local stdio MCP server running single-user at the same OS privilege
as the calling agent, which already has file and shell access. There is no privilege
boundary here. Root guards, parameter clamps, and size caps exist as footgun
protection, not as a security boundary. The bug classes that matter are crashes,
hangs, data corruption, and wrong exact edges.
Every hook failure path exits 0 silently. A malformed scope config indexes everything rather than crashing.
A corrupt graph DB is quarantined and rebuilt from source, disclosed in the result.
A crash between file commits and edge resolution leaves a persisted flag that forces re-resolution on the next run, so a half-written graph is never trusted.
Schema migrations check every column any INSERT uses against old DBs on open.
python tests/test_codegraph.py # plain python; also pytest-compatible62 tests: a 6-language ground truth plus regressions from four adversarial audit rounds. Each confirmed defect became a permanent test with decoys. Run it after any change to the parser, resolver, or hooks.
Shape-based resolution has a precision ceiling versus full type analysis. The long
tail lands in inferred/ambiguous, not in a wrong exact.
Ruby paren-less calls in expression position (x = helper + 1) are not extracted.
Member-expression JSX (<Animated.View/>) is skipped.
JS namespace-import resolution requires the alias to match the filename stem.
Python re-exports (util.helper defined in util/_impl.py) land unresolved.
Windows is untested; the hook glue is bash.
PolyForm Noncommercial 1.0.0. Free for noncommercial use - individuals, personal projects, education, research, charities, government.
Commercial use - including inside a for-profit company's development workflow - requires a commercial license: ccgraphtheory@shaunoster.com.
Required Notice: Copyright (c) 2026 Shaun Oster (https://github.com/Doublehead)
WordPress hook/filter dispatch - the string-named action/filter coupling a call graph CANNOT see (add_action/add_filter/register_rest_route/do_action/apply_filters).
name = a hook/action/filter name or REST route -> its in-repo listeners + fire sites.
name = a symbol -> the hooks it's registered on (the high-confidence callback->hook
direction: "register_routes fires on rest_api_init").
entry_points=True or empty name -> the public attack surface: every wp_ajax_* /
wp_ajax_nopriv_* / register_rest_route callback, with UNAUTH flagged.
Blind spots (honest): dynamic/interpolated hook names, closures, and variable callbacks (call_user_func($x)) cannot be resolved and are not edges.
This tool - NOT the edges_hook count - is the source of truth for whether
WordPress coupling was captured. edges_hook: 0 is normal for a pure-listener
plugin (its callbacks are fired by WP core / the REST framework, not by its own
do_action), and REST routes never contribute to that count by design. If a hook
seems missing, check here first.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| root | No | . | |
| entry_points | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it explains what it resolves (hooks, REST routes, symbols), what it cannot resolve (dynamic names, closures, variable callbacks), and how it handles entry_points. It also states it is the source of truth for WordPress coupling capture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, front-loading the purpose. It is slightly verbose but every sentence adds value, including details about blind spots and comparisons with other tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, the description covers most aspects: usage patterns, limitations, and relationship to edges_hook. The root parameter is not elaborated, but overall it is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, especially for the name parameter (three distinct use cases) and entry_points. However, the root parameter is not explained, leaving a minor gap despite 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool dispatches WordPress hook/filter actions, showing the coupling between action/filter names and their listeners and fire sites. It distinguishes between different uses of the name parameter and differentiates from siblings like stats, scope, pending.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage for three cases of the name parameter and explains the entry_points flag. It compares with edges_hook count and clarifies when the tool should be consulted. However, it does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Relationship drift from UNCOMMITTED edits. For every file changed on disk since the last index, diffs its RESOLVED call edges (caller -> resolved target, container-qualified) against the stored graph and reports what each edit ADDED or REMOVED - catching a re-pointed call (Foo.save -> Bar.save) a name diff would miss. Run after an edit to prove you didn't silently sever a relationship. Folds the changes into the graph as part of the diff.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | . |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the core behavior: diffing resolved call edges, reporting additions/removals, and folding changes into the graph. No annotations exist, so description carries full burden; it covers the main action but omits details like permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise but dense with technical terms; each sentence adds meaningful context. The key idea is front-loaded. Minor redundancy in explaining the diff process but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the tool's purpose and behavior well but misses critical context: no description of the root parameter, no output schema info, and no mention of prerequisites (e.g., existence of a stored graph). Incomplete for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter (root, default '.') is not mentioned in the description. With 0% schema coverage, the description fails to add any semantic value for the parameter, leaving the agent uninformed about its purpose or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly defines the tool as detecting 'relationship drift from UNCOMMITTED edits' and explains its unique ability to catch re-pointed calls that name diffs miss. The verb 'diff' and resource 'call edges' are specific and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Run after an edit to prove you didn't silently sever a relationship') and what it detects. However, it does not compare directly with siblings (stats, scope, hooks) or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scope which files codegraph indexes for this project, then force-reindex. On a big
vendor monorepo this is the highest-leverage action - and it's YOURS to do for the user,
not theirs. Pass exclude to drop vendor trees (recommended: keeps ALL the user's code,
auto-includes anything they add later) or include to index ONLY listed dirs. Globs are
relative to the project root; * spans directories (e.g. "wp-content/plugins/woocommerce/*").
Merges with any existing config and writes /.codegraph/config.json. Apply an index()
scope_suggestion straight through here. Returns the new config + post-scope stats.
Call with NO include/exclude for an instant DRY RUN: a suggested exclude list derived from the directory layout (no indexing) - so you can scope a huge repo BEFORE paying for a full index, then apply it. Returns {"dry_run": True, "suggested_exclude": [...], "current": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | . | |
| exclude | No | ||
| include | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden. It details the behavior: force-reindex, config merging, file writing, and the dry-run result format. This gives the agent a clear understanding of side effects and outputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer but every sentence adds value. It is front-loaded with the core purpose. Minor trimming could be possible, but it remains clear and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return values thoroughly: new config + post-scope stats for normal calls, and a dry-run object with suggested excludes. All edge cases (dry-run, merging) are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the input schema having 0% description coverage, the description compensates completely. It explains the 'exclude' parameter (drop vendor trees, recommended), 'include' (index only listed dirs), glob syntax, and the default behavior of no arguments triggering a dry run.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Scope which files codegraph indexes for this project, then force-reindex.' It clearly distinguishes the tool from siblings like 'stats', 'pending', and 'hooks' by focusing on scoping and reindexing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (on a big vendor monorepo), what parameters to pass (exclude vs include), and includes a dry-run feature. It also notes that merging with existing config and writing to a config file occurs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Graph overview: file/symbol/edge counts, resolution quality (exact vs inferred vs ambiguous vs unresolved), and breakdown by language and symbol kind.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | . |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral transparency. It describes the output content but does not disclose behavioral traits such as whether the tool is read-only, requires specific permissions, or has side effects. The description is output-focused rather than behavior-focused.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded with key information. However, it lacks structural elements like bullet points or clear separation of concepts, which could improve readability for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately lists the types of information returned (counts, resolution quality, breakdowns). However, it does not explain the format or structure of the output, nor does it clarify the role of the optional root parameter. This makes it partially complete but with notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description does not mention the sole parameter 'root' at all. It provides no additional meaning beyond the schema's default value. This is a significant gap for an optional parameter that likely controls the scope of the statistics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a graph overview with specific counts (file/symbol/edge), resolution quality levels (exact, inferred, ambiguous, unresolved), and breakdowns by language and symbol kind. This is a specific verb+resource description that distinguishes it from sibling tools like scope, pending, and hooks, which likely serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a summary tool ('Graph overview') but provides no explicit guidance on when to use this tool versus its siblings (scope, pending, hooks). No when-not-to-use instructions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0hookspendingscopestatsScored across 4 tools
Each tool has a clearly distinct purpose: stats provides graph overview, scope manages indexing, pending detects uncommitted relationship drift, and hooks analyzes WordPress hook coupling. No two tools overlap in functionality.
All tool names are single words in lowercase (stats, scope, pending, hooks). While they don't follow a strict verb_noun pattern, they are consistently short and descriptive, with no mixing of conventions.
With only 4 tools, the server is well-scoped for its purpose. Each tool covers a critical aspect of code analysis without being over or under represented.
The set covers overview, indexing management, change tracking, and WordPress-specific coupling. A potential gap is the lack of a general symbol or edge query tool, but the existing tools address key workflows.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
