claudeers.
// Developer Tools

wingbox

Code graph and blast-radius analysis for AI coding agents, built for large repositories and monorepos. Plugin and skill for Claude Code, Codex, Gemini CLI, C…

// Developer Tools[ cli ][ api ][ desktop ][ web ][ claude ]#claude#agent-skills#ai-agents#blast-radius#call-graph#claude-code#code-analysis#code-graph#devtools◷ MIT$open-sourceupdated 4 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up wingbox (claude-plugin project) into my current project.
Found on https://claudeers.com/wingbox
Repo: https://github.com/aileron-tech/wingbox
Homepage/docs: https://wingbox.dev
Detected install method: claude-plugin → /plugin install wingbox@aileron-tech/wingbox
Category: devtools. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)

⚠ Unverified / not recently updated — review before pasting a run-this config.

/plugin marketplace add aileron-tech/wingbox
/plugin install wingbox@aileron-tech/wingbox
// or clone
git clone https://github.com/aileron-tech/wingbox

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguagePython

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Wingbox: Code Graph and Blast Radius Analysis for AI Coding Agents

Wingbox: the code graph of a repository drawn as the structure of an aircraft wing, with the blast radius of one change highlighted

AI agents should know what their changes will break before editing code.

Wingbox builds a local code graph of your repository so that AI coding agents and developers can see dependencies, call flows, architecture boundaries and the blast radius of a change before editing code. It works as an agent skill in Claude Code, Codex, Gemini CLI, Cursor and GitHub Copilot, as an MCP server for any MCP client, and from the command line. It supports Python, TypeScript, Rust, C#, Java, Go, Ruby, Rails, PHP, Laravel (Blade, Livewire), Free Pascal, and Lazarus.

Runs fully locally: no network access, no model, no telemetry. It can be used inside a security perimeter and on a machine with no internet.

Website: wingbox.dev: benchmarks with charts, a sample report and the live map.

Install: pipx install wingbox && wingbox install | PyPI: the command, then the skill, an always-on block and a search hook for every coding assistant on the machine. Then type /wingbox in your agent.

The graph keeps itself fresh: in Claude Code a hook marks every edited file, and the next search patches only those files into the graph (about a second on a 1,200-file project); changes made by git or an editor are found too. See Keeping the graph fresh.

Skill only: npx skills add aileron-tech/wingbox | skills.sh

Release notes: Changelog

Note: Wingbox was formerly published as codespaces. The skill, the scripts and the generated files were renamed on 2026-11-15; see the Changelog for the old and new names.

Understand a large codebase before you change it. Wingbox is an architecture-aware code search and impact analysis tool for Python, TypeScript, TSX, Rust, C#, Java, Go, Ruby, Ruby on Rails, PHP, Laravel, Blade, Livewire, Free Pascal, and Lazarus repositories. It helps developers and AI coding agents find the right module, trace dependencies, measure change impact, and read only the source files that matter.

Use it for codebase architecture discovery, dependency graph search, blast-radius analysis, call-flow tracing, monorepo navigation, and safer AI-assisted coding.

Everything runs on your machine. The code graph is built by deterministic static parsing: no LLM call, no embeddings, no vector database, and no network access to build or query it.

Runs fully locally, inside your security perimeter

Wingbox is safe to run on code that must not leave the company:

  • No network. Building and querying the graph open no network connection. Run it with the network switched off to see for yourself: docker run --rm --network none -v "$PWD":/repo wingbox. The one command that reaches the network is wingbox update, which runs your package installer (pipx, uv or pip) when you ask it to.
  • No model, no account, no key, no telemetry. Nothing is sent to a model or to a service, and nothing is collected about its use.
  • Your code is read, never run. Wingbox parses source files with its own parsers and calls git for the ignore rules; it does not execute the code, the tests or the build of the repository. The --lsp option, off by default, starts a language server that is installed on the machine.
  • The results stay in one folder of the repository, .wingbox/: the graph index.sexp, REPORT.md and map.html. The map is one HTML file that loads nothing from outside and opens offline.
  • Works on a machine with no internet. Fetch the package and its pinned dependencies once (pip download wingbox -d wheels), carry the folder inside, and install with pip install --no-index --find-links wheels wingbox.
  • Deterministic and open. The same code gives the same graph; the source is MIT licensed and small enough to review.

Two tests of the repository keep this true: the package imports no module that opens network connections, and the map page loads no outside resource.

See it in action

wingbox impact on the immich server: a terminal asks what breaks if src/dtos/asset.dto.ts changes; on a 3D stack of architecture layers the file lights up in the domain layer, then the ten files that import it, then twenty more at two hops

Once the graph is built, an agent asks what a change breaks before it edits anything. Real output, Wingbox 0.2.6 on the server of immich (commit e5d6eb7, 707 modules):

$ wingbox impact src/dtos/asset.dto.ts 2
Impact of changing src/dtos/asset.dto.ts
  direct dependents   10
  within 2 hops       30

Depth 1
  src/controllers/asset-media.controller.ts   imports
  src/controllers/asset.controller.ts         imports
  src/controllers/shared-link.controller.ts   imports
  src/controllers/user-admin.controller.ts    imports
  src/dtos/asset-media.dto.ts                 imports
  src/services/asset-media.service.ts         imports
  src/services/asset.service.ts               imports
  src/services/asset.service.spec.ts          imports
  src/services/shared-link.service.ts         imports
  src/services/user-admin.service.ts          imports

Depth 2
  src/controllers/index.ts                                 imports
  src/controllers/asset-media.controller.spec.ts           imports
  src/controllers/asset.controller.spec.ts                 imports
  ...

The answer is 30 files in about 600 tokens, and it is exact: a TypeScript import resolver written separately from Wingbox finds the same 3,795 dependencies between the 707 modules, none extra and none missing.

wingbox build also writes .wingbox/map.html (wingbox open shows it). Its layers view stacks the architecture in 3D; click a file and its blast radius lights up across the layers:

One DTO changes: 30 files within two hopsThe base service changes: 281 of 707 modules
The Wingbox map of the immich server in the layers view, turning slowly, with the 30 modules reached by a change to src/dtos/asset.dto.ts highlightedLayers view of the Wingbox map with src/services/base.service.ts selected: 65 direct dependents, 281 modules within two hops

Benchmarks with charts, a sample report and the live map: wingbox.dev.

What can Wingbox answer?

  • Where is authentication, billing, upload, or another feature implemented?
  • Which modules depend on this service, class, function, or type?
  • Where exactly is this function, class or constant used, line by line?
  • What could break if I change this file?
  • Which two or three files should I read before fixing a bug?
  • How does a request or data value move through the system?
  • Does this dependency cross an architecture boundary?
  • Which Rails models, services, jobs, mailers, concerns, and specs are affected?
  • Can you draw a call-flow, data-flow, or sequence diagram from the code?

Instead of searching a repository one text match at a time, Wingbox turns code into a queryable code graph of modules, entities, imports, references, call relationships, architecture layers, and infrastructure connections.

What is a code graph?

A code graph describes a codebase as facts instead of text. Modules, classes, functions and types are nodes; imports, references, data flows, calls and architecture layers are edges. Wingbox writes the graph to .wingbox/index.sexp as plain S-expression facts, so the bundled query tool and ordinary text search can both read it.

What is blast radius analysis?

The blast radius of a change is everything that depends, directly or transitively, on the code you are about to edit. Wingbox computes it from the reverse dependencies in the code graph. impact path/to/file prints the dependents by depth and the files to read first; rdeps and boundary give the same facts as a tree and as a change boundary.

$ wingbox impact scripts/lang/treesitter.py

Impact of changing scripts/lang/treesitter.py
  direct dependents   4
  within 2 hops       11

Depth 1
  scripts/lang/csharp/parser.py   imports
  scripts/lang/go/parser.py       imports
  scripts/lang/java/parser.py     imports
  scripts/lang/ruby/parser.py     imports
...

The text form is for people. Agents add --sexp to get the same facts as compact S-expressions.

Measured: 100 questions, with and without Wingbox

One hundred "which files depend on this file" questions, drawn at random with a fixed seed in five public repositories (TypeScript, Rust, Python):

  • wingbox impact names the complete list of dependent files, with nothing outside it, in 100 of 100 questions (95 % interval 96 to 100 %). The lists hold 1 to 503 files.
  • Claude Code answers 55 of the questions with its built-in search only, and again with the wingbox command added:
SetupComplete answersTokens per answerCost per answer
With Wingbox55 of 5532,1830.031 USD
Built-in search only48 of 5549,2920.063 USD

Tokens -35 % (95 % interval -47 % to -20 %), cost -51 % (-58 % to -43 %). The saving is large on the Rust and Python repositories and absent on the two TypeScript ones.

  • Checked against every import statement of seven corpora (3,795 dependencies in the largest), the graph has no wrong dependency and one missing: an import of a vendored bundle, which Wingbox leaves out of the graph.

The reference lists come from resolvers that share no code with Wingbox. The scripts, the lists and every result file are in benchmarks/impact, with what the benchmark does not show. Dockerfile.benchmark runs the tests that need no model in a clean container and compares every result with the committed one:

docker build -f Dockerfile.benchmark -t wingbox-benchmark .
docker run --rm wingbox-benchmark

Wingbox and Graphify on the same tests

Graphify builds a knowledge graph of a codebase, documents and images for coding agents. Wingbox is narrower: a deterministic graph of the code alone, built without a model, and exact lists of what depends on a file. Both were run on the same public repositories (Wingbox 0.2.0, Graphify 0.9.110, no model on either side):

TestWingboxGraphify
Exact list of dependent files, five questions (wingbox impact, graphify affected)5 of 51 of 5
Dependencies against the 1,801 import pairs of FastAPI0 wrong, 0 missing22 wrong, 32 missing
Tokens a coding agent spends per answer (built-in search alone: 59,367)25,598109,071
Graph of FastAPI on a hosted runner2.2 s17.9 s

graphify affected follows calls and references as well as imports, so it answers a wider question than "who imports this file"; the report gives its figures restricted to imports too. The scripts, the reference lists, every result file and the token formula Graphify publishes are in benchmarks/graphify.

Quick start for AI coding agents

Install the command and let it set up every coding assistant on the machine (see Install into your coding assistants):

pipx install wingbox
wingbox install

In the agent, /wingbox builds the graph and summarizes the report, /wingbox path/to/file shows what a change to that file breaks. Or ask a natural question:

Use the Wingbox skill before reading source.
Find where file uploads are handled, analyze that module, show its dependencies
and blast radius, then list only the boundary files needed for the change.

To install the skill alone, without the command's block and hook:

npx skills add aileron-tech/wingbox

MCP clients use wingbox mcp: see Use from an MCP client.

Install as a plugin

This repository is also a plugin marketplace for Claude Code and Codex. The plugin, in plugins/wingbox, bundles the wingbox skill and the MCP server wingbox mcp, and in Claude Code the search hook that wingbox install adds. Use either the plugin or wingbox install, not both (wingbox uninstall removes what install added).

Claude Code:

/plugin install wingbox --marketplace aileron-tech/wingbox

or /plugin marketplace add aileron-tech/wingbox, then /plugin install wingbox@aileron-tech (from a shell: claude plugin marketplace add aileron-tech/wingbox and claude plugin install wingbox@aileron-tech). The skill is /wingbox:wingbox. The plugin runs the installed wingbox command; without it, and with uv installed, it runs uvx --from git+https://github.com/aileron-tech/wingbox@<commit> wingbox, pinned to the commit of the latest release tag, which uv fetches on first use. The search hook never downloads and stays silent while neither is available.

Codex:

codex plugin marketplace add aileron-tech/wingbox
codex plugin add wingbox@aileron-tech

The Codex plugin runs wingbox from your PATH, so install the command first with pipx install wingbox. Codex lists the skill as wingbox:wingbox.

The plugin folder holds a copy of SKILL.md and references/, and the version of pyproject.toml; python3 tools/sync_plugin.py refreshes them and the tests fail while they differ.

Quick start from the command line

Install the wingbox command (Python 3.11 or newer, macOS or Linux):

pipx install wingbox

Or run it without installing:

uvx wingbox --help

Build the code graph of a project, then ask what a change will break:

cd /path/to/project
wingbox build .
wingbox impact path/to/file.py
wingbox usages path/to/file.py::create_order
wingbox quick "file upload"

wingbox usages lists every place that uses one symbol, through re-exports and aliases, grouped by file, with the line, the column and the kind of use:

Usages of Invoice (class, app/models.py:1)
  7 uses in 2 files

app/__init__.py
  1:21   re-export
app/billing.py
  1:17   import
  2:24   import
  4:13   extends
  7:13   type
  7:25   type
  8:11   call

The symbol is Name, <file>::Name or <file>::Class.method; a name defined in several files lists the candidates. Kinds: import, re-export, call, type, extends (extends or implements), reference. For a method, calls whose receiver type is not in sight are listed as unresolved-call, never guessed. At most 200 uses unless --all; --sexp prints the same answer as usage facts. The build records which files use each definition; the first usages after a change also reads every use position (a parallel pass over the files, about as long as a build) and keeps them for the next calls. Python, TypeScript, JavaScript and Rust have use positions; in other languages usages names the files that reference the symbol.

wingbox build [PATH] accepts the builder options described below, and every query command in Common code searches is available as wingbox <command>. The command installs the parsers for all supported languages and finds the project by its .wingbox/index.sexp, in the current directory or a parent; without one it says so and names the paths it looked at. wingbox open shows the map of the project in the browser.

Install into your coding assistants

wingbox install                    # every assistant whose configuration folder exists
wingbox install --dry-run          # name every file it would write, change nothing
wingbox install --assistant codex  # only the named assistants (repeatable)
wingbox install --project          # into the current repository instead of the home folder
wingbox uninstall                  # remove exactly what install added

wingbox install puts three things in place for each assistant: the wingbox skill (so /wingbox exists), a short always-on block in the instructions file the assistant reads in every session, and for Claude Code a hook that runs before each search. Running it again changes nothing; after an upgrade it refreshes the skill. Assistants are found by their folders in the home directory: ~/.claude, ~/.codex, ~/.gemini, ~/.cursor, ~/.copilot and ~/.agents.

Assistant (--assistant)Skill, globalSkill, --projectAlways-on block, globalBlock, --project
Claude Code (claude-code)~/.claude/skills/wingbox.claude/skills/wingbox~/.claude/CLAUDE.mdCLAUDE.md
Codex (codex)~/.agents/skills/wingbox.agents/skills/wingbox~/.codex/AGENTS.mdAGENTS.md
Gemini CLI (gemini)~/.gemini/skills/wingbox.gemini/skills/wingbox~/.gemini/GEMINI.mdGEMINI.md
Cursor (cursor)~/.cursor/skills/wingbox.cursor/skills/wingboxnone (user rules live in the settings)AGENTS.md
GitHub Copilot, CLI and VS Code (copilot)~/.copilot/skills/wingbox.github/skills/wingbox~/.copilot/copilot-instructions.mdAGENTS.md
Shared Agent Skills folder of npx skills (agents)~/.agents/skills/wingbox.agents/skills/wingboxnoneAGENTS.md
  • The block sits between <!-- wingbox:begin --> and <!-- wingbox:end -->. It tells the agent to run wingbox quick or wingbox analyze before reading code, wingbox impact <file> before changing a file, and /wingbox for an overview. Text outside the markers is never touched; a file that links to another one (CLAUDE.md to AGENTS.md) gets one block.
  • The Claude Code hooks are a PreToolUse entry with the matcher Grep|Glob|Read in ~/.claude/settings.json (.claude/settings.json with --project) that runs wingbox hook pre-search, and a PostToolUse entry with the matcher Edit|Write|MultiEdit that runs wingbox hook dirty. When the project has a graph, the search hook adds a few lines of context to the search: the modules and definitions that match the pattern with their direct dependents, or for a file its dependents and the hint to run wingbox impact. It answers in 0.4 to 0.7 s on a graph of 8,000 files, Python start included, never blocks the tool, opens no network connection, and says nothing in a project without a graph. The edit hook only marks the edited file (see "Keeping the graph fresh"). Other settings and hooks are kept; the file is backed up once to settings.json.wingbox-bak before the first change.
  • A skill folder that another installer wrote (for example npx skills add) is left as it is. Install records what it did in ~/.wingbox/installed.sexp; wingbox update and wingbox uninstall read it.
  • /wingbox with no argument builds the graph when it is missing or older than the code and summarizes .wingbox/REPORT.md; /wingbox <file> runs wingbox impact <file> 2; /wingbox <command> ... runs that command. In Codex the skill is called as $wingbox.

Every result is a list of facts: --sexp prints them as S-expressions such as (install-wrote ~/.claude/skills/wingbox :what skill :assistant (claude-code) :version 0.2.6), and the default output is the same facts as aligned text.

Update

wingbox update --check    # installed and latest version, nothing installed
wingbox update --dry-run  # the command it would run
wingbox update            # upgrade, then refresh what wingbox install put in place

wingbox update upgrades with the installer that installed Wingbox: pipx (pipx upgrade wingbox), uv (uv tool upgrade wingbox) or pip of the Python environment it runs in. A Docker image or an editable or local install cannot update itself; the command says so and prints what to run instead. Wingbox itself opens no network connection: only the installer reaches the package index, and only when you run wingbox update.

It also looks for files that versions before 0.4.1 wrote outside .wingbox/ (.code_graph.sexp, .code_graph.uses.sexp, .code_graph.uses-cache.json, .code_graph_cache.json, wingbox-out/), in the current folder and its parents up to the project root and in every --project install, and prints one warning line per project (yellow on a terminal); it deletes nothing.

Keeping the graph fresh

The graph follows the code without wingbox build. Before the search hook, an MCP tool or a query command reads it, the files changed since it was built are brought in:

  • In Claude Code, wingbox hook dirty (PostToolUse on Edit and Write) marks the edited file in .wingbox/graph-state.json and returns; it never builds.
  • Changes made elsewhere (an editor, git checkout, a script, a shell command) are found by comparing the size and modification time of every source and resolution config, and the time of every folder, with the snapshot the last build wrote: one stat per entry, no hashing.
  • The changed files are patched in: only they are parsed again, and only the modules that read them, that resolved a name a created or deleted file could now answer, or that looked up a name the change added or removed are resolved again. The result is the graph a build publishes, byte for byte. A changed package.json, tsconfig*.json, pyproject.toml, .gitignore or other resolution config, a changed source in a language other than Python and TypeScript, or a change that reaches more than a quarter of the modules takes the incremental build instead. Several edits are brought in by one refresh, and never two run at once for one project.
  • The search hook waits up to WINGBOX_HOOK_WAIT seconds (3) for the refresh; a longer one goes on in the background and publishes when it is done. While the graph misses known changes, after a failed refresh (not repeated until something changes again) or with WINGBOX_AUTO_REFRESH=0, the hook gives no context from it but (wingbox-graph-stale :reason ...); MCP answers start with that line and query commands print it on stderr. WINGBOX_REFRESH_WAIT (600 s) is the wait of MCP tools and query commands; WINGBOX_CHECK_INTERVAL (0) spaces out the file-system checks.

Measured on a shared machine under heavy load (load average 20 to 55), wall time, the version before this change and after it, runs interleaved:

fastapi, 1,227 Python filesTypeScript monorepo, 6,834 files
Search hook, nothing changed0.20 -> 0.24 s0.30 -> 0.38 to 0.52 s
of which the check for outside changes0.02 s (1,666 entries)0.17 s (9,748 entries)
Edit hook0.21 s0.26 s
One edited file patched in1.0 s (24 modules redone)9 to 13 s (12 modules redone)
Incremental build after one edit11.2 -> 4.4 s23.0 -> 25.9 s
Build without changes11.1 -> 3.3 s20 to 23 -> 20 s
Cold build24.1 -> 7.0 s44 -> 47 s

A patch grows with the modules it redoes: on fastapi 0.6 s for 1 file, 1.1 s for 10, 1.4 s for 50 and 3.3 s for 150 files (234 modules), against 3.5 to 5.6 s for the incremental build of the same changes. On the monorepo the patch is dominated by reading and writing the build cache (35 MB) and the fragment store (39 MB); it takes longer than the search hook waits, so the first search after an edit there answers (wingbox-graph-stale :reason refresh-timeout ...) and the next ones, once the patch is published, use the new graph.

The report and the map

wingbox build PATH creates PATH/.wingbox/ and writes everything there; nothing else in the project is written. The folder also marks the project: every command, the hooks and the MCP server look for the nearest .wingbox/index.sexp at or above the current folder, and that folder is the project root.

File in .wingbox/For whomWhat it is
index.sexpAI coding agentsThe code graph in a compact form that the query commands read
index.uses.sexpAI coding agentsModule-level variables and the files that use each definition; usages adds every use position on its first call
index.uses-cache.jsonWingboxThe use walk of each file by content hash, so that usages after a change reads only the changed files
cache.jsonWingboxThe parse of each file by content hash, so that a build reads only changed files
REPORT.mdPeopleKey findings, the most depended-on files, architecture layers, boundary violations, where to start reading
map.htmlPeopleAn interactive map of the code graph: one file, opens in a browser (wingbox open), works without a network connection
graph-*, refresh.*WingboxWhat keeps the graph fresh: the facts of each module and what they were read from, the sizes and times of the sources at the build, the folder it was built from, the files changed since (see "Keeping the graph fresh")
.gitignoregitIgnores every file above, so that a file you write into .wingbox/ later stays in the repository

On the map, click a file to see its blast radius: the files that depend on it move onto rings, one ring per hop. The layers view stacks the architecture layers as planes in 3D and can be turned with the mouse. A link such as map.html#select=src/app.ts opens the map on that file.

The generated files are rewritten on every build and never committed thanks to .wingbox/.gitignore; you can also ignore the whole folder. A .wingbox/ folder copied or moved to another place is read as it is but never refreshed there: queries say rebuild. Wingbox deletes nothing outside .wingbox/; wingbox update names files that versions before 0.4.1 left in a project (.code_graph*, wingbox-out/) so that you can remove them.

Run in Docker, with nothing installed

git clone https://github.com/aileron-tech/wingbox
docker build -t wingbox wingbox

cd /path/to/project
docker run --rm --network none -v "$PWD":/repo wingbox
docker run --rm --network none -v "$PWD":/repo wingbox impact path/to/file.py

The first docker run builds the code graph, the report and the map of the mounted project; any other Wingbox command goes after the image name. The container needs no network, and --network none shows it: nothing leaves the machine. On Linux add --user "$(id -u):$(id -g)" so that the written files belong to you.

Running the scripts from a clone

Clone the repository:

git clone https://github.com/aileron-tech/wingbox.git
cd wingbox

Build the code graph for an explicit project directory:

python3 scripts/build_code_graph.py --root /absolute/path/to/project

Exclude tracked source snapshots or generated fixture trees by directory name. The option is repeatable and applies at any depth:

python3 scripts/build_code_graph.py \
  --root /absolute/path/to/project \
  --exclude-dir review-bundles \
  --exclude-dir generated-fixtures

When the target is inside a Git worktree, the builder also honors repository ignore rules through Git itself. This applies to source files and language configuration such as tsconfig.json, package.json, Cargo.toml, go.mod, and LSP project discovery. Tracked snapshot paths that still match .gitignore are excluded as well.

Parser packages are loaded only for languages found in that project. Python needs no extra parser package. If another detected language is not installed, the builder stops before publishing and prints its exact install command, for example:

python3 -m pip install -r requirements/typescript.txt
python3 -m pip install -r requirements/csharp.txt
python3 -m pip install -r requirements/ruby.txt
python3 -m pip install -r requirements/php.txt

Install only the files for languages you use, then run the same build command again. requirements/php.txt pins tree-sitter==0.25.2 and tree-sitter-php==0.24.1; the package dependencies list the PHP grammar, so an installed wingbox needs no separate step. requirements.txt contains the separate infrastructure-topology dependency.

Run a relevant search and get the first matching module with its full context:

python3 scripts/code_graph_search.py \
  --map /absolute/path/to/project/.wingbox/index.sexp \
  --root /absolute/path/to/project \
  quick "file upload"

The code graph is written to .wingbox/index.sexp. Wingbox does not modify the source files it analyzes.

Use from an MCP client

wingbox mcp runs Wingbox as an MCP (Model Context Protocol) server: the client starts the command, sends JSON-RPC requests on its standard input and reads the answers on its standard output. The transport is stdio only: no port, no network. Logs go to standard error. Every tool carries MCP annotations: a title, and read-only for every tool except build, which writes the graph; no tool is destructive or reaches outside the repository.

wingbox mcp                         # serve the current directory
wingbox mcp --root /path/to/project

The server speaks protocol revision 2026-07-28 (requests with per-request _meta, server/discover) and the initialize handshake of revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

ToolWhat it answers
buildBuild or refresh the code graph (full, exclude_dirs)
impactBlast radius of a file, as text (target, depth, all)
analyze, quickFull analysis of a module, or of the first module matching a keyword
boundary, boundaries, layersFiles to read for a change; layer violations; modules by layer
deps, rdepsDependency and reverse dependency trees
entity, find_function, find_typeWhere a name is defined and used
usagesEvery use of one symbol by file, line:column and kind, as text (symbol, all)
find_callers, find_calls, find_callchainCall graph questions
diff_functionsFunctions changed since a git ref
queryA Scheme query on the graph

Each tool returns the output of the wingbox command of the same name. A query tool called before the graph exists answers that build must be called first. Answers stop at 200 items; all: true lists everything. The graph is read once and read again when .wingbox/index.sexp changes.

Claude Code, in the project directory:

claude mcp add wingbox -- wingbox mcp

--scope project writes the server into .mcp.json for everyone working on the project; --scope user makes it available in all your projects.

Codex, in ~/.codex/config.toml (or codex mcp add wingbox -- wingbox mcp):

[mcp_servers.wingbox]
command = "wingbox"
args = ["mcp"]
cwd = "/path/to/project"

Cursor, in .cursor/mcp.json of the project (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "wingbox": {
      "command": "wingbox",
      "args": ["mcp", "--root", "${workspaceFolder}"]
    }
  }
}

Claude Desktop, in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Claude Desktop starts servers in an undefined directory and with a reduced PATH, so give absolute paths for the command and the project (which wingbox prints the first):

{
  "mcpServers": {
    "wingbox": {
      "command": "/absolute/path/to/wingbox",
      "args": ["mcp", "--root", "/absolute/path/to/project"]
    }
  }
}

Without installing, uvx wingbox mcp works in place of wingbox mcp ("command": "uvx", "args": ["wingbox", "mcp", ...]).

Common code searches

GoalCommand
Find and analyze a featurequick "payments"
Search for a modulesearch "payment.*service"
See full module contextanalyze path/to/module
Find files needed for a changeboundary path/to/module --files-only
Trace dependenciesdeps path/to/module 2
See what a change will breakimpact path/to/file.py
Find every use of one symbolusages path/to/file.py::create_order
Measure blast radius as a treerdeps path/to/module 2
Find a class, module, interface, enum, or typefind_type OrderService
Find a function or methodfind_function createOrder
Find callersfind_callers createOrder 2
Trace a call pathfind_callchain handleRequest createOrder 5
Search inside function bodiesgrep_functions "validate.*input"
Check architecture boundariesboundaries all
Check naming conventionsinvariants all
Inspect changed functionsdiff_functions HEAD~1

analyze and impact always print the complete counts and list at most 200 dependent files, nearest first; add --all for every file. boundaries reports an import of TypeScript types only apart from the violations: the compiler erases it, but a change of the type still reaches the importing file.

Pass --map and --root (see Running the scripts from a clone) when the graph is outside the current directory and its parents.

Supported languages and projects

LanguageWhat is indexed
PythonModules, imports, classes, functions, methods, inheritance, and references
TypeScript, TSX and JavaScriptImports, re-exports, classes, interfaces, functions, types, decorators, aliases, and references
RustCargo crates, modules, use dependencies, structs, traits, enums, functions, implementations, and methods
C#Namespaces, types, interfaces, records, enums, methods, attributes, inheritance, and local type dependencies
JavaPackages, imports, classes, interfaces, records, enums, methods, annotations, inheritance, and local type dependencies
GoModules, packages, imports, structs, interfaces, functions, constants, variables, receiver methods, and local package dependencies
Ruby and RailsRuby classes, modules, instance and singleton methods, inheritance, requires, Zeitwerk constants, concerns, associations, callbacks, jobs, mailers, and impacted specs
PHP and LaravelPHP 8 classes, interfaces, traits, enums, methods, attributes, use aliases, inheritance, Composer PSR-4 classes, Blade views and components, Livewire components, Eloquent associations, events, and jobs
Free Pascal and LazarusUnits, programs, uses/includes, classes, records, interfaces, inheritance, methods, and routines

Wingbox is designed for single repositories and monorepos. It understands Python project roots, TypeScript configuration and package aliases, Cargo package names and local Rust crate dependencies, .NET solutions and projects, Maven and Gradle projects, Go modules and workspaces, Rails application/autoload roots with project acronyms, and Composer PSR-4 roots, including nested module manifests and autoload-dev.

Pascal dependencies resolve by case-insensitive unit identity and explicit UnitName in 'path.pas' paths, then by a unique same-directory unit. Other ambiguous unit names remain unlinked, compiler conditionals are indexed conservatively, and Pascal does not use LSP enrichment. Automatic Pascal copies under Lazarus backup/ directories are excluded without excluding other supported languages stored under the same path.

It can also map infrastructure relationships from Kustomize, Helm, and Terraform.

Rails code often depends on constants without an explicit require. Wingbox builds a project-local constant index and follows conservative Zeitwerk naming rules, so changing a shared model, concern, service, job, or mailer can reveal its likely callers and affected specs.

The default Ruby map does not boot Rails. Ambiguous reopened constants remain unlinked, polymorphic associations stay open, and external or dynamic Ruby calls are not guessed. This keeps blast-radius results useful without executing application code.

PHP and Laravel code names classes through Composer instead of relative paths, and one feature can span PHP classes, Blade templates and Livewire components. Wingbox reads every composer.json (the root manifest and a module's nested one) and merges autoload.psr-4 with autoload-dev.psr-4, the longest matching prefix first, as Composer does. A .php file is indexed as PHP, a .blade.php file as Blade: classes, interfaces, traits, enums, methods, attributes, use aliases and grouped uses, extends, implements and trait use.

Laravel conventions become edges. view('users.show'), View::make(...) and view()->make(...) name the template; a namespaced admin::nav uses the directories registered by loadViewsFrom(...) or View::addNamespace(...), or a module's resources/views directory. Blade @extends, the @include* family, @component and @each, anonymous <x-*> components, and <livewire:counter> or @livewire('counter') are followed. A Livewire component resolves through Livewire::component(...) registrations, its flat or dotted alias under App\Livewire or a module's Livewire folder, or its livewire.<alias> template; a component class that extends Livewire\Component also links to the template named after it (App\Livewire\Chat\FileUpload to livewire.chat.file-upload).

Eloquent associations create edges when the first argument is X::class (belongsTo, hasOne, hasMany, the through and morph variants); event(new X(...)), dispatch(new X(...)), X::dispatch(...) and X::dispatchSync(...) link events and queued jobs. Models are domain, controllers, middleware and requests under app/Http are api, app/Livewire and resources/views are ui, app/Jobs, app/Listeners and app/Policies are service, app/Events is domain, and tests are test.

The map is conservative: a class name that no file declares, or that several files declare without a single PSR-4 owner, creates no edge, and so do an alias with several targets and a view in several view directories. IDE-helper stubs such as _ide_helper_models.php do not shadow the real class: the file the PSR-4 map autoloads wins. A Livewire alias that the application registers dynamically, in a loop over a directory for example, is left unlinked unless it also follows one of the conventions above. Nothing boots Laravel, runs Composer or opens a network connection; the graph comes from source text and composer.json.

A simple workflow

  1. Build the map for the exact repository you want to understand.
  2. Search for a feature, type, function, or module instead of guessing a path.
  3. Analyze the returned module to see dependencies, reverse dependencies, layers, references, and the minimal boundary files.
  4. Read only those files and make the change.
  5. Rebuild the map after structural changes and check boundaries again.

This keeps code exploration focused and gives AI coding agents less irrelevant context, clearer ownership, and better evidence for implementation decisions.

Call graphs and diagrams

The default static analysis builds import, reference, data-flow, and architecture edges. Add --lsp when supported language servers are installed to enrich the map with precise call-site information:

wingbox build /path/to/project --lsp

You can then ask an agent to render Mermaid diagrams from the graph:

Use Wingbox to trace the file upload flow and render a Mermaid sequence diagram.
Base every participant and edge on the code-graph facts.

Accuracy and limits

Wingbox is an architecture and impact-analysis tool, not a compiler replacement. The default map comes from deterministic static parsing. Optional LSP enrichment adds call hierarchy and reference detail when the relevant language server is available.

For generated imports, runtime dependency injection, reflection, or framework behavior that is not explicit in source, verify the result against the running application or the owning framework.

FAQ

Does Wingbox send my code anywhere?

No. The code graph is built and queried locally by deterministic static parsing. Building and querying need no LLM, no embeddings, no vector database and no network access.

Is Wingbox free?

Yes. It is open source under the MIT license, with no paid tier, no account and no usage limit.

Can I run it fully offline?

Yes. Building and querying never use the network; wingbox update runs your package installer (pipx, uv or pip) when you ask it to. On a machine with no internet, install from wheels fetched once elsewhere (pip download wingbox -d wheels, then pip install --no-index --find-links wheels wingbox), or run the Docker image with --network none.

Does it use embeddings or a vector database?

No. The graph is built by parsers that read the source; a question is answered by following recorded import, reference and inheritance edges, not by retrieving text that looks similar.

RAG splits code into chunks, embeds them and returns the chunks that look closest to a question. Wingbox resolves each import to the file it names and answers from those edges, so impact returns the complete list of dependent files with nothing guessed. The benchmark checks every list against resolvers that share no code with Wingbox: benchmarks/impact.

My editor already has "go to definition" and "find usages". Why a graph?

The editor answers one symbol at a time, inside an open, resolved project. wingbox usages gives the same kind of list without a language server or installed dependencies (on 100 refactoring questions it names exactly the files of the language tooling's find usages in all 100). The graph also answers for a whole file or module at once (what depends on it within two hops, which layer boundary a dependency crosses, which files to read first), for a coding agent on the command line, with no language server and no installed dependencies.

How is it different from Sourcegraph or ctags?

ctags lists where names are defined; it does not resolve imports or say who depends on a file. Sourcegraph is a code search server; its precise navigation needs an indexer per language run on a resolved project. Wingbox is one local command that builds a dependency graph of the repository in seconds and keeps it as a file next to the code.

Does the graph stay current as I change code?

Yes: the search hook, the MCP tools and the query commands bring in the files changed since the last build before they read the graph, and in Claude Code an edit hook marks each edited file (see "Keeping the graph fresh"). A graph that may miss changes says so. wingbox build rebuilds by hand; files whose content did not change are taken from the cache. diff_functions <ref> lists the functions changed since a git ref.

Which AI coding agents does Wingbox work with?

Codex, Claude Code, Gemini CLI, Cursor, GitHub Copilot, and other clients that support Agent Skills; wingbox install sets up the ones it finds on the machine. Any MCP client (Claude Code, Codex, Cursor, Claude Desktop) can also use it through wingbox mcp; see Use from an MCP client. The scripts can also be run directly from the command line.

How is a code graph different from text search with grep or ripgrep?

Text search finds lines that match a pattern. A code graph answers structural questions: which modules depend on this one, what a change can break, which architecture boundary a dependency crosses, and which few files are worth reading first.

Does Wingbox replace a compiler or a language server?

No. It is an architecture and impact-analysis tool. Optional LSP enrichment adds call hierarchy and reference detail; behavior that is not explicit in source, such as generated imports, runtime dependency injection or reflection, must be verified against the running application.

Which languages are supported?

Python, TypeScript, TSX and JavaScript, Rust, C#, Java, Go, Ruby and Ruby on Rails, PHP and Laravel (Blade and Livewire), Free Pascal and Lazarus, plus infrastructure relationships from Kustomize, Helm and Terraform.

Where Wingbox comes from

Wingbox grew out of the paper Theory of Code Space: Do Code Agents Understand Software Architecture? by Grigory Sapunov (arXiv:2603.00601, February 2026; code, the author's write-up). It asks whether a coding agent that explores a repository under a budget of files can build and keep a correct "belief map" of its architecture, and finds that this depends on the model and that the map can collapse. The paper itself carries over the framework of Theory of Space (arXiv:2602.07055), which measured the same failures in physical space.

Wingbox takes the opposite route: the agent does not build the map, a parser does, from every file, without a model, and again after every change.

  • March 2026: a script that writes the belief map from the syntax tree, first as JSON, then as S-expressions, one fact per line, to save agent tokens.
  • June 2026: published as the codespaces skill.
  • November 2026: renamed Wingbox; the belief map became the code graph.

The papers do not evaluate Wingbox; the link between them and this tool is ours. The full story: wingbox.dev/story.

Project resources

License

MIT

// faq

What is wingbox?

Code graph and blast-radius analysis for AI coding agents, built for large repositories and monorepos. Plugin and skill for Claude Code, Codex, Gemini CLI, Cursor and Copilot, plus an MCP server; the graph stays fresh after every edit. Python, TypeScript, Rust, C#, Java, Go, Ruby/Rails, PHP/Laravel, Free Pascal. Fully local.. It is open-source on GitHub.

Is wingbox free to use?

wingbox is open-source under the MIT license, so it is free to use.

What category does wingbox belong to?

wingbox is listed under devtools in the Claudeers registry of Claude-compatible tools.

4 views
★ 10 stars
unclaimed
updated 4 days ago

// embed badge

wingbox on Claudeers
[![Claudeers](https://claudeers.com/api/badge/wingbox.svg)](https://claudeers.com/wingbox)

// retro hit counter

wingbox hit counter
[![Hits](https://claudeers.com/api/counter/wingbox.svg)](https://claudeers.com/wingbox)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how wingbox connects across the ecosystem