hillclimb 0.8.0

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 provides a modular harness, tooling and testbed for exploring and benchmarking autoresearch algorithms. The aim is to provide a tool to discover better autoresearch methods, rather than build a single best autoresearcher.

You provide a verifier script, verifier.sh, and (optionally) a starting solution, solution.py. hillclimb then spends a compute budget running a search policy — a climber — that decides which version to build on next and dispatches headless coding agents to write, debug and improve it. Each version is scored through your verifier, and hillclimb keeps the one that scores best.

The harness is fixed. The climber — what to try next and how each attempt is prompted — is a block you can swap, edit and share, so two methods can be compared on the same problem under the same budget.

Quickstart

pip install hillclimb                      # or: uv tool install hillclimb
hillclimb connect claude                   # or codex, pi, openrouter; add --agent dummy to any run for no LLM at all

hillclimb init                             # hillclimb.yaml, problems/, runs/ in this folder
hillclimb problem get heilbronn-convex-13  # the verifier is the problem; description.md is the brief
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. Each one is a built-in or a Python file you can edit.

Together they are one block of config, in a run spec or as the folder's default in hillclimb.yaml:

climber:
  selector_policy: map-elites     # which candidate to build on next
  operator_policy: 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 prebuilt module, a .py file of your own, or package.module:Class. Presets: greedy, openevolve, gepa. Or compose in Python:

from hillclimb import Budget, Climber, Problem
from hillclimb.policies import Greedy
from hillclimb.selectors import MapElites

problem = Problem("heilbronn-convex-13")
budget = Budget(wall_clock="10m", evaluations=40)
climber = Climber(selector_policy=MapElites(num_drafts=5), operator_policy=Greedy())

climber.search(problem, budget=budget)
climber.best, climber.history, climber.to_frame()

MapElites and the openevolve preset need pip install 'hillclimb[openevolve]', tuner: optuna needs 'hillclimb[optuna]' and gepa needs 'hillclimb[gepa]'.

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 run heilbronn-convex-13 --climber greedy --climber openevolve   # 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