coach.py is an LLM-powered coach that can help a StarCraft ladder player. It's set up to run with a voice interface during a gaming session and can answer questions from replay history and about opponents such as:
- When did I last play against this player?
- What was the opening build order of this player, in summary?
- Is this player a smurf?
- Who is ahead in the current replay?
- Cast the game from replay please
The AI coach is embedded with a voice engine and can be interacted with live during gameplay via microphone (optional, can run in text-only mode).
New chat sessions with the AI coach are initiated when a new ladder game is starting, when a game just finished, or on voice command. The LLM assistant can use multiple high-level capabilities such as querying a MongoDB replay database, looking up a player's Battle.net profile, or adding comments to a replay. The assistant decides autonomously without explicit programming when to employ a capability.
This is a personal research project to explore LLM-based agents applied to competitive gaming.
Looking up past games when a new game is being played:
Analyzing a replay after a game just finished:
Answering arbitrary questions on SC2:
Instructions for a minimal setup without voice integration. Text only, "chat with your replays". Some Python experience required.
Developed and tested with Python 3.12.
Install with uv: https://docs.astral.sh/uv/
> uv syncAll settings can be done in config.yml, or better yet in a config.yourname.yml file in the same directory. Any config.*.yml file overwrites values from config.yml. This allows you to keep your personal settings separate.
At minimum, set replay_folder to point to where your SC2 ladder replays are saved:
# config.yourname.yml
replay_folder: "C:\\Users\\yourname\\Documents\\StarCraft II\\Accounts\\1234\\2-S2-1-1234\\Replays\\Multiplayer"
student:
name: "yourname"
race: "Terran"The rest of the settings will be taken from config.yml.
Secrets are configured with environment variables. Either provide them at runtime or put them in a .env file like .env.example. Note: Copy to .env since the example file is ignored by the application.
Any MongoDB > 4.5 will do. Either setup one by yourself, or follow the instructions in mongodb/ on how to setup a local database for dev/testing.
If you setup your own MongoDB, create a database and add the DB name to settings:
# config.yourname.yml
replay_folder: "C:\\Users\\yourname\\MyReplays"
student:
name: "yourname"
race: "Terran"
db_name: "YOURDB"and add the MongoDB connection string to the env variable AICOACH_MONGO_DSN.
Use the tool repcli.py to populate your DB with replays. The tool offers a few options:
> python repcli.py --helpUsage: repcli.py [OPTIONS] COMMAND [ARGS]...
Options:
--clean Delete replays from instant-leave games
--debug Print debug messages, including replay parser
--simulation Run in simulation mode, don't actually insert to DB
-v, --verbose Print verbose output
--help Show this message and exit.
Commands:
add Add one or more replays to the DB
echo Echo pretty-printed parsed replay data from a .SC2Replay file
query Query the DB for replays and players
sync Sync replays and players from replay folder to MongoDB
validate Validate all replays in the DB.
Run
> python repcli.py sync --from=2024-01-01 to read all 1v1 ladder replays from beginning of 2024, and add the replays and the players from the replays to the DB.
Use the --simulation flag to just read replays but not commit to DB.
The replays collection of the DB should now be populated with replay documents.
See python repcli.py sync --help for more options. You can always repopulate the DB from replay files without destroying anything. AICoach does not change anything on the replay data in the DB.
Prerequisites:
- Set up an OpenAI account and fund it with credits
- Create an OpenAI Assistant
- Create an API key
Add your OpenAI organization, Assistant ID, and API key to the environment variables: AICOACH_ASSISTANT_ID, AICOACH_OPENAI_API_KEY, and AICOACH_OPENAI_ORG_ID.
The default model is gpt-4.1 (configurable via gpt_model in config).
Note on cost: Typically interactions stay below $0.10, but longer session can run up to and over $1.00 in API costs. AICoach will not incur API costs until one of the wake events is triggered.
If you just want a database with your replays you can skip this step and the next or do it later.
If using OpenAI as your AI backend:
> python build.pyThis generates a new file assistant.json with your assistant configuration.
> python build.py --deployThis deploys the assistant to OpenAI. Verify the assistant is properly initialized with tools and instructions at https://platform.openai.com/playground
Configure a wake hotkey. When pressed, AICoach will wake up and ask for input (default: ctrl+alt+w).
Configure student.emoji if you want to show a different icon in the terminal output.
Disable interactive if you want AICoach to speak but not listen for input:
# config.yourname.yml
replay_folder: "C:\\Users\\yourname\\MyReplays"
audiomode: "text"
student:
name: "yourname"
race: "Terran"
emoji: ":woman_student:"
db_name: "YOURDB"
wake_key: "ctrl+alt+w"
interactive: true> python coach.pyThis starts a listener that reacts to configured events. For each event, AICoach performs an action and asks the student for input.
Students can chat with AICoach. The conversation continues as long as both parties keep engaging. AICoach determines autonomously when a conversation is complete - typically when you thank it or say goodbye.
AICoach can be triggered by several events, configurable via coach_events:
Invoked when the wake hotkey is pressed. AICoach asks for a question without additional context.
When a new replay is added to the replay folder while AICoach is running:
- Adds the replay to the replay database
- Offers to discuss the replay with you
On conversation end, AICoach saves the conversation with a summary and keywords characterizing the game to replay metadata.
Triggered at the very start of an SC2 game (when the in-game clock hits 1 second):
- Looks in the database for existing replays of the opponent
- Summarizes the opponent's past strategies
- Asks for follow-up questions
Control which events AICoach responds to:
# config.yourname.yml
coach_events:
- game_start
- wake
- new_replayPlease note: This is a hobby project and advanced features are not ready to use without technical setup. Code is presented as-is without dedicated support.
Prerequisites:
- All requirements from minimal setup above
- NVIDIA GPU (for local voice recognition and synthesis)
- Microphone and speakers
For advanced setup with voice integration, see Installation.md for detailed steps. This requires Python experience and familiarity with machine learning tools.
OBS Integration (keep obs_integration=False to skip):
- Integrates with OBS for scene control and display
Additional implemented but undocumented features:
- Twitch chat integration - AICoach listens and responds to Twitch chat
- Battle.net integration - retrieves player profile information and portraits
- SC2 Pulse integration - can unmask barcode players
- Smurf detection - analyzes whether opponents are smurfs
- Replay commentary - AICoach can commentate games from replays
- Game type: Designed for competitive 1v1 ladder only. Team games, arcade, and custom games are not supported and may cause unexpected behavior.
- Player names: Internal logic relies on player names, so changing your Battle.net name between seasons will break some functionality.
- Regions: Primarily tested on EU Battle.net. Some functionality may not work on NA/KR or other regions.
- Replay age: Only tested with LotV replays from early 2023 onwards. Older replays will likely cause errors.
- Text mode limitations: Text mode wake events can cause SC2 lag during gaming sessions. Disable for competetive play.
- Platform: Production code targets Windows. Unit tests pass on both Windows and Linux.