codeweb

<div align="center">

<img src="assets/brand/banner.png" alt="codeweb — See what your AI edits affect." width="100%">

[![CI](https://github.com/GhostlyGawd/codeweb/actions/workflows/ci.yml/badge.svg)](https://github.com/GhostlyGawd/codeweb/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40ghostlygawd%2Fcodeweb?style=flat-square&color=c6f24e)](https://www.npmjs.com/package/@ghostlygawd/codeweb)
[![license: MIT](https://img.shields.io/npm/l/%40ghostlygawd%2Fcodeweb?style=flat-square&color=8a8794)](LICENSE)

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

**[Website](https://ghostlygawd.github.io/codeweb/)**&nbsp;·&nbsp;[Gate every PR](#gate-every-pull-request)&nbsp;·&nbsp;[See it in action](#see-it-in-action)&nbsp;·&nbsp;[Install](#install)&nbsp;·&nbsp;[Use](#use)&nbsp;·&nbsp;[For agents (MCP: Model Context Protocol)](#use-it-as-an-mcp-tool)&nbsp;·&nbsp;[How it works](#how-it-works)&nbsp;·&nbsp;[Free forever](#free-forever-and-where-the-paid-line-sits)&nbsp;·&nbsp;[Changelog](CHANGELOG.md)

[![Try it with npx](https://img.shields.io/badge/Try_it_with_npx-060608?style=for-the-badge&logo=npm&logoColor=c6f24e)](#try-it-on-your-repo)
[![Open the live demo](https://img.shields.io/badge/Open_the_live_demo-060608?style=for-the-badge&logoColor=c6f24e)](https://ghostlygawd.github.io/codeweb/demo/)
[![Install the Claude Code plugin](https://img.shields.io/badge/Install_the_Claude_Code_plugin-060608?style=for-the-badge&logoColor=c6f24e)](#install)

</div>

**See what your AI edits affect.**

```bash
npx -y @ghostlygawd/codeweb .
```

<div align="center">
<a href="https://ghostlygawd.github.io/codeweb/downloads.html"><img src="assets/metrics/npm-downloads.svg" alt="Latest seven-day npm download total with a line chart of completed daily downloads for @ghostlygawd/codeweb, generated from the public npm downloads API" width="100%"></a>
<br><sub>The large number is the latest seven completed days; the line shows daily downloads. Package downloads are retrievals, not a count of users. Select the chart for the live data and reporting cutoff.</sub>
</div>

**Structural checks for AI code changes.** codeweb's gate builds
the call graph before and after a change, then fails the pull request on three regressions: a new
dependency cycle, a new body-confirmed duplication, or an existing non-exported symbol that
becomes an orphan with no mapped callers. [Gate conditions and limits](docs/ci-gate.md).

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 exempt
from the diff’s orphan check. Inspect `analysis.checks`: skipped
checks 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 →](#gate-every-pull-request)

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 maps
3,000 symbols in approximately 3 seconds. Static analysis produces the same map from the
same 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 grep
missed more than half of a function's real callers
([see the measurements](https://ghostlygawd.github.io/codeweb/research.html)). An incomplete caller
list 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 use
  their 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 include
**duplicated logic, dead code, hotspots, and tangled domains**.

<div align="center">
<a href="https://ghostlygawd.github.io/codeweb/research.html"><img src="assets/brand/proof-strip.svg" alt="Measured codeweb results: agents found 74% of real callers with codeweb and 44% with grep at the same context spend; impact answers had 126 times smaller context size than a simulated graph-assisted grep loop; more than 490,000 deterministic comparisons had zero disagreements" width="100%"></a>
<br><sub>Measured against fixed tasks and independent oracles. Select the proof strip for the methodology and receipts.</sub>
</div>

---

## 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.

<div align="center">
<img src="assets/screens/zod-terminal-run.svg" alt="Condensed real terminal run of codeweb 0.12.0 on Zod commit 912f0f5: 1,388 symbols and 1,616 edges from 409 files, followed by 66 actionable findings" width="840">
<br><sub>Real run against <a href="https://github.com/colinhacks/zod/tree/912f0f51b0ced654d0069741e7160834dca742ee">Zod at commit <code>912f0f5</code></a>, captured 2026-07-29. The replay shortens the absolute local path to <code>.codeweb</code>; the displayed values are unchanged.</sub>
</div>

## 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 posts
a sticky structural review comment either way, so reviewers see the blast radius without
installing anything.

**Pin the Action to a release tag**, not a moving branch: a floating ref can change your gate's
verdict semantics under you. Pin `codeweb-ref` to the same tag so the engine is fixed too. The
workflow YAML, the monorepo matrix form, and every input live in
[`docs/ci-gate.md`](docs/ci-gate.md).

Want the gate hosted — no workflow YAML, cached base graphs, and history across every repo in the
org? That is the planned scope of [codeweb Teams](https://ghostlygawd.github.io/codeweb/pricing.html), the paid half of
[the boundary](#free-forever-and-where-the-paid-line-sits). Running it yourself stays free forever.

## See it in action

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

codeweb found 3 real duplications in axios and rejected 12 false positives. Read
[the case study](docs/case-study-axios.md), or
[inspect the live map](https://ghostlygawd.github.io/codeweb/demo/).

### Know what an edit breaks — before you write

Select a function in the [live map](https://ghostlygawd.github.io/codeweb/). The map highlights
the 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.

<div align="center">
<img src="assets/screens/axios-blast-radius.png" alt="codeweb blast radius: AxiosError selected in the axios graph — the selected block wears the accent with a viewfinder frame, blast edges lit across three domains, 27 callers listed in the inspector" width="760">
<br><sub>Selecting <code>AxiosError</code> in axios lights up its <b>31 callers across the domains that depend on it</b> — try it yourself in the <a href="https://ghostlygawd.github.io/codeweb/">living map</a>.</sub>
</div>

### 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.

<img src="assets/screens/axios-graph.png" alt="codeweb Graph tab on axios: eight domain blocks (helpers, core, adapters, cancel, defaults, platform) sized by symbol count and linked by stippled call edges" width="100%">

### 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.

<img src="assets/screens/axios-findings.png" alt="codeweb Findings tab on axios: ranked duplication, hotspots, and likely-dead code, with a clickable detail panel" width="100%">

### See duplication density, and where domains tangle

<table>
<tr>
<td width="50%" valign="top">
<img src="assets/screens/axios-treemap.png" alt="codeweb Treemap on axios: every file sized by lines of code, duplication density carried by a dark-to-lime lightness ramp">
<br><b>Treemap</b> — The size of each block shows the file's lines of code. A brighter block
contains more duplicated code. Use the bright blocks to identify possible consolidation targets.
</td>
<td width="50%" valign="top">
<img src="assets/screens/axios-matrix.png" alt="codeweb Matrix on axios: a heatmap of call coupling between domains">
<br><b>Matrix</b> — The matrix shows coupling between domains. A large off-diagonal cell shows
strong coupling. You can merge the domains or add a clear interface between them.
</td>
</tr>
</table>

<div align="center">
<img src="assets/brand/demo.svg" alt="The codeweb pipeline: extract → cluster → overlap → render, looping" width="840">
<br><sub>The deterministic pipeline, looping: extract → cluster → overlap → render.</sub>
</div>

---

codeweb works at **symbol resolu