Coverage dashboard for binary-matching decompilation projects.
See every byte. Track every match. Ship the decomp.

Install · Quick Start · Screenshots · Potato Mode

recoverage serves a local web dashboard that visualises per-byte match status across .text, .data, .bss, and other PE sections of a decompilation project. Think of it as a defrag map for your decomp — every byte of the original binary is a cell in a grid, colored by how closely your C code matches the original compiled output.

• Byte-Perfect Confidence: Stop guessing if your C code produced the correct assembly. See exact byte comparisons visually.
• Fast Iteration: Quickly identify which parts of a function are matching and which parts have diverged (e.g. register allocation differences, instruction reordering).
• Interactive Triage: Click any block in the grid to immediately view the corresponding C source, disassembled binary, and hex diff.

Potato Mode is a zero-JavaScript, server-side rendered HTML fallback. Every view is a plain HTML table — no CSS, no JS — so it works on low-spec machines, restricted browsers, or anywhere you just want a quick glance without loading the full SPA.

pip install recoverage

For development:

uv pip install -e .

Install an extra to enable its feature: pip install 'recoverage[<extra>]' (or uv sync --extra <extra> in a workspace).

# 1. Generate the coverage database (from your project directory)
uv run rebrew catalog --json
# Analyzes the target binary, parses your annotations, and dumps raw match data to db/data_*.json

uv run rebrew build-db
# Consumes the JSON files and builds a fast SQLite database (db/coverage.db) for the dashboard

# 2. Start the dashboard
uv run recoverage serve
# Starts a lightweight Bottle web server serving the frontend SPA and providing the API backend

Start the dashboard web server.

Print per-section coverage stats as a Rich table, or as JSON with --json.

recoverage stats                    # all targets
recoverage stats --target SERVER    # single target
recoverage stats --json             # machine-readable

Export coverage data to stdout.

recoverage export --format json     # JSON (default)
recoverage export --format csv      # CSV
recoverage export --format md       # Markdown table

CI gate — exits non-zero if coverage is below a threshold. Sections the grid never records matches for (e.g. .bss/.data when only .text matches are tracked) are skipped, not failed.

recoverage check --min-coverage 60                              # all targets, all sections
recoverage check --min-coverage 60 --target SERVER --section .text   # specific
recoverage check --min-coverage 60 --json                       # machine-readable verdict

Exit codes: 0 = gate passed, 1 = coverage below threshold (or bad input), 2 = infrastructure error (database missing/unreadable).

Re-run rebrew catalog + rebrew build-db to regenerate coverage.db.

recoverage regen

Open the dashboard in a browser (useful when --no-open was used).

recoverage open --port 8001

recoverage is designed as a standalone consumer of the data that rebrew produces — the two packages are intentionally decoupled.

rebrew catalog --json          rebrew build-db           recoverage (Bottle + SQLite)
       │                             │                       │
  db/data_*.json  ──────────▶  db/coverage.db  ──────────▶  VanJS Dashboard

1. rebrew catalog --json: Scans your project's source annotations and writes intermediate db/data_*.json files containing coverage metrics. Jump table / switch data bytes are absorbed into their parent function's size. Use --export-ghidra-labels to generate ghidra_data_labels.json for round-trip Ghidra sync.
2. rebrew build-db: Consumes those JSON files and builds a structured db/coverage.db (SQLite v4 schema) database, storing per-function metadata (detected_by, size_by_tool, textOffset), per-global metadata (module, size), per-cell metadata (label, parent_function), and stamping db_version for schema detection. See DB_FORMAT.md for the full schema.
3. recoverage: Starts a Bottle web server. The backend serves API endpoints querying the SQLite database, while the frontend is a zero-build Single Page Application (SPA) powered by VanJS, rendering the interactive defrag grid.

You can run recoverage independently on any machine (or even host it remotely) as long as it has access to a compiled coverage.db — no rebrew dependency or compiler toolchain is required.

recoverage/
├── pyproject.toml
├── README.md
├── docs/                     # Screenshots, mascot & design doc
│   ├── DESIGN.md             # Detailed architecture & design doc
│   ├── DESIGN_PRINCIPLES.md  # Core operational philosophies
│   ├── USER_STORIES.md       # User stories with acceptance criteria
│   └── ideas.md              # Future improvement ideas
├── tests/
│   ├── conftest.py           # Shared fixtures (synthetic coverage.db)
│   ├── test_api.py           # API validation & security tests
│   ├── test_cli.py           # CSV export, formatting tests
│   ├── test_lifecycle.py     # Process lifecycle (regen timeouts, opener reaping)
│   ├── test_paths.py         # DB path resolution tests
│   ├── test_server.py        # Compression, encoding tests
│   ├── test_potato.py        # Potato Mode rendering tests
│   └── test_playwright.py    # Browser integration tests
└── src/recoverage/
    ├── __init__.py
    ├── __main__.py           # python -m recoverage
    ├── _paths.py             # DB path resolution (rebrew-project.toml db_dir)
    ├── cli.py                # Typer CLI entry point
    ├── server.py             # Bottle app, shared helpers & compression
    ├── regen.py              # rebrew regen subprocess lifecycle (group kill + reap)
    ├── api.py                # REST API routes (/api/*)
    ├── ui.py                 # UI routes (/, /potato, static files)
    ├── potato.py             # Potato Mode renderer
    ├── webapp.py             # Composition root: imports api+ui so app has every route
    └── assets/
        ├── index.html        # SPA shell
        ├── style.css         # All styles
        ├── print.css         # Print stylesheet
        ├── app.js            # VanJS frontend
        ├── detail.js         # Deferred panel logic (hex dump, modal, live reload)
        ├── van.min.js        # VanJS library (~2 KB)
        ├── favicon.svg       # Retro "R" logo favicon
        ├── hljs.min.js       # Highlight.js core
        ├── hljs-c.min.js     # Highlight.js C grammar
        ├── hljs-x86asm.min.js # Highlight.js x86 asm grammar (hex lang is in detail.js)
        └── hljs.css          # Highlight.js theme

The browser libraries under src/recoverage/assets/ are vendored so the dashboard works air-gapped (see docs/DESIGN.md); nothing is fetched from a CDN at runtime. Licenses and versions are recorded here because the minified blobs themselves carry little provenance:

hljs.css is a first-party theme (not upstream Highlight.js CSS). When re-vendoring any of these files, keep the upstream license banner in the minified output so this table stays verifiable against the blobs.

MIT