hillclimb

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:

Quickstart

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.

Climbers

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.

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>

Learn more

Questions, results, ideas: join the Discord.

License

MIT