zzop ( Zero Zone Of Pain )

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

That page is a narrated walkthrough: 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 on bringing your own corpus. (The synthetic corpus we did write is committed, at cases/ — 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:

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

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

Quick start

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

• 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 and run them directly, or put them on PATH. Each release also carries a SHA256SUMS asset covering every one of those assets — from v0.30.0 onward; releases up to and including v0.29.1 do not have one, so on an older pin check that the file is there before relying on it. 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.
• Claude Code plugin. /plugin marketplace add eezz4/zzop, then /plugin install zzop@zzop — see Use in Claude Code below. (Windows: the install hook needs a POSIX shell — Git for Windows is the supported path; details in packages/README.md.)
• 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 — 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.
• 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.

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 steps).
2. Start a new session. The plugin downloads the binary for your platform on first run; nothing goes on PATH. That first session does not list the zzop tools yet — the tool list is settled before the download finishes — so restart Claude Code once and they appear (the hook says so on stdout too). Once installed, a newer release is reported to you, never installed behind your back.

The server exposes the tools analyze_repo, cross_repo, check_file, check_endpoint, analyze_envelope, validate_envelope, validate_rule_pack — plus the zzop://contract/* resources carrying the authoring contracts (among them the envelope schema, the DSL reference, the rule catalog, the config surface and an annotated starter config), so an adapter or rule pack can be written with nothing but the binary. zzop-mcp itself takes no analysis subcommands: bare or mcp serves stdio, and version/help are the only other forms.

See packages/README.md for the full install/tool/resource reference, and docs/modules/mcp.md for exact argument shapes.

Use in a terminal or CI (zzop CLI)

The human-facing lane. Write a zzop.config.jsonc and run it, ESLint-style. A config is required — every analysis lane refuses a tree that has none, on both binaries alike, because the names zzop would otherwise guess about your project (what you call your auth guards, which banners mark your generated files) live in that file, and a key you do not declare is a judgment zzop does not make:

zzop init                               # write the starter config — do this first, once per tree
zzop analyze .                          # analyze one repo/tree -> JSON findings summary
zzop analyze --config ci/zzop.config.jsonc   # same, for a config that does not sit at the tree root
zzop analyze . --severity critical --limit 10  # narrow the findings LIST (counts always cover everything)
zzop cross --config zzop.config.jsonc   # cross-layer join, driven by that config
zzop analyze . --fail-on critical       # THE CI GATE: exit 3 when anything at/above that severity exists
zzop <subcommand> --help                # that one subcommand's own line (exit 0); `zzop help` prints them all

zzop --help is the canonical subcommand list — this README does not repeat it.