From nothing to a first result. Six steps, in order.
This runs the optimizer on your own machine against one of the datasets that ship with it. What to type is on the right of each step.
Rather not install anything? Use the hosted one
-
Get a key.
You need Python 3.13 or newer and an OpenRouter API key. OpenRouter is the default provider for the optimizer.
Create a key at openrouter.ai# check your Python
python --version
-
Clone and install.
The key goes in a file called .env in the repo root. That file carries API keys and nothing else.
Install, in the manualgit clone https://github.com/PromptPotter/prompt-potter-optimizer.git
cd prompt-potter-optimizer
echo "OPENROUTER_API_KEY=your_key_here" > .env
pip install -e ".[all]"
-
Start a campaign.
Open Claude Code in the repo root and run the skill that ships with it. It checks your setup, downloads and starts the backend a campaign scores against, lists the bundled datasets for you to pick from and prepares the campaign. If Claude Code was already open, reload it first.
Your first campaign, and the path without Claude Code# in Claude Code, not in a shell
/potter-run
-
Run it.
A campaign takes minutes to hours, so it runs in your own terminal. Ctrl+C pauses it and saves what is banked. The same command picks it up where it stopped.
Reading the outputpython -m promptpotter resume
-
Watch it in the browser.
In a second terminal, serve the app and open http://127.0.0.1:8001/. Leave the campaign running in the first one.
What the screens showpython -X utf8 -m uvicorn promptpotter.main:app --port 8001
-
Read the result.
When it finishes, the winning version is in export.json in the campaign folder, with the measurements behind it. log.md beside it has one digest per round. The score on the held-out examples is graded when you ask for it.
Where results land# grade the winner on the held-out examples
python -m promptpotter bench
You have a result. Where to go from it.
The manual. Six chapters, kept beside the code.
The full walkthrough lives in the optimizer repo, where it stays in step with the code. Each chapter opens on GitHub.