Download the PHP package kha333n/laravel-code-graph without Composer

Laravel Code Graph

A persistent, structural map of your Laravel codebase, exposed to AI assistants over MCP — so they get token-efficient, accurate context instead of re-reading whole files.

By the AI, For the AI

Only AI and God knows how it works, but it works.

As per the rule of ✨

Why this exists

When you ask an AI assistant (Claude Code, Cursor, Windsurf, Zed, Continue) to make a change in a Laravel project, it typically does this on every turn:

1. grep for the symbol you mentioned
2. Read whole files to understand the context
3. Read more whole files to find the callers
4. Read the tests for those files
5. ...and only then start editing

That's a lot of tokens spent re-discovering structure that doesn't change between turns. On a real Laravel codebase it adds up to half or more of every conversation.

Laravel Code Graph parses your project once into a local SQLite graph, keeps it up to date incrementally on every file change, and exposes it to AI assistants via the Model Context Protocol. Instead of grepping and reading whole files, the assistant asks the graph "where is ScoringService::score?" and gets back:

Then it can Read exactly those 16 lines instead of the whole 800-line file.

What it indexes

A single SQLite file in .code-graph/index.sqlite containing:

Symbols

• Classes, interfaces, traits, enums, methods, functions
• Each with its FQN, file path, exact line range, signature, and docblock
• Plus a symbol per Blade view file

Edges (directed relationships)

• calls — method, static, function calls
• instantiates — new Foo(...) expressions
• depends_on — constructor parameter type hints (DI graph)
• extends / implements / uses_trait — class hierarchies
• has_relation — Eloquent hasMany/belongsTo/morphMany/etc, with relation type metadata
• binds — service container bindings inside service providers
• as_action — classes composing the lorisleiva/laravel-actions AsAction trait
• route_handler — routes/*.php → controller@method, with HTTP method + URI
• filament_model — Filament Resource → Model
• migrates_table — migrations → table pseudo-FQNs
• blade_includes — Blade @include, <x-foo> components, etc.
• livewire_renders — <livewire:foo> and @livewire('foo') references

Chunks

• Symbol-level source slices (one per method, function, small class, or Blade view)
• Mirrored into FTS5 for full-text search by intent or keyword

Installation

Requires PHP 8.3+, Laravel 11 / 12 / 13, and the pdo_sqlite extension.

The package auto-discovers via Laravel's package discovery — no service provider registration needed.

Quickstart

That's it. The install command:

1. Publishes config/code-graph.php to your project
2. Builds the initial graph
3. Registers code-graph in your project's .mcp.json so AI clients can connect (auto-detects Windows + WSL vs native)

After the install you'll see something like:

The index lives at .code-graph/index.sqlite — add .code-graph/ to your .gitignore.

Subsequent runs only re-parse files that actually changed:

Connecting to your AI assistant

code-graph:install does this automatically — it writes a code-graph entry into your project's .mcp.json (or creates the file if it doesn't exist) and auto-detects whether you're on a native Linux/macOS install or inside WSL on Windows. The resulting entry looks like one of:

After installing, restart your AI assistant (Claude Code, Cursor, Zed, ...) so it picks up the new MCP server. Verify with the MCP Inspector if needed:

If you need to register or re-register the MCP server later (or remove it):

Existing entries for other servers (like laravel-boost) are preserved.

The graph auto-refreshes on every tool call (mtime fast path keeps it under a few milliseconds), so the assistant always sees fresh data even right after you save a file.

The MCP tools

Every tool returns exact file:start-end line ranges so the calling assistant can Read only the slice it needs.

find-symbol-tool

Look up a symbol by name or fully qualified name. Falls back to FTS5 prefix matching if there's no exact hit. By default, also returns the file's use statements so you can author a new file from the same template without an extra Read.

search-code-tool

Keyword and intent search across symbol-level chunks (method bodies, small classes, Blade views) ranked by BM25. Use this when you don't know the exact name but you know what you're looking for.

get-callers-tool

Find every callsite that calls a function, method, or constructor. Pass a class FQN to get callers of any method on that class, or a method FQN for the exact callers.

Method calls on dynamic receivers (when the static type isn't resolvable) are recorded with a wildcard receiver ?::methodName.

get-callees-tool

The inverse: what does this function/method/class call?

get-blast-radius-tool

Recursive BFS over the call graph going backwards from a root symbol — every caller, every caller's caller, up to the requested depth. Use this before changing a method to see what might break.

Results are depth-stratified so you can see which symbols are most directly affected.

get-relations-tool

List Eloquent relations (hasMany, belongsTo, morphMany, etc.) declared on a Model. Returns the relation type, the related model FQN, and the file/line where each relation lives.

get-implementations-tool

Find every concrete class that extends, implements, or uses a given class, interface, or trait. The inverse of get-callers for inheritance.

report-issue-tool (opt-in)

Lets the AI assistant log a case where one of the other tools gave a wrong, missing, incomplete, or misleading result. The package writes the entry to a local markdown file (.code-graph/feedback.md by default). Disabled by default — enable it in config/code-graph.php if you want to gather a feedback log over time. Local-only; nothing is sent over the network.

Commands

Configuration

The published config lives at config/code-graph.php:

You can override the database location with the CODE_GRAPH_DB env var if you want the index somewhere other than .code-graph/. Set CODE_GRAPH_FEEDBACK=true to enable the feedback log.

How it works

Indexing pipeline

1. Walk the configured scan_paths with Symfony Finder.
2. For each file: mtime + size fast path — if both match the stored values, skip without reading.
3. On a mismatch: read + SHA-256. If the hash matches, just update mtime/size and skip.
4. Otherwise parse with nikic/php-parser and run a pipeline of small extractors over a single AST traversal:
   • SymbolVisitor — class/interface/trait/enum/method/function nodes
   • InheritanceEdgeVisitor — extends, implements, uses_trait
   • CallEdgeVisitor — calls, instantiations, constructor DI
   • EloquentRelationVisitor — hasMany/belongsTo/etc.
   • ServiceProviderBindingVisitor — bind/singleton/scoped/instance
   • AsActionRewriter — detects the AsAction trait and rewrites Foo::run/dispatch/... calls into edges targeting Foo::handle
   • FilamentResourceVisitor — protected static $model = X::class
   • RouteVisitor — Route::get/post/... in routes/*.php
   • MigrationVisitor — Schema::create/table in database/migrations/
   • ChunkExtractor — slices symbol bodies for full-text search
5. Blade files (.blade.php) are handled by a separate extractor that uses regex over the raw text — Blade isn't valid PHP, so nikic's parser doesn't apply.
6. Persist (file row, symbols, edges, chunks) to SQLite atomically per file.
7. After every file is processed, run a single resolveEdges() pass that joins source/destination FQNs against symbols.fqn to fill in numeric symbol IDs — this lets a visitor in file A emit an edge to a symbol that lives in file B without waiting for B to be parsed.

Storage

Five tables in a single .code-graph/index.sqlite file:

Freshness

The package guarantees that AI tools always see fresh data:

• Auto-refresh on every MCP call. Each tool runs an incremental index pass before answering. Thanks to the mtime + size fast path, the no-op case takes ~1ms even on hundreds of files.
• In-memory throttle. If a tool was called less than 250ms ago, the next call reuses the previous freshen — handles the case where an AI client batches several queries in one turn.
• code-graph:watch command for active development if you want the indexer running continuously in a separate terminal.

Why this saves tokens

• A Read of a 500-line file costs ~3000 tokens. A find-symbol call returning a 6-line summary with file:line ranges costs ~50.
• For multi-step tasks (find symbol → find callers → check tests → make change), the graph collapses 4 file reads to 1 grep + 3 line-range reads.
• The chunked search layer means search-code-tool returns whole, callable units instead of arbitrary line windows — no more "you read lines 100-200 but the function actually starts at line 95".
• Auto-refresh means the graph stays in sync without per-turn re-indexing prompts cluttering the conversation.

Working with Laravel Boost

If you use Laravel Boost (the official Laravel MCP server), the two are complementary, not overlapping:

Boost owns docs and runtime. laravel-code-graph owns structure. Run both side-by-side in your .mcp.json and your AI assistant gets the full picture.

Contributing

Issues and pull requests are welcome on GitHub. Before opening a PR, please open an issue first to discuss the change — especially if you're touching the storage schema or the MCP tool surface.

To work on the package locally:

The test suite uses orchestra/testbench to boot a minimal Laravel app and exercises the indexer end-to-end against fixture files in a temp directory.

License

MIT. See LICENSE.