Get started

Get started with codeweb — plugin, npx one-liner, or MCP server

Free & MIT-licensed. Runs entirely on your machine — no account, no server, no telemetry. Reads your code; never executes it.

Requires Node.js ≥ 22. That's it.
Zero required dependencies — an empty node_modules works.
Optional extras (a wasm grammar, ctags, ripgrep) sharpen extraction. Never required.

Recommended

Using Claude Code?

The plugin adds the /codeweb command, ambient pre-edit impact cards, and all 27 tools.

/plugin marketplace add GhostlyGawd/codeweb
/plugin install codeweb

Restart Claude Code, then run /codeweb on any project.

Using Cursor, Windsurf, or another MCP agent?

Register the same zero-dependency stdio server (JSON-RPC 2.0) — all 27 tools, no plugin.

claude mcp add codeweb -- \
  npx -y -p @ghostlygawd/codeweb codeweb-mcp

Shown with Claude Code's syntax — swap in your client's add-server command.

Just want the map — no AI involved?

One command from your project directory. Nothing to install, nothing to undo.

cd your-project
npx -y @ghostlygawd/codeweb .

~3 s for 3,000 symbols — open .codeweb/report.html when it finishes.

Not sure? Run the npx one-liner — it's the whole map, no install.

The interactive map codeweb builds — axios, 274 product symbols across 8 domains

~3 s for 3,000 symbols → this, for your repo. (Click it — that's the live axios demo.)

What success looks like — the run ends with a result, not a log:

[run] mapped 1668 symbols -> 14 actionable finding(s) · 6 ready merge(s)
[run] done -> your-project/.codeweb · codeweb v0.12.0
[run] next:  1. see the map: open .codeweb/report.html

Five-minute quickstart

From a cold repo to a queryable map

1 · Map it

Build the graph and the interactive report for a target.

node scripts/run.mjs ./my-app --out-dir ./my-app/.codeweb
# open ./my-app/.codeweb/report.html

2 · Query the graph

Ask what a change touches before you make it.

node scripts/query.mjs ./my-app/.codeweb/graph.json \
  --impact myFunction --json

3 · Guard the edit

Diff two snapshots and get a regression verdict.

node scripts/diff.mjs before.json after.json
# exit 1 on a new cycle, new duplication, or lost callers

4 · Gate the PR

Run the same verdict automatically on every pull request.

node scripts/ci-gate.mjs --base origin/main --target src

Or drop in the GitHub Action — see the CI gate.

Concepts

Five ideas that make the rest click

Node & edge

Every function, class, and method is a node; calls, imports, inheritance, and test links are edges. That graph is the substrate for every query.

Domain

Nodes are clustered into semantic domains so you can reason about subsystems, not just files. Cross-domain overlap is where consolidation lives.

Overlap

Two nodes that do the same work. codeweb confirms overlap by comparing bodies — same name with different bodies is dismissed, not flagged.

Blast radius

Everything transitively affected by changing a symbol. Ask for it before editing so you know what an edit can break.

The gate

A structural regression check: a change fails if it adds a cycle, adds a body-confirmed duplicate, or orphans a symbol. Pure removals always pass.

Severity

Findings carry confidence tiers — high, medium, low. High-confidence rows wear the accent in the report, so attention goes to what's actionable first.

Wire it into the loop: your agents call codeweb_find_similar before they write, codeweb_impact before they edit, and codeweb_review before they open a PR.

See all 27 tools Read the evidence