See a feature in an app that you want in your own product? CRAB lets you rebuild it without ever looking at its implementation. One agent, the observer, studies the app as a black box. It records what the app accepts, refuses and defaults to, what it does at the edges, and how its screens are sequenced. CRAB turns that into falsifiable rules and claims and releases them as a sanitized spec. A second agent, the clean implementer, sees only that spec and writes its own implementation. It can check its work against the original, but it only ever gets back abstract pass/fail verdicts.

The valuable knowledge about a feature is behavioral. Tracing the implementation through binaries, minified bundles or obfuscated code is slow, brittle, and copies expression you don't want. CRAB never captures code, decompilation or stack traces. What it cannot observe becomes an explicit unknown, not a silent gap.

Both sides can run enforced, not just instructed. The observer works in a container whose only way to the target is CRAB's drivers. The implementer works in a container that sees only the spec. Every crossing goes through the gate and is recorded in a signed, hash-chained audit log.

Quick start

Install

uv tool install "crab-cleanroom[web]"   # Python 3.12+; the command is `crab`
crab install-browser                   # Chromium for web targets
crab demo                              # observe -> gate -> clean -> verdict on a built-in example

pip install "crab-cleanroom[web]" works too, and uv tool install "crab-cleanroom[web] @ git+https://github.com/lemonadesaltbagel/crab" installs the latest unreleased version. Docker is needed for CLI targets (each run is isolated in a container) and for the enforced rooms; an installed copy builds the room images from files it carries. Android needs the SDK and an emulator or device reachable through adb.

To work on CRAB itself, use a checkout: git clone https://github.com/lemonadesaltbagel/crab.git, then uv sync and uv run crab ....

Set up your agent

Register the observe server with your agent (Claude Code shown; any MCP client works):

claude mcp add crab-observe -- crab observe --project /path/to/project

From a checkout, use uv run --directory /path/to/crab crab observe ... instead.

Then ask:

Open web:http://localhost:3000/ as a research target and follow the observe_target playbook:
discover the UI, probe every field, inject API faults, state rules, close the coverage gaps
and release the spec.

The playbook (docs/observer-playbook.md) is served as the observe_target MCP prompt; the observer guide (docs/observer-guide.md) details every tool.

Review and release

crab review  --project P --feature F           # gate findings by class, coverage gaps
crab approve --project P --feature F --by you@example.com --class expected-output --reason test-oracle
crab release --project P --feature F
crab export-clean --project P --out KIT        # the kit: released spec + build/verify scaffolding

In strict mode every release needs your approval at a terminal, and the observer's tools cannot approve anything. In practice that is a few class-level decisions per release: approve the app text the clone must reproduce, approve the action names, acknowledge the coverage gaps the observer explained (docs/strict-gate.md).

Rebuild in the clean room

crab cleanroom up    --project P --kit KIT --claude-token-file ~/.config/crab-claude-token
crab cleanroom check --project P               # isolation probes, run from inside the container
crab cleanroom shell --project P -- claude     # the implementer sees only /kit; `verify` asks the gate
crab cleanroom down  --project P

crab observerroom confines the observer the same way (docs/clean-runtime.md).

How CRAB works

1. Observe. Drivers run the target and capture behavior only: outputs and file effects for CLIs, accessibility trees and API exchanges for web apps, accessibility trees for Android. A mapper turns each observation into a compact, wording-agnostic symbol. For web apps that symbol is versioned (web.aria/v10) and records everything a user-facing Playwright test can tell apart.
2. Generalize. UI discovery crawls every screen. The observer probes fields by equivalence class and boundary, injects faults (server errors, network failures, malformed bodies, unreadable files, airplane mode) and states rules in its own words. CRAB checks every rule against the original and records it as corroborated or falsified. Coverage lists what is left: each control, field, endpoint × fault, data state and live output, every route signed in and signed out, and record pages in each status. A release is refused until every item is exercised or explained.
3. Gate. The release is checked for copied expression (verbatim and near-verbatim matches against everything observed and every ingested document) and for real names, which become a codename. In strict mode, findings need your recorded approval.
4. Rebuild. The clean agent builds from the spec and asks the gate to verify its build. The gate runs the original and the clone through the same tests and returns pass/fail with abstract symbols, never the original's text or evidence.

What you can analyze

CRAB refuses to bypass protections and never captures implementation-tier data (see Responsible use).

Results

Each result was scored on a hidden test suite the observer never saw, against the original's own score under the same harness. How the evaluation works, and every result with its caveat, is in docs/evaluation.md.

• The clones reproduced their specs. What the hidden suites caught were things the spec did not contain.
• The web abstraction is built from a principle. It records every difference a user-facing Playwright locator or assertion can see, checked by an audit of page pairs that must differ and pairs that must not.
• The strict-gate rounds took a few class-level decisions at the person's own terminal per release. The audit log records each one.
• Famous targets measure the model's memory too. On jq, the same model with no spec at all did as well as with it. That is why the benchmarks use apps written for the purpose.

FAQ

Documentation

• Observer playbook: the loop the observer agent follows (also an MCP prompt).
• Observer guide: driving the dirty side for CLI, web and Android targets.
• Strict gate: reviewing findings and approving releases.
• Clean runtime: the enforced clean room and observer room.
• Evaluation: the benchmark method and every result with its caveats.

Responsible use

CRAB never:

• bypasses CAPTCHAs, bot protection, certificate pinning, root or attestation checks, or FLAG_SECURE;
• flips Electron fuses or re-signs binaries;
• uses fake accounts or exceeds configured rate limits;
• captures implementation-tier data (code bodies, decompilation, stack traces).

These refusals are not configurable. Observe only software you are allowed to observe, within its terms. You declare your purpose at intake and own the legal assessment.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the ground rules, and report anything that could let information cross the clean-room barrier privately through SECURITY.md. Changes are listed in CHANGELOG.md.

uv sync
uv run ruff check src tests
uv run pytest -q    # Android and desktop tests run when an emulator / the desktop image is available

License

Apache License 2.0. See NOTICE.

The license covers CRAB's own code and documents. CRAB grants no rights in the software you analyze: observing a target, and building and distributing anything from what you observed, remain subject to that target's terms and the law that applies to you.