codeweb

See what your AI edits affect.

npx -y @ghostlygawd/codeweb .

Structural checks for AI code changes. codeweb's gate buildsthe call graph before and after a change, then fails the pull request on three regressions: a newdependency cycle, a new body-confirmed duplication, or an existing non-exported symbol thatbecomes an orphan with no mapped callers. Gate conditions and limits.

No LLM is in the checks. The gate uses zero model tokens for its static analysis.A passing check does not prove the program works. Analysis can miss dynamic relationships;inspect unresolved results and run the relevant tests. Pure removals pass the structural rules.

The verdict uses the mapped graph, not a model, and costs zero LLM tokens. Exported symbols are exemptfrom the diff’s orphan check. Inspect analysis.checks: skippedchecks are not passes, and refresh drops the evidence needed to evaluate duplication.

A green result does not establish complete dependency coverage or behavioral correctness.Pure removals do not count as structural regressions.Put it on your PRs →

The gate needs a map to compare, and that map is worth reading on its own.

codeweb reads your code. It maps supported functions and the calls it can resolve between them. It maps3,000 symbols in approximately 3 seconds. Static analysis produces the same map from thesame code. No LLM is in the mapping loop.

Static extraction can omit unsupported layouts,ambiguous calls, and runtime dispatch; the map is not a completeness guarantee.

Your coding agents query the map instead of using grep. In measured tests, agents that used grepmissed more than half of a function's real callers(see the measurements). An incomplete callerlist can cause an agent to break code that it did not inspect.

• Give agents structural data: The Model Context Protocol (MCP) server provides 28 tools,including codeweb_impact, codeweb_callers, and codeweb_find_similar.
• Keep answers small: Each query returns a bounded structural answer. Your agents can usetheir remaining context for implementation work.
• Inspect the same data: The interactive report shows the extracted codebase map.

The map also shows relationships that are not visible in one file. These relationships includeduplicated logic, dead code, hotspots, and tangled domains.

Try it on your repo

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

For a repository with 3,000 symbols, the first map takes approximately 3 seconds. Open.codeweb/report.html to inspect the map.

Gate every pull request

From a Codeweb source checkout, run the verdict locally; the GitHub Action can run it on every pull request:

node scripts/ci-gate.mjs --base origin/main --target src   # exit 1 on a structural regression

The gate builds the graph from the pull request base and from its head, then diffs them. It postsa sticky structural review comment either way, so reviewers see the blast radius withoutinstalling anything.

Pin the Action to a release tag, not a moving branch: a floating ref can change your gate'sverdict semantics under you. Pin codeweb-ref to the same tag so the engine is fixed too. Theworkflow YAML, the monorepo matrix form, and every input live indocs/ci-gate.md.

Want the gate hosted — no workflow YAML, cached base graphs, and history across every repo in theorg? That is the planned scope of codeweb Teams, the paid half ofthe boundary. Running it yourself stays free forever.

See it in action

Each screenshot below shows a generated report for axios (280 symbols, 7 domains).The screenshots are not mockups.

codeweb found 3 real duplications in axios and rejected 12 false positives. Readthe case study, orinspect the live map.

Know what an edit breaks — before you write

Select a function in the live map. The map highlightsthe function's blast radius and shows the symbols that the change can affect.

Your agents can get the same answer from the codeweb_impact MCP tool before they edit the code.

Navigate the whole system

The force-directed map shows the extracted symbols. You can collapse symbols into domains. Search, drag,zoom, or select a node to trace its callers and dependencies.

Findings — stop guessing what to refactor

The Findings tab ranks duplication, highly connected hotspots, and likely dead code.Select a row to inspect the symbol's callers and dependencies.

See duplication density, and where domains tangle

codeweb works at symbol resolution. It maps functions, classes, methods, and the call andimport edges between them. A file-level scanner can show that two modules are similar. codewebcan show that two functions do the same work, identify their callers, and calculate the effect ofa merge.

Benchmarks

• Find callers before an edit: In the v0.9.0 efficiency pilot, agents found 74% of afunction's real callers with codeweb and 44% with grep at the same context spend. A missedcaller can cause an edit to break working code.
• Calculate the effect of a change: One codeweb call returned one small answer. A simulatedgraph-assisted grep loop used 126 times the context size in the recorded comparison.This measures context-size differences, not total agent-session token savings.
• Detect duplicate code: codeweb found every planted duplicate with zero false alarms,including renamed copies. Text search found 0% of the renamed copies.
• Check deterministic results: Tests compared codeweb with the TypeScript compiler and otherindependent implementations more than 490,000 times, with zero disagreements.
• Map and query quickly: The first map takes approximately 3 seconds for a repository with3,000 symbols. Queries take approximately 0.1 seconds. A repository with twice as manysymbols takes approximately 1.3 times as long to map.
• Understand the limits: A new map after a very large edit can take more time. Agents alsocompleted simple tasks successfully without codeweb.

Methodology, raw data, and per-claim receipts:the evidence ledger. Benchmark your ownrepo from a Codeweb source checkout: npm run bench -- <path>/.codeweb/graph.json. CI re-runs the performance budgets onevery PR; breaking a published number fails the build.

codeweb also keeps a local activity tally. From a Codeweb source checkout, run npm run stats to see it:

codeweb this month: 41 pre-edit card(s) · 5 card-named caller(s) followed · 2 regression(s) flagged · 120 queries served

To evaluate a dependency, point codeweb at a repository that you do not own:/codeweb https://github.com/owner/repo. codeweb makes a read-only clone, maps the clone, andadds an adoption review. codeweb does not execute the target code.

Install

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

• codeweb requires Node.js ≥ 22.
• codeweb has zero required dependencies. CI verifies operation with an empty node_modulesdirectory.
• The optional web-tree-sitter wasm grammar improves extraction. codeweb does not require it.
• CI publishes releases with npm provenance. Run npm audit signatures to verify a release.

Using Claude Code? Install the plugin to add the /codeweb command, automatic pre-editimpact cards, and all 28 tools:

/plugin marketplace add GhostlyGawd/codeweb
/plugin install codeweb

Restart Claude Code to register the /codeweb command, agents, and skill.

Using Codex? Install the bundled coding skill and local MCP server:

codex plugin marketplace add GhostlyGawd/codeweb
codex plugin add codeweb@codeweb

Reload Codex, then use $codeweb to inspect callers before an edit, compare existingimplementations, or review a structural change. The plugin uses your existing tool permissions.

The plugin/MCP workflow is verified with Codex CLI 0.159.2 and 0.160.0. If a client does not exposebundled tools, use the standalone MCP recipe below with the coding skill. Manage each configuredentry when disabling or removing Codeweb. This workflow does not claim automatic hook delivery.

Choose your MCP client: The setup pageprovides one recipe for Claude Code, Cursor, Windsurf, Gemini CLI, or Codex. Print a recipeand check local setup from your project:

npx -y @ghostlygawd/codeweb setup --client cursor
npx -y @ghostlygawd/codeweb doctor

Setup prints configuration without replacing files. Doctor checks the local server and graph;a successful local check does not prove an editor connection. Restart your client, ask youragents to run codeweb_callers, and check a returned source location.

Map a repository without an AI agent: Run one command from your project directory:

cd your-project
npx -y @ghostlygawd/codeweb .    # ~3 s for 3,000 symbols — then open .codeweb/report.html

For a temporary evaluation, use the npx command. It creates the map without a permanentinstallation.

Run the engine from a clone:

git clone https://github.com/GhostlyGawd/codeweb.git
node codeweb/scripts/run.mjs /path/to/your/project

docs/cli.md lists each executable, flag, and exit code.

VS Code: editor/vscode-codeweb shows anN callers · blast M lens above each mapped symbol. Select the lens to open the report.

What you can do

Each link lands on full docs, flags, and examples in the reference.

• Know before you edit: Find callers, calculate the effect of a change, and check for anexisting implementation.→ Query the graph ·context & pre-flight
• Gate every edit: Get a structural regression result for an edit, pull request, orarchitecture rule.→ The diff verdict ·the PR gate ·the capability suite
• Clean up, ranked: Rank consolidation and dead-code work by evidence.→ optimize ·hotspots ·campaign ·trend

Use

/codeweb                                  # map the current project
/codeweb src/payments --depth symbol      # deep-dive one subsystem
/codeweb https://github.com/owner/repo    # external review before adopting
/codeweb owner/repo --open                # clone, map, and open the report

Available flags include --depth module|symbol|auto, --engine hybrid|read|tools,--focus <glob>, --mode internal|external, and --open. See commands/codeweb.md for details.

codeweb writes all outputs to <target>/.codeweb/. Agents and other tools can read graph.json.You can open report.html. codeweb also creates Markdown versions.See the description of each output file.

Use it as an MCP tool

scripts/mcp-server.mjs is a zero-dependency Model Context Protocol (MCP) stdio server. It givesMCP clients access to 28 tools. The tools help the client orient, read the structure,check before writing, gate an edit, and plan cleanup.

The September 14 packaged assessmentexercised the baseline loop with Codex CLI 0.154.0; it did not certify every tool in everyclient. Claude runtime compatibility and other clients were not tested in that assessment.See the recorded scope.

The plugin registers the server automatically. To register the standalone server, run:

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

Requires Codeweb 0.15.0 or later. Use the installed MCP server, or register a sourcecheckout using its absolute path as shown in the reference.

The loop an agent runs:

1. Orient with codeweb_brief (or codeweb_find when no symbol name is known).
2. Before editing, call codeweb_refresh {baseline:true} once to capture fresh source.Ask codeweb_explain, then codeweb_context, codeweb_impact, or codeweb_dependentsabout the symbol before changing it.
3. After editing, call codeweb_diff {before:"baseline",refresh:true}.
4. If red, repair the code and repeat that same diff against the same baseline.Do not capture another baseline during repair: baseline:true replaces the original.Ordinary and automatic refreshes preserve it. Start a new baseline for the next task.

Known unsupported same-line JS/TS declarations produce status: "inconclusive" andok:false instead of a clean gate. Inspect the diagnostic locations and callers in source.The detector covers known layouts; no diagnostic does not prove complete extraction.

Read analysis.checks: a skipped check is not a pass. Refresh drops overlap evidence, sothis loop does not evaluate duplication; structural green does not prove behavioralcorrectness. Run the project's tests too. If the baseline is missing, edited source cannotreconstruct it — recover the pre-edit source before beginning again.

For npm v0.14.0, use the snapshot quickstart.For the unreleased checkout, try the tiny cycle → repair → green walkthrough.Clients that hide the server's built-in instructions can pastethe rules snippet instead.

The server includes these agent-specific features:

• Optional graph argument: The server finds the nearest map when you omit graph. If no mapexists, the error directs the agent to codeweb_map.
• Budgeted responses: Responses include the highest-ranked items and the true totals. A contextresponse that was approximately 300 KB is now approximately 10 KB.
• Staleness information: A stale result identifies its state and directs the agent tocodeweb_refresh — on the orient tools and on every spawned advisor answer.

All 28 tools, grouped and explained →

How it works

For JavaScript, TypeScript, Python, Rust, Go, Java, C#, Ruby, PHP, Kotlin, Swift, C, and C++,codeweb uses a deterministic Node pipeline by default. One command creates the map. No LLM isin the pipeline, and the same input produces the same bytes.

The map pipeline has the four stages in the following diagram. scripts/run.mjs also createsoptimize.md after overlap analysis and before report rendering.

1. Extract (extract-symbols.mjs) parses each source file into atomic nodes such as functions,classes, and methods. It also records call and import edges. If a bare call can refer to morethan one definition, codeweb omits the edge instead of guessing. Per-file caching makesextraction incremental and byte-identical to a full rebuild. An imported .json file entersthe map as a file-level node without being parsed. An unreferenced .json file stays out of themap, which prevents lock-file noise.
2. Cluster (cluster3.mjs) removes genuine utility hubs and groups the remaining nodes intodirectory-anchored semantic domains.
3. Overlap (overlap.mjs) detects duplicated logic and parallel implementations. It compareseach candidate with the actual function bodies by using token-shingle similarity. This checkprevents name coincidences from becoming findings. A structural pass overidentifier-normalized skeletons also finds renamed Type-2 clones(find-similar --structural).
4. Render (build-report.mjs) converts graph.json into the self-contained report.html andreport.md files.

For a language that the extractor cannot parse, codeweb uses the agent path.codeweb-dissector agents extract nodes and edges for each subsystem. codeweb-domain-mapperthen assigns domains and overlaps.

Both paths produce the same graph.json schema. In external mode, each path also adds anadoption verdict.

Versus a language server (LSP): an LSP answers one hop on demand — definitions, directreferences — inside an editor session. codeweb builds one deterministic whole-graph artifact:transitive impact, duplication with body evidence, dead code, and domain coupling.

Agents query that artifact over MCP, and CI diffs it to gate a PR. The two compose — codewebreplaces the grep loop, not your language server.

Choose a reading path in the documentation index, which also explainsrepository ownership. The component map details the engine.

Roadmap

• Support more first-class languages: codeweb currently supports thirteen native languages:JavaScript, TypeScript, Python, Rust, Go, Java, C#, Ruby, PHP, Kotlin,Swift, C, and C++. Other languages use the agent fallback. Dynamic-dispatch AST tierscover JS/TS, Java, C#, Python, Go, Rust, Ruby, PHP, C, and C++. Kotlin and Swiftdispatch requires a trusted wasm grammar at the pinned ABI. See scripts/grammars/PROVENANCE.md.

Recent releases added the agent-intelligence suite (hotspots, campaign,reading-order, Type-2 clone detection, and suppression memory), alive interactive demo, Go and Rust on the fastpath, duplication trend data, and the one-command CI regression gate with a GitHub Action.codeweb currently provides 28 tools.

Versioning & releases

The maintenance commands below require a Codeweb source checkout.

codeweb follows Semantic Versioning. It records changes inCHANGELOG.md, which uses theKeep a Changelog format. Each capability, benchmark, and fix shipsin a tagged GitHub release.

package.json is the source of truth for the version.scripts/mcp-server.mjs is the source of truth for the MCP tool count. The release tools deriveand verify the other values:

npm run version-sync        # propagate version + tool count -> plugin.json, SKILL.md, README badge
npm run check-consistency   # fail if any public-facing surface has drifted
npm run build:site          # regenerate the docs/ website (zero-dependency, deterministic)
npm run release -- --minor  # roll the changelog, bump, sync, rebuild; prints the git/tag steps

check-consistency runs in CI. It gates version strings on every surface, recognized prose patterns forthe tool and language counts, the CHANGELOG entry for the current version, and every evidencefile the ledger cites.

About

Built by GhostlyGawd. AI agents helped write much of the code.The commit co-author trailers identify those contributions. Open an issue for questions orproblems. Use SECURITY.md to report a security issue.

Stay current: codeweb does not contact an update service. To receive release notifications,select Watch → Custom → Releases on GitHub.

Free forever, and where the paid line sits

The rule, ratified in CHARTER.md: anything that runs on one laptop against onerepo is free forever; money buys hosting, multi-repo aggregation, and human attention.

Everything in this repository is that free half — the map, the MCP tools, the hooks, the report,the CLI, the self-hosted gate Action, and every language codeweb learns. MIT, no accounts, notelemetry, no license keys. Nothing here moves behind a payment later.

The planned paid half is a separate hosted service, codeweb Teams: the gate run for you, and historyheld across every repo in an org. Billing lives only in that service, so a payment problemdegrades the hosted tier and never breaks your local tooling or your CI.

Hosted availability is not established by this repository’s local checks. The pricing pageretains the sign-up doorway.

Read the full contract onthe boundary page, and the planned Teamsprice on the pricing page.

Support the project

Sponsoring supports the project. Sponsorship alsoprovides advertising. Top sponsors can put their logo at the top of this README, and each sponsorcan join the supporters list. See thesupport page for details.

Running codeweb at an organization and need help? Send email through the GitHub profile.

Handoffs

You can send codeweb outputs to refactor-cleaner, codebase-onboarding, or code-tour if youhave those tools. codeweb does not require them.

For a useful next step, apply the highest-ranked ready merge from optimize.md. Then runcodeweb again and compare the findings count.