screpdb

README

screpdb

screpdb is an advanced Starcraft replay reporting tool.

Features

Filtering/finding replays by high-level semantic features & staging them for watching on the game client

Rich game events browser with map overlays

Build Order detection with charts and for comparing with progamer timings

Skill proxies measurements: Viewport Multitasking, Unit Production Cadence, First Unit Efficiency

Alias list support for progamer replays (built-in, editable, importable/exportable), and automatic aliasing for local user's player names

Sophisticated command de-duping on the early game to facilitate precise build order detection and timing comparisons

Alliance timeline and team stacking detection on multiplayer melee games

Installation

Download the latest release from the Releases page. See CHANGELOG.md for release notes.

As a convenience for non-technical Windows users, a special Windows GUI binary is included in releases (look for screpdb-dashboard).

⚠️ Warning: screpdb runs as an unsandboxed binary. To reduce risk it now routes all I/O through in-process facades — filesystem access is confined to the working directory, the replays folder, and the OS cache dir, and the binary makes no outbound network calls (see Security / I/O model). These are best-effort guardrails, not an OS sandbox, so still exercise judgement before running it.

If you prefer to build from source, you'll need Go 1.25.2 or later:

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

Developer features

• CLI for ingestion onto SQLite database. No need to use UI: just ingest and query the database.

./screpdb ingest

- `-i, --input-dir`: Input directory containing replay files (default: system replay directory)
- `-s, --sqlite-path`: SQLite database file path (default: screp.db)
- `-n, --stop-after-n-reps`: Stop after processing N replay files (0 = no limit)
- `-d, --up-to-yyyy-mm-dd`: Only process files up to this date (YYYY-MM-DD format)
- `-m, --up-to-n-months`: Only process files from the last N months (0 = no limit)
- `--store-right-clicks`: Store `Right Click` commands (disabled by default to reduce command-table volume)
- `--skip-hotkeys`: Skip storing `Hotkey` commands (disabled by default)
- `--clean`: Drop all non-dashboard tables before ingesting to start over (useful for migrations)

• MCP server: expose the replay database to an MCP client so you can query any game/player.

./screpdb mcp

# Specify custom database file
./screpdb mcp -s /path/to/custom.db

• All UI functionality exposed as API: OpenAPI schema available

Running on Windows

The Windows binaries are not code-signed. On first launch you will see one or more of the following — none of them mean the binary is malicious:

• SmartScreen "Windows protected your PC" dialog. Click More info → Run anyway.
• Microsoft Defender or third-party antivirus may flag the binary as suspicious or silently quarantine it. Unsigned Go binaries that read files and make network requests are a known false-positive pattern. If the binary disappears from your Downloads folder, check Defender's Protection History and restore it (or add an exclusion).
• Enterprise machines running AppLocker or Windows Defender Application Control may block execution outright. There is no workaround without code signing.

The dashboard binary (screpdb-dashboard-windows-amd64.exe) is a GUI app — if you dismiss the SmartScreen dialog, it simply won't start and won't print any error.

You can always build from source to bypass these warnings.

Verifying downloads

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

• Filesystem — all disk access goes through internal/iofacade, which permits reads/writes only within: the current working directory (the SQLite database), the configured replays folder (read replays, write "watch me" replays), and the OS user-cache directory (cached game-asset images). A narrow, read-only exception walks up from the replays folder to find StarCraft's CSettings.json.
• Network — the Go binary makes no external outbound network calls. The dashboard server binds to localhost only. The single "new version available" check is a browser fetch() to the GitHub releases API from the dashboard UI, not from the binary. internal/netfacade houses the only network-client operation (a localhost readiness probe).
• 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.

This is a best-effort, in-process guard, not an OS sandbox: paths handed to trusted dependencies (the SQLite driver, the screp parser, scmapanalyzer) are opened inside those libraries. The guarantee is that screpdb's own code keeps its I/O behind these chokepoints.

I/O Safety Audit

Changes to screpdb are authored by an LLM coding agent (e.g. Claude Code). As part of authoring a change, that LLM re-assesses whether the change could weaken the I/O rules above and records a dated, one-line verdict in the log below (see AGENTS.md). It's an honour-system receipt written by the same LLM that wrote the code — it can be tampered with, just as the facades themselves can — but recording it makes any tampering visible in the diff. TestIOSafetyAuditPresent fails CI (go test ./...) if the log has no entry, so a change cannot land with an empty audit. The authoritative guard remains the enforcement test above.

• 2026-05-31 — OK. Introduced the iofacade/netfacade chokepoints, the enforcement test, and removed the AI + fswatch surfaces; this change establishes the I/O rules rather than weakening them.

(Most recent first. The authoring LLM adds a dated line each time; keep the last few.)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions welcome. Open a Pull Request or file an Issue.

Acknowledgments

• Built using the github.com/icza/screp library for StarCraft replay parsing. This project would have been impossible without András Belicza's work.