Hillclimbing on verifiable rewards.
Use Claude Code and Codex to autonomously search for python programs that optimize a score you define.
Website · Docs · Quickstart · Python SDK · CLI reference · Blog · Discord
hillclimb is a CLI and modular Python framework for building, testing and benchmarking hillclimbing algorithms powered by coding agents. It provides reusable components and a common way to evaluate different search strategies across different problems — from speeding up code and solving optimisation problems to improving prediction accuracy. The goal of hillclimb to create a framework to enable discovery of better autoresearch methods, rather than build a single best autoresearcher.
There are two main parts: the problem and the climber. A problem defines what counts as better through a verifier script, verifier.sh, and optionally includes a starting solution, solution.py. A climber is a search algorithm that drafts initial solutions and then decides which solutions to build on and what to try next. Start with built-in problems and climbers, or write your own ones.
hillclimb run starts the search in the background and returns control of your terminal. Within the compute budget you set, the climber dispatches headless coding agents to write, debug and improve solutions. Your verifier scores each attempt, and hillclimb keeps the best result.
A hillclimb search running visualised through hillclimb watch:
uv tool install hillclimb # or: pip install hillclimb (Python 3.12+)
hillclimb connect claude # or codex, pi, openrouter; add --agent dummy to any run for no LLM at all
hillclimb init # hillclimb.yaml, problems/, runs/, climbers/ in this folder
hillclimb problem get heilbronn-convex-13 # the verifier is the problem; description.md is the brief
hillclimb climber get greedy # the climber, as Python you can read and edit (climbers/greedy/policy.py)
hillclimb verify heilbronn-convex-13 # score the floor solution
hillclimb run heilbronn-convex-13 --budget 10m
hillclimb watch # live coding agents and scores (also: chart, tree)
hillclimb stop --all
hillclimb summit # copy the best solution.py into this folder
Every search also keeps its best in runs/<run-id>/searches/<search-id>/best/.
The walkthrough goes through each step.
A climber is five modules, run in this order at every step of a search. The
engine ships none of the first two: the catalog's climbers (greedy,
openevolve, gepa) are Python files hillclimb climber get copies into your
folder, to read and edit; the other three are built in or a file of your own.
| Module | Decides | Built in / in the catalog |
|---|---|---|
selector_policy |
which candidate the next attempt builds on | Best ,MapElites (catalog) |
operator_policy |
which operator to apply to it | Greedy (catalog) |
operators |
how one attempt is made: the prompt the coding agent gets | draft ,debug ,improve ,ensemble |
tuner |
which parameter values to try on a candidate | random ,optuna |
memory |
what carries over from one search to the next | files ,none |
Together they are one block of config, in a run spec or as the folder's run
default in runs/config.yaml (hillclimb climber get pins one there):
climber:
selector_policy: climbers/openevolve/policy.py:MapElites # which candidate to build on next
operator_policy: climbers/greedy/policy.py:Greedy # which operator to use on it
operators: [draft, debug, improve, crossover.py:Crossover]
tuner: optuna
memory: files
params: {num_drafts: 5}
Every slot takes a .py file (file.py:Class), package.module:Class, or a
built-in's name. A fetched climber is one file that builds the whole block
(climber: climbers/greedy/policy.py). Or compose in Python:
from hillclimb import Budget, Climber, Problem, catalog
greedy, openevolve = catalog.module("greedy"), catalog.module("openevolve")
problem = Problem("heilbronn-convex-13")
budget = Budget(wall_clock="10m", evaluations=40)
climber = Climber(selector_policy=openevolve.MapElites(num_drafts=5), operator_policy=greedy.Greedy())
climber.search(problem, budget=budget)
climber.best, climber.history, climber.to_frame()
A catalog climber that imports a library beyond hillclimb (openevolve, gepa) names it in a
requirements.txt beside its policy.py — pip install -r climbers/gepa/requirements.txt, as
climber get says; tuner: optuna is the engine's and needs 'hillclimb[optuna]'.
climber.start(...) opens the same search to drive by hand, one climber.step() at a
time, and Problem(name, score=my_function, ...) defines a problem from a scoring function.
Runnable scripts are in examples/.
Compare two head to head:
hillclimb climber get openevolve --no-default
hillclimb run heilbronn-convex-13 --climber climbers/greedy/policy.py --climber climbers/openevolve/policy.py # one search each; --parallel-searches 3 runs three of each
hillclimb experiment report <run-id>
| From first run to following and resuming a search. | Define your own problem and write its verifier. |
| The modules a climber is built from. | Compare climbers on the same problem. |
| Every example problem and its best known value. | Every hillclimb command and its flags. |
| Build and run searches from Python. | Blog posts on hillclimbing. |
Questions, results, ideas: join the Discord.