Installing & running it

No programming experience needed. Download the project, double-click one file to install everything, then double-click another to launch. Budget about 5 minutes the first time. The app runs entirely on your own computer — nothing is uploaded anywhere.

What you need

A Windows, macOS or Linux computer, an internet connection (to download things the first time and, later, to fetch card data from Scryfall), and a web browser. You do not need to install Python or anything else yourself — the installer below handles all of it.

Step 1 — Download the project

On the GitHub page click the green “<> Code” button, then “Download ZIP”. Unzip it somewhere you'll find again (e.g. your Documents folder). You'll get a folder named MtG-Goldfish-Simulator-main containing, among other things, the install and launch files used below.

Comfortable with Git? git clone https://github.com/BastienPasdeloup/MtG-Goldfish-Simulator.git works too.

Step 2 — Install it (one click)

Open the project folder and double-click the file for your system. It installs a small helper tool and downloads Python and everything else automatically. A window opens showing progress — the first run can take a minute or two. When it says “All done!” you can close it.

Your computer	Double-click this file
macOS	`install-macos.command`
Windows	`install-windows.bat`
Linux	`install-linux.sh`

If your system warns you the first time

These files are safe — the warnings just appear because you downloaded them from the internet.

macOS — if it says the file is “from an unidentified developer”, right-click the file, choose Open, then Open again. You only do this once.
Windows — if a blue “Windows protected your PC” box appears, click More info, then Run anyway.
Linux — if double-clicking opens the file in an editor instead of running it, right-click and choose Run in Terminal (or run ./install-linux.sh from a terminal in the folder).

Step 3 — Launch it (one click)

Whenever you want to use the simulator, double-click the launcher for your system. It starts the app and opens it in your web browser automatically.

Your computer	Double-click this file
macOS	`launch-macos.command`
Windows	`launch-windows.bat`
Linux	`launch-linux.sh`

A small window stays open while the app runs — that's normal. Keep it open while you're using the simulator.
Your browser opens at http://127.0.0.1:8000. If it doesn't open on its own, type that address into your browser yourself.
To stop the app: close that window (or press Ctrl + C in it).

Step 4 — Use it in the browser

Paste a Moxfield or MTGTop8 deck URL. The format, commanders and companions are all detected automatically.
Define properties (a trigger moment + a plain-English condition) and how many mulligans to allow.
Compile, review the generated code, and run a simulation. Statistics stream live; each successful game can be replayed on an MTGO-like board, and its full search tree opened.

Optional: sharper English → code

Out of the box, a built-in offline converter handles simple conditions. For more complex English, click ⚙ Choose model in the Properties box to use a local model (via Ollama) or an API model — set an ANTHROPIC_API_KEY (copy .env.example to .env). Either way the generated code is shown for you to review before running.

Updating to a newer version

The project improves over time. On startup the app compares its version against the latest released on GitHub and shows a small “download the latest version” popup when a newer one exists.

Downloaded the ZIP? Download the ZIP again and replace your folder, then double-click the install file for your system once more (to pick up any new dependencies). Your saved sessions live elsewhere and aren't affected.
Cloned with Git? Run git pull in the project folder, then launch it again as usual.

Prefer the terminal? (advanced)

The one-click files are just small wrappers around two commands. If you'd rather run them yourself, you don't need the install/launch files at all:

# 1. Install uv (once). macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
#    …or Windows PowerShell:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. From inside the project folder, start the app (first run fetches Python + deps):
uv run mtg-goldfish

uv is a tiny tool that fetches the correct Python and every dependency automatically, so you never manage that yourself. When you see Uvicorn running on http://127.0.0.1:8000, open that address in your browser. Stop the app with Ctrl + C.

Troubleshooting

Symptom	Fix
The install/launch window flashes and disappears	Run it from a terminal so you can read the error: open a terminal in the project folder and run the install command from the “Prefer the terminal?” section above.
Double-clicking opens the file in a text editor (Linux)	Right-click and choose Run in Terminal, or run `./install-linux.sh` then `./launch-linux.sh` from a terminal.
macOS says the file can't be opened	Right-click the file → Open → Open. You only need to do this once per file.
The browser page doesn't load	Make sure the launcher window is still open, then open exactly `http://127.0.0.1:8000`.
A card is shown in red	It has no dedicated implementation yet and plays as a vanilla approximation — results relying on it are approximate.