Waxwing

Give your codebase an explanation people can explore.

Your coding agent explains a system. Later, you need to retrace a workflow, check a claim against the code, or help someone else understand it. The answer is somewhere in the conversation.

With Waxwing, you and your agent can turn that explanation into an interactive map: follow a workflow, look inside a component, and inspect the code references behind a claim. Share it as an HTML file anyone can open in a browser.

Explore the demo → · Try it on your code · Documentation

The demo explains Waxwing itself. Select Layout engine, inspect its source references, then open Inside architecture layout to look closer. Switch to the build workflow to follow the steps from input to output. This is a curated explanation of a pinned source revision.

Try it on your code

You need Node.js 20.19.0 or newer and a coding agent that can read your repository and run terminal commands.

Install the published release:

npm install -g @isought/[email protected]

Open your repository with your agent and give it one question. For a web service, start with this prompt; replace the request question with something you want to understand about your own project:

Use Waxwing to explain how this repository handles an incoming request.

Run npm root -g, then read @isought/waxwing/AGENT_GUIDE.md inside the
printed directory. Use that guide and the installed waxwing command.

Inspect the relevant code. Map the main components and request workflow,
link claims to their supporting source, and leave unknowns explicit.
Validate the model, then use waxwing build to write the interactive HTML
diagram to ./waxwing-output.
Open the result, or tell me where to find it.

Open waxwing-output/diagram.html. Follow the request, select a component, and check a source reference against the code. Share that HTML file when it answers your question—viewers need no installation, server, or account. The file includes the model and linked document contents, so check those before sharing private work.

Your agent reads and explains the code; Waxwing builds the explorable output. Waxwing's renderer does not call an LLM. Validation checks that the model is consistent; you still need to check the explanation against its sources.

For repeat use, install the Waxwing skill in your agent's skills directory. It supports creating explanations and updating existing ones.

After installing Waxwing, run:

waxwing build-site "$(npm root -g)/@isought/waxwing/examples/waxwing/model.json" ./waxwing-demo --direction DOWN

Open waxwing-demo/index.html. This uses macOS/Linux shell syntax. On Windows, run npm root -g and substitute its printed path for $(npm root -g).

Help shape it

Waxwing is an early, personally maintained open-source project. The formats are still experimental. Current limits and the roadmap describe where it stands.

Tried it and got stuck? Open an issue with what you wanted to understand and where the process stopped. Confusing instructions and unhelpful output are useful feedback too. For code and docs changes, see Contributing.

Go deeper

• Examples, commands, and source recovery
• Agent authoring guide and installable skill
• Multi-page sites and collections of explanations
• Model queries for agents and updates across repositories
• JavaScript API
• Release notes and migration guidance

Experimental source scanning

The experimental source scanner indexes source evidence separately from authored architecture models. JavaScript/TypeScript use compiler bindings; other supported languages use Tree-sitter syntax extraction. With Waxwing 0.3.0 installed, run:

waxwing scan /path/to/repository /tmp/project-scan.json --source-id my-project
waxwing scan-query /tmp/project-scan.json search loadModel
waxwing scan-view /tmp/project-scan.json /tmp/project-source.html

The source explorer includes a focused static graph. An optional connected site opens relevant implementation entries from system components or relationships, with exact source evidence and qualified recorded rationale. Try it on Waxwing:

npm run demo:connected -- /tmp/waxwing-connected

Open the generated site/index.html, choose a component, and follow its implementation link. Each level remains independently useful when no connection is recorded. The connected example describes what is curated and what the scanner establishes.

It reports unresolved bindings and skipped files. Source snapshots remain separate from authored architecture models. Baseline syntax profiles cover Python, Java, Kotlin, Go, C/C++, C#, Rust, Ruby, Swift, Objective-C, SQL, JSON, and shell. Syntax-only references remain unresolved; support is not equivalent across languages. Lean 4 and full Objective-C++ are future work. See the coverage table for limits. Scanning is experimental and is not included in 0.2.0.

Work on Waxwing

From a source checkout:

git clone https://github.com/isought/waxwing.git
cd waxwing
npm ci
npm test
npm run test:package

test:package installs a packed archive in a temporary directory and exercises its CLI, module imports, and source recovery. It needs npm registry access.

MIT licensed. Third-party notices.