zzop

# zzop ( Zero Zone Of Pain )

[![CI](https://github.com/eezz4/zzop/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/eezz4/zzop/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@zzop/cli?logo=npm)](https://www.npmjs.com/package/@zzop/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

**Your AI coding agent can't read your whole codebase. zzop reads it — and answers the same way every
time.**

Point zzop at one repository, or at your frontend and backend together, and it returns a single JSON
document describing what is actually there: which frontend calls reach which backend routes and which
reach nothing, what looks risky, what is dead, where to refactor first — and what this run could not
see. An agent starts from that instead of guessing from the handful of files it had room to open.

zzop does not write code. It makes the *understanding* a code generator works from accurate and
repeatable — same commit in, byte-identical findings out — so what your agent writes rests on what your
code does rather than on what it inferred from a partial read. The thing being improved is
comprehension, not capability.

## See it break something

**[Break a route](docs/demo/break-a-route.md)** is the whole product in one change: rename
one backend route in a frontend/backend pair that share no code and no types. The frontend still
compiles, its tests still pass — and zzop names both ends of the break, file and line (abridged here;
the demo page shows the run's own format):

```
=== unprovided consumes ===
  "PUT /api/user"      @ fe-vite     src/pages/Settings.jsx:19    ← the call now hits nothing

=== unconsumed provides ===
  "PUT /api/users/me"  @ be-express  src/app/routes/auth/auth.controller.ts:61   ← the route nobody calls
```

**You can run that in seconds**, on a pair this repository ships and with nothing to fetch — the
demo pair is committed here, so clone this repository to get it:

```bash
git clone https://github.com/eezz4/zzop && cd zzop
bash docs/demo/break-a-route-shipped.sh    # needs a zzop binary and node, nothing else
```

The script finds a binary in `target/release/`, or any `zzop` on your `PATH`, and tells you how to
get one if it finds neither. It analyzes a temporary copy and never edits `docs/demo/pair/`.

It asserts the join state at each step instead of printing it, so it fails rather than narrating a
claim that has stopped being true. CI runs it on pushes to `main` and on pull requests; on a
development branch `scripts/ci-local.sh` is the lane that sees it.

The page itself is a **narrated walkthrough** of the same change on two independently-authored
repositories: every command and the output it produced are written out, so it
reads end to end without you running anything. The script behind it, `docs/demo/break-a-route.sh`, is a
maintainer tool rather than a first-run command — it builds a `cargo` example (so it needs a **source
checkout**, not a released binary) and analyzes two repositories **you supply** at
`corpus/oss/fe-vite` and `corpus/oss/be-express`. `corpus/oss/` is gitignored and nothing in this repo
ships those trees — they are third-party checkouts, not ours to redistribute; see
[CONTRIBUTING.md](CONTRIBUTING.md) on bringing your own corpus. (The synthetic corpus we *did* write
is committed, at [`cases/`](cases/README.md) — every file of it but one, a fixture
that has to carry a live vendor-token literal and so cannot be committed at all; its README says what
that costs the benchmark score.)

## Which of the two binaries do you want?

zzop ships as two Node-free binaries. Decide which one you need before you install anything:

| If you want | Use | How you drive it |
|---|---|---|
| An AI agent (Claude Code, Claude Desktop, any MCP client) to answer questions about your repos | **`zzop-mcp`** — an MCP server over stdio | Install the plugin or the `.mcpb` bundle and the agent calls the tools. You run no commands. → [Use in Claude Code](#use-in-claude-code-mcp-plugin) |
| To run analyses yourself — a terminal, a CI job, a script | **`zzop`** — a plain CLI | `zzop init` once per tree, then `zzop analyze .` or `zzop cross --config …`. JSON to stdout. → [Use in a terminal or CI](#use-in-a-terminal-or-ci-zzop-cli) |

Both binaries dispatch to the same shared handlers over the same engine, so a tool call and a CLI run
against the same path give the identical answer. Neither one makes a network request of any kind — they
carry no HTTP dependency at all ([privacy](https://eezz4.github.io/zzop/privacy.html)).

- Documentation site: <https://eezz4.github.io/zzop/> (authored in [`site-src/`](site-src/), generated by `scripts/gen-site.mjs`; [`site/`](site/) is the committed output — a guard rejects hand edits to it)
- Documentation (in-repo): [`docs/README.md`](docs/README.md)
- How it works, in depth: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- External parser protocol: [`docs/NORMALIZED_AST.md`](docs/NORMALIZED_AST.md)

## Quick start

Neither binary needs Node.js, npm, or a compiler. Get them one of four ways:

<!-- Canonical install-lane list for repo readers. docs/getting-started.md, docs/modules/mcp.md and
     VERSIONING.md link here instead of restating it; the site's Usage tab is the site-side twin (one
     copy per audience, not one per page) — its sentences live in site-src/content/usage.mjs and are
     generated into site/index.html, since site/usage.html became a redirect stub on 2026-08-14. Add a
     lane here first, then link. -->

- **Download the binaries.** Grab the `zzop-cli-<platform>[.exe]` (CLI) and/or `zzop-mcp-<platform>[.exe]`
  (MCP server) assets for your platform from [GitHub Releases](https://github.com/eezz4/zzop/releases)
  and run them directly, or put them on `PATH`. Each release also carries a `SHA256SUMS` asset covering
  every one of those assets. ⚠ **On an older pin there may be no release to download at all** — see
  [VERSIONING.md](VERSIONING.md) under *Breaking in the current `0.x`*, which is the one owner of which
  tags carry assets, and build from source for the ones that do not. (This sentence said the asset
  exists *"from v0.30.0 onward"* and told you to check on an older pin. Both halves were written
  before the 2026-09-23 history rewrite and neither survived it: for a tag between v0.30.0 and
  v0.34.0 there is nothing to check, because the release itself is gone.) Verify with
  `sha256sum -c SHA256SUMS --ignore-missing`, or `shasum -a 256 -c SHA256SUMS --ignore-missing` on a
  macOS box that has no `sha256sum`. Its scope is narrow and worth stating: it catches a corrupted
  download, and it is a hook for anyone who obtained the digest through another channel. It does
  **not** defend against a compromised release origin — an attacker who can swap an asset can swap
  `SHA256SUMS` beside it — and TLS already refuses MITM.
  **What each platform is actually verified to do differs, and it is worth knowing before you pick one.**
  The test suite runs on Linux x64 only. Every release build is smoke-tested by running `version` and
  comparing it against the manifest — on Windows x64, macOS arm64 and Linux x64; the two
  cross-compiled targets (macOS x64, Linux arm64) cannot execute on the runner that built them and
  are not smoke-tested at all. So on macOS and Windows what is proven is that the binary loads and
  links; the analysis behaviour is proven on Linux and assumed to carry. The engine has no
  platform-specific code path save one, which is why that assumption is a reasonable one and not a
  promise. The exception is worth naming because it is the case the assumption covers least well:
  `crates/summary/src/siblings.rs` folds directory names case-insensitively on Windows, because a
  case-insensitive filesystem would otherwise report a root you analyzed as its own unanalyzed
  sibling. The Windows arm of that fold is executed by nothing, anywhere: the suite runs on Linux,
  where the arm is not taken, and a developer mac cannot test the other arm either, because APFS is
  case-insensitive by default and the test skips itself with that reason. The source says so at the
  skip. Recount: `git grep -nE 'cfg!?\(\s*(not\()?\s*(windows|unix|target_os|target_family)' --
  'crates/**/*.rs' 'parser/**/*.rs' 'rules/**/*.rs' 'packages/**/*.rs'`.
- **Claude Code plugin.** `/plugin marketplace add eezz4/zzop`, then `/plugin install zzop@zzop` —
  see [Use in Claude Code](#use-in-claude-code-mcp-plugin) below. (Windows: the install hook needs a
  POSIX shell — Git for Windows is the supported path; details in
  [packages/README.md](packages/README.md#install-as-a-claude-code-plugin).)
- **Claude Desktop.** One-click `.mcpb` bundle (drag-and-drop install) — what an installer should
  know BEFORE installing (updates are manual; on macOS the unsigned binary is expected to hit
  Gatekeeper; the privacy statement) is [packages/mcpb/BUNDLE-README.md](packages/mcpb/BUNDLE-README.md) —
  bundles from releases after v0.32.0 carry that file as their own README; bundles up to and
  including v0.32.0 ship without it, which is exactly why the pre-install pointer here matters.
  Packaging internals: [packages/mcpb/README.md](packages/mcpb/README.md).
- **npm.** `npm i -g @zzop/cli` installs the exact same `zzop` binary above, fetched for your platform
  as an npm dependency — every subcommand `zzop help` lists, byte-for-byte the
  same output, no Node runtime involved beyond a tiny launcher script and no separate JS implementation
  that could drift from the native binary. Convenient when a project already manages its toolchain
  through npm. See [packages/cli/README.md](packages/cli/README.md).

## Use in Claude Code (MCP plugin)

The agent-facing lane. `zzop-mcp` is a self-contained binary with an MCP server built in; you install it
once and then ask questions in plain language — the agent picks the tool.

1. `/plugin marketplace add eezz4/zzop` — then `/plugin install zzop@zzop` (two separate s