Quick Start

1. Create a Repository From the Template

Click Use this template on GitHub, create your repository, and clone it:

git clone https://github.com/<your-github-name>/<your-repository>.git
cd <your-repository>

Choose either initialization path:

Use an AI coding tool (recommended): In Codex, enter Use $initialize-ok-script-app to initialize this repository. With another tool, ask it to read .agents/skills/initialize-ok-script-app/SKILL.md first. The initializer gathers the game, runtime targets, repositories, icons, and first-task requirements before editing files.
Initialize manually: Continue with this page and the linked guides.

2. Install Python 3.12 and Project Dependencies

Install Python 3.12.10, then run:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
$PypiIndex = "https://pypi.org/simple/"
python -m pip install --index-url $PypiIndex --upgrade pip

Install the Qt desktop UI dependencies (ok-script 3.0.0b3):

python -m pip install --index-url $PypiIndex --no-deps --upgrade -r requirements.txt
python main_debug.py

ok-script 3 removed the web frontend. The old web launchers, web extra, and requirements-web.txt remain compatibility aliases for the desktop app.

The lock files provide reproducible installations and are recommended for daily development. To resolve the latest compatible dependencies directly from pyproject.toml, use the applicable command instead:

python -m pip install --index-url $PypiIndex ".[qt]"

Run only the command for your target. The official PyPI index endpoint for pip is https://pypi.org/simple/, not the website root https://pypi.org/. Using the website root can report No matching distribution found even when the package exists.

Administrator privileges are normally unnecessary. If the target game runs as administrator, launch the automation app at the same privilege level or capture and input may not work.

3. Initialize the App

Set the application identity, runtime targets, icons, and update repository in App configuration.
Create and register the first task with Task development.
Start Debug mode:

python main_debug.py

Run tests:

python -m unittest tests.TestMain

After validation, configure the workflows and push a tag using Packaging and release.