Overview
Auto-hillclimbing for verifier-defined problems.
You describe one problem as a single script: verifier.sh runs a candidate solution.py and
writes back a number. hillclimb then spends a compute budget having headless coding agents
write, debug and improve that solution.py — scoring every version through your verifier and
keeping the one that scores best. Below, a real greedy run on heilbronn-convex-13, candidate by
candidate, against the benchmarks from problem.yaml.
What is hillclimb for?
Anything you can phrase as: a program or artifact in, a number out, and a verifier that computes
that number/score (potentially using data the agents never seen). Some problem types that are well
suited for hillclimb:
| Problem type | What Hillclimb improves |
|---|---|
| Optimization | Packing, routing and scheduling solutions, scored by solution quality, cost or constraint violations. |
| Prediction and forecasting | Training and prediction code, evaluated on hidden data using metrics such as MAE, pinball loss or CRPS. |
| Performance engineering | Code for a fixed workload, scored by runtime, memory use, binary size or another resource constraint. |
| Parameter fitting | Estimation code that recovers unknown parameters, tested against cases with known ground truth. |
| Strategies and policies | Dispatch, bidding and cache-eviction strategies, evaluated by replaying historical or simulated scenarios. |
| Generated artifacts | SQL queries, regular expressions, solver configurations and prompts—anything that can be generated and scored. |
| Mathematical discovery | Constructions, counterexamples and bounds, scored by a programmatically verifiable mathematical objective. |
Where it fits poorly. Verifiers that take hours: the loop needs many candidates per budget and starves. Objectives without a scalar score, like UX, prose or "nicer code". Pass/fail verifiers with no partial credit, since a 0/1 score gives the search nothing to climb. Low-dimensional continuous optimisation, where a numerical optimizer is the better tool.
Rule of thumb. Can each attempt be scored automatically in under fifteen minutes? Does the
score reliably distinguish better attempts from worse ones? Does improving the score improve the
outcome you actually care about? Three yeses make your problem a strong candidate for hillclimb.
How to prevent reward hacking?
Agents optimize the score your verifier produces, not necessarily the outcome you intended. If there is a shortcut or loophole, the search may find it.
Test on cases the agent never sees. Score a solver rather than a fixed answer, and evaluate it
across multiple instances. Keep some instances hidden with holdout: true so the agent must
discover a solution that generalizes instead of memorizing the visible cases.
Make improvements real and reproducible. Score invalid outputs as zero, avoid unnecessary
rounding, and measure the verifier's noise with hillclimb verify --repeat 5. Set
search.min_improvement above the noise floor so Hillclimb only accepts meaningful
improvements—and inspect the winning code before using it.
Concepts
Coarse to fine, on disk and in hillclimb watch:
Run # one `hillclimb run`
└── Search # one climber on one problem
└── Candidate # one version of `solution.py`
└── Trial # one parameter set
└── Replicate # one seeded execution, for stochastic verifiersTwo roles act on it: a climber decides what a search tries next (its selector policy,
operator policy, operators, tuner and memory); an agent (claude-code, codex) writes each
candidate.
Framework
A climber is five parts you can swap for your own, and one record they all share:
| part | what does it decide? | comes with |
|---|---|---|
| selector policy | which candidate to build on next | Best, MapElites |
| operator policy | which operator to use on it | Greedy |
| operators | what the agent is asked to do | Draft, Debug, Improve |
| tuner | which parameter values to try | RandomSearch, Optuna |
| history | nothing. It is the record of this search: every candidate, its score, its parent | the journal |
| memory | what to keep from earlier searches, and leave for later ones | FilesMemory, NoMemory |
The presets greedy, openevolve and gepa are whole climbers; Climber has
every part and its knobs.
Form factor
hillclimb is a CLI that drives coding agents in headless mode. You start a search yourself, or
your own coding agent does; the CLI runs it; headless coding agents write the code, as many in
parallel as the search is given.
This is the usage pattern we have in mind: you talk to hillclimb through your coding agent, or directly through the CLI, and it spins up a lot of parallel agents underneath.
Architecture
hillclimb is built in layers, so you can start small and grow into it. To begin, bring a problem
and run it with a preset climber. When you want to change how the search works, replace one module
of the climber: a SelectorPolicy, OperatorPolicy, Operator, Tuner or Memory, each a class you subclass
from hillclimb.sdk and name in the climber: block. Underneath, the harness stays fixed. It runs
the loop, sandboxes the code, scores every candidate, counts the budget and journals everything the
same way for every climber, so two climbers on the same problem are always compared fairly. The
agent that writes the code is whichever one you connected.
The cyan blocks are the climber, each a class you can swap, each plugged into the same harness. In the RSI framework's terms they are the agent: πsel, πop and O, plus a tuner and a memory of hillclimb's own. The verifier V stays outside it, in the problem; the harness keeps the history Ht and the budget τ.
A search repeats one step until its budget closes. Each step crosses the layers the same way:
The climber decides and observes, the harness does the work and keeps the record, and the agent only ever touches code, inside the sandbox.
Three ways to use hillclimb
| from | how | read more |
|---|---|---|
| the CLI | hillclimb run … — the headless engine, every command and flag | CLI reference |
| Python | Climber(...).search(problem) — the same search from a script or a notebook | Python SDK |
| your agent | the skill that lets Claude Code start, watch and steer runs for you | SKILL.md |
Next steps
Quickstart
Install the CLI, get a problem, start climbing.
Walkthrough
The Heilbronn triangle problem end to end, with the run's own charts.
Visualisations
What hillclimb draws while it climbs, live from a running search.
Create a problem
A problem is a folder, and a problem is its verifier.
Run a search
Run a climber on a problem, follow it, and pick it up again.
Run an experiment
Compare setups over repeats, and tell a real difference from chance.