Stellaris Auto-Start Automation

Automatically launch Stellaris, load your save, and unpause the game - perfect for mod testing with Claude Code.

What It Does

1. Syncs mod files (optional) - copies your mod to Stellaris folder
2. Launches Paradox Launcher with Chrome DevTools Protocol enabled
3. Auto-clicks RESUME button via CDP (no image recognition needed!)
4. Waits for game to load (monitors game.log for timestamps)
5. Unpauses and sets fastest speed via AutoHotkey

Total time: ~45-50 seconds (first run), ~30-35 seconds (if launcher already open)

Requirements

Windows (via WSL2)

• WSL2 with Ubuntu
• AutoHotkey v2.0 - Download
• Python 3 with packages: requests, websocket-client
• Stellaris with Paradox Launcher

Install Python packages

pip install requests websocket-client

Install AutoHotkey

Download and install AutoHotkey v2.0 from https://www.autohotkey.com/

Setup

1. Clone this repo

git clone https://gitlab.com/stellarisclaude206-group/stellarisClaude-project.git
cd stellarisClaude-project

2. Copy and edit config

cp config.template.sh config.sh
nano config.sh  # Edit paths for your system

3. Make scripts executable

chmod +x *.sh scripts/*.py

4. Test it!

./stellaris-autostart.sh

Configuration

Edit config.sh with your paths:

# Path to your Stellaris logs (OneDrive or local)
STELLARIS_LOGS="/mnt/c/Users/YOURUSERNAME/OneDrive/Documents/Paradox Interactive/Stellaris/logs"

# Path to AutoHotkey v2
AHK_PATH="/mnt/c/Program Files/AutoHotkey/v2/AutoHotkey.exe"

# Path to Paradox Launcher
LAUNCHER_PATH="/mnt/c/Users/YOURUSERNAME/AppData/Local/Programs/Paradox Interactive/launcher/bootstrapper-v2.exe"

# Optional: Path to your mod workspace (for auto-sync)
MOD_WORKSPACE=""  # Leave empty to skip sync

Usage

Basic usage

./stellaris-autostart.sh

Debug mode (more output)

./stellaris-autostart.sh debug

With Claude Code

Add to your project's CLAUDE.md:

## Quick Commands
- `./stellaris-autostart.sh` - Launch game and unpause

Then just tell Claude: "run the autostart script"

How It Works

CDP (Chrome DevTools Protocol)

The Paradox Launcher is an Electron app, which means it has a built-in Chrome debugging interface. By launching with --remote-debugging-port=9222, we can:

• Connect to the launcher's DOM
• Search for the "RESUME" button
• Click it programmatically

This is much more reliable than image recognition!

AutoHotkey for Game Input

Stellaris uses SDL/DirectInput which filters synthetic keyboard input from normal Windows APIs. AutoHotkey provides hardware-level HID emulation that bypasses this filter - that's why we use it for unpause/speed commands.

Troubleshooting

"RESUME button not found"

• Make sure you have a save game to resume
• Check that the launcher opened correctly
• Try running with debug mode for more info

"Game didn't load within timeout"

• Large save files take longer - increase MAX_LOAD_TIME in config
• Check if Stellaris actually started in Task Manager

AutoHotkey errors

• Make sure AutoHotkey v2.0 is installed (not v1.x)
• Check the path in config.sh

Files

stellaris-autostart/
├── README.md                 # This file
├── config.template.sh        # Configuration template
├── stellaris-autostart.sh    # Main automation script
└── scripts/
    ├── click_resume_cdp.py   # CDP script to click RESUME
    └── unpause.ahk           # AutoHotkey unpause script

Credits

Created for use with Claude Code for Stellaris mod development.

License

MIT License - Use freely, modify as needed!