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 is currently distributed as a binary with full filesystem read/write access and unrestricted Internet access. Treat it as high-risk software and think twice before executing it. Safety guardrails are being investigated.

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)
- `-w, --watch`: Watch for new files and ingest them as they appear
- `-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: ask AI anything about 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

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.