screpdb

README

screpdb

screpdb is an advanced Starcraft replay reporting tool.

English | 한국어

_{28.88 ms/replay · corpus: 166 replays · GitHub-hosted 2-core runner · updated automatically on merge to main}

▶️ Try it in your browser — the full dashboard on sample replays, no install, runs entirely client side.

⬇️ Install on Windows: download screpdb and open it. If Windows says it protected your PC, click More info → Run anyway.

macOS, Linux and other options: see Installation.

Features

Filtering and finding replays by high-level semantic features

Game summary: each player's noteworthy semantic events and unit composition

Rich game events browser with map overlays

Hotkey intel: what each player keeps on which key, all game long

…and the hotkeyed buildings drawn on the map where they were built

Build order detection, de-duped and charted against usual progamer timings

Built-in progamer profiles alongside the players in your own library

Skill proxies: viewport multitasking, unit production cadence, first unit efficiency

Per-player hotkey signature, including the built-in progamers

Alliance timeline and team stacking detection on multiplayer melee games

Installation

Windows

Download screpdb and open it. If Windows says it protected your PC, click More info → Run anyway. screpdb moves itself out of Downloads, adds Start Menu and Desktop shortcuts, and opens in your browser.

Trouble opening it?

The app is not code-signed, so:

• Defender or other antivirus may quarantine it (a known false positive for unsigned Go binaries). Restore it from Protection History.
• Work PCs with AppLocker or WDAC may block it outright.

Linux

curl -fsSL https://raw.githubusercontent.com/marianogappa/screpdb/main/install.sh | sh

Or with Homebrew / Linuxbrew:

brew install marianogappa/screpdb/screpdb   # upgrade later: brew update && brew upgrade screpdb

Then run screpdb. Upgrade by re-running the installer or with the in-app Update button.

Read the installer first, or install manually

install.sh is short and dependency-free: it downloads the binary for your OS/arch, checks it against the release's signed SHA256SUMS, and copies it to ~/.local/bin. To audit before running:

curl -fsSL https://raw.githubusercontent.com/marianogappa/screpdb/main/install.sh -o screpdb-install.sh
less screpdb-install.sh
sh screpdb-install.sh

Or download the binary from the Releases page yourself:

chmod +x screpdb-linux-amd64                              # or screpdb-linux-arm64
mkdir -p ~/.local/bin && mv screpdb-linux-amd64 ~/.local/bin/screpdb

macOS

brew install marianogappa/screpdb/screpdb   # upgrade later: brew update && brew upgrade screpdb

Or, without Homebrew:

curl -fsSL https://raw.githubusercontent.com/marianogappa/screpdb/main/install.sh | sh

Then run screpdb. Neither method triggers the Gatekeeper "unidentified developer" block.

Prefer a direct download? (this one does hit Gatekeeper)

Download the binary for your Mac from the Releases page, then:

chmod +x screpdb-darwin-arm64                          # or screpdb-darwin-amd64
xattr -d com.apple.quarantine screpdb-darwin-arm64     # clear the browser-download quarantine
mkdir -p ~/.local/bin && mv screpdb-darwin-arm64 ~/.local/bin/screpdb

Keep it in a writable folder (not ~/Downloads or a Homebrew prefix) so the in-app Update button works.

Windows: Scoop or the CLI

Prefer Scoop? (also installs the screpdb CLI)

scoop install git   # required by 'scoop bucket add' (skip if you already have git)
scoop bucket add screpdb https://github.com/marianogappa/screpdb
scoop install screpdb

Run screpdb-gui for the app or screpdb for the CLI. Upgrade with scoop update screpdb. Seeing an old version? Run scoop update (no package name) first to refresh the bucket.

No Scoop yet? Install it first:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

Want the CLI without Scoop?

Grab screpdb-windows-amd64.exe from the Releases page. The same SmartScreen and antivirus notes apply. You can also build from source.

🛡️ Secured: on Windows, screpdb runs sandboxed at Low integrity, so even a compromised replay parser can only write to screpdb's own data folder. On macOS and Linux there is no OS sandbox yet; writes are confined in-process to the app-data and replays folders. See Security / I/O model.

See CHANGELOG.md for release notes.

Building from source

You'll need Go 1.25.2 or later. Use make build (not a bare go build) so the embedded dashboard UI assets are rebuilt first:

git clone https://github.com/marianogappa/screpdb.git
cd screpdb
make build

Uninstall

1. Remove the binary

Installed with	Command
Windows download or PowerShell installer	Remove-Item -Recurse -ErrorAction SilentlyContinue "$env:LOCALAPPDATA\Programs\screpdb", "$([Environment]::GetFolderPath('Programs'))\screpdb.lnk", "$([Environment]::GetFolderPath('Desktop'))\screpdb.lnk"
Scoop (Windows)	scoop uninstall screpdb
Homebrew (macOS/Linux)	brew uninstall screpdb
One-line installer / manual	Delete the binary you placed (e.g. ~/.local/bin/screpdb)

2. Delete the data folder (optional — skip this to keep your data for a future reinstall).

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\screpdb"

# macOS
rm -rf "$HOME/Library/Application Support/screpdb"

# Linux
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/screpdb"

Developer features

MCP server and full OpenAPI — click to expand

• Server / API: ./screpdb dashboard (also the default when run with no subcommand) starts the HTTP server and opens the dashboard UI. All UI functionality is exposed as a JSON API — OpenAPI schema available. Run it headless as an API-only server (no UI, no browser) with --headless:

./screpdb dashboard --headless -p 8000
# then: curl http://localhost:8000/api/health

• MCP server: point an MCP client (Claude Desktop, Claude Code, Cursor, …) at your replays and ask questions in natural language about any game, player, matchup, build order, or event. A curated read-only subset of the API is reachable; nothing that changes local state is.

./screpdb mcp

If you want to build something on top of screpdb's API or MCP, let me know. I'm open to facilitating this, but I won't add untested features otherwise.

Specification — how the numbers are computed

Every golden value — unit stats, build times, expert timings, detection thresholds — is generated from source and test-backed (see SPECIFICATION.md)

screpdb makes a lot of derived claims: "this is a 9 Pool", "your Spawning Pool was 6s late", "a Zealot takes 25.2s". Skeptical? Audit them.

SPECIFICATION.md documents every golden value the app relies on — unit names, build times, expert timings, costs, tech-tree rules, detection thresholds, and more. It's:

• Generated from the Go source of truth (go generate ./...), so it can't drift from the code.
• Test-backed — CI fails if any value is wrong or the file is stale.

In short: not aspirational docs that rot, but a provably-accurate description of what the app actually does.

Verifying downloads — checksums + minisign signature

Each release publishes a SHA256SUMS file and a SHA256SUMS.minisig minisign signature alongside the binaries.

Verify the checksum (Linux/macOS):

sha256sum -c SHA256SUMS --ignore-missing

Verify the checksum (Windows PowerShell):

Get-FileHash screpdb-windows-amd64.exe -Algorithm SHA256
# Compare the printed hash against the line in SHA256SUMS

Verify the signature (requires minisign):

minisign -Vm SHA256SUMS -P 'RWS9gPPOydPD/tR8JBOelXKhif526NoAKY18dau7QHR4dqg84QMhJ5L/'

Security / I/O model

screpdb minimizes its attack surface by routing all I/O through facades and keeping dependencies small (see #135). On macOS and Linux this is a best-effort, in-process guard; on Windows a Low-integrity worker adds a real OS write boundary.

How the I/O model works — filesystem, Windows sandbox, network, self-update, enforcement

• Filesystem — all disk access goes through internal/iofacade, which permits reads/writes only within: a single per-OS app-data directory (%LOCALAPPDATA%\screpdb on Windows, ~/Library/Application Support/screpdb on macOS, $XDG_CONFIG_HOME/screpdb on Linux) that holds settings, the Battle.net and game-asset caches, logs, crash reports, and extracted sample replays; and the configured replays folder (read replays, write "watch me" replays). A narrow, read-only exception walks up from the replays folder to find StarCraft's CSettings.json.
• Windows OS sandbox — on Windows the app splits into a Medium-integrity launcher and a Low-integrity worker (#237). The launcher marks the app-data directory Low-writable and relaunches the real worker at Low integrity; the worker keeps read-down access to replays anywhere but can only write into that one Low-labeled folder — every other write is refused by the OS, even from a compromised screp/scmapanalyzer parser. The launcher retains self-update (it must overwrite the install .exe) and brokers the single "watch me" write into the read-only replays folder on the worker's behalf. This does not stop a compromised parser from reading private files (Low integrity can read up-level); blocking reads needs AppContainer + a broker process, a deferred "Tier 2" follow-up.
• Network — the dashboard server binds to localhost only. The binary's outbound calls are confined to three sanctioned packages: internal/selfupdate (#212) queries GitHub Releases for self-update, verifying every byte against a minisign-signed SHA256SUMS (embedded public key) before any swap; internal/bnetfacade (#317) talks to SC:R's local web-api bridge (loopback only, path-prefixed to /web-api/) and downloads replays from storage.googleapis.com (allowlisted to the single path prefix /starcraft-user-uploads-prod/S1-replays/, with length + seRS magic-byte validation on every download); internal/netfacade houses localhost readiness probes.
• Self-update — updates are always user-initiated, never automatic. Package-manager installs (Scoop on Windows, Homebrew/Linuxbrew on macOS/Linux) and non-writable install directories are detected and excluded so the updater never fights scoop update / brew upgrade or needs elevation; those installs are pointed back at their package manager. The curl | sh and install.ps1 installers drop into writable dirs (~/.local/bin, %LOCALAPPDATA%\Programs\screpdb), so in-app self-update keeps working there. On Windows, an app opened from the Downloads folder copies itself to %LOCALAPPDATA%\Programs\screpdb, writes Start Menu and Desktop shortcuts, relaunches from there and deletes the download. Self-written binaries carry no macOS quarantine xattr / Windows Mark-of-the-Web, so Gatekeeper/SmartScreen don't re-prompt after an update.
• Enforcement — TestNoDirectIOOutsideFacades (in internal/iofacade) parses the whole module on every go test run and fails the build if any package reaches the filesystem or network directly instead of through the facades. internal/selfupdate, internal/bnetfacade, and internal/winsandbox (the Windows process-spawn / integrity-labeling / broker surface) are the documented exceptions.

On macOS and Linux this is a best-effort, in-process guard, not an OS sandbox: paths handed to trusted dependencies (the screp parser, scmapanalyzer) are opened inside those libraries, and the facade only constrains screpdb's own code. On Windows the Low-integrity worker adds a real OS write boundary on top of the same facades.

I/O Safety Audit

The LLM that authors each change records a dated, one-line verdict on whether it could weaken the I/O rules above (see AGENTS.md); TestIOSafetyAuditPresent fails CI if the log is empty, and the enforcement test above stays the authoritative guard.

2026-10-21  OK. Frontend only: a player with a Skill tab no longer shows Skill proxies, and old Skill proxies links open Skill. No I/O changes.

Older I/O safety audit entries (click to expand, five most recent)

2026-10-21  OK. Frontend only: the player summary Skill row is taller and leads with a large tier badge in its tier colour. No I/O changes.
2026-10-21  OK. Frontend only: the player Skill tab leads with the tier and trend, a dated Skill over time chart with tier lines, a smoothed average and a trend line, then the breakdown; How Skill works is a modal again, and the summary row is compact and points at the tab. No I/O changes.
2026-10-21  OK. Player Skill becomes one clickable summary row and its own tab: Skill over time, the average breakdown and a shorter How Skill works; no new os/net calls, no iofacade/netfacade allowlist widening, no enforcement-test changes.
2026-10-21  OK. Player pages show a Skill average from 5 rated engine games with habit pills, a How Skill works explainer opens from every Skill surface, and the player page drops its engine data count; no new os/net calls, no iofacade/netfacade allowlist widening, no enforcement-test changes.
2026-10-21  OK. Skill: six metrics that all count toward the estimate (EAPM, hotkey recalls put to use, hotkey checks, army production rhythm, unspent resources against income, idle production), read from the command stream at load and from the engine data; worker production stops counting dead bases; a long supply block pill on engine games. No new os/net calls, no iofacade/netfacade allowlist widening, no enforcement-test changes.

License, Contributing & Acknowledgements

• This project is licensed under the MIT License. See the LICENSE file for details.
• Due to security safeguards I can no longer accept PRs or other code contributions, but please feel free to file an Issue, and you're more than welcome to contribute non-code improvements.
• Built using the github.com/icza/screp library for StarCraft replay parsing. This project would have been impossible without András Belicza's work.
• Country flags on platforms that lack them (Windows) are drawn with the Twemoji Country Flags font, whose artwork comes from Twemoji and is used under CC BY 4.0.