hillclimb

Hillclimbing on verifier-defined problems. You give it a problem — a folder whose verifier.sh scores a solution.py — and a budget. It spawns coding agents (Claude Code, Codex or pi) as operators that draft, debug and improve solutions, scores every candidate through your verifier, and keeps the best. The harness is fixed. The climber — what to try next and how each attempt is prompted — is a bundle you can swap, edit and share, so two methods can be compared on the same problem under the same budget.

Get started

Eight commands, ten minutes. Each step says what you should see.

1. Install and connect an agent.

pip install hillclimb
hillclimb connect claude       # logs in; operator calls bill your Claude subscription

connect codex and connect pi do the same for the other agents. No agent yet? Add --agent dummy to any run below: it climbs with no LLM at all.

2. Make a hillclimb dir, get a problem, read it.

hillclimb init                         # this folder: hillclimb.yaml, problems/, runs/
hillclimb problem list                 # the bundled example problems, with the best known value
hillclimb problem get heilbronn-11

Everything hillclimb writes lives beside hillclimb.yaml (hillclimb init hillclimb keeps it all in a subfolder instead). The problem lands in problems/heilbronn-11/. Open verify.py: the verifier is the problem. Everything the agents will be told is in description.md.

3. Check the verifier.

hillclimb verify heilbronn-11 --repeat 3

Scores the problem's floor three times and prints the spread. Example problems are exact, so the spread is 0 and any improvement is real. On a noisy problem of your own, this number is the noise floor the search must beat.

4. Climb.

hillclimb run heilbronn-11 --budget 10m

The search starts as a detached engine and the terminal comes straight back with the run id: a baseline, then drafts, debugs and improves, each scored as it lands. (--no-detach keeps it in this terminal; Ctrl-C then stops it.)

5. Watch it.

hillclimb watch      # every agent, what it is doing, its candidate's score
hillclimb chart      # best score so far against time, every candidate a dot
hillclimb tree       # the exploration tree: what was expanded, what was left

The result is runs/<run-id>/searches/heilbronn-11/best/: solution.py and the submission.csv it wrote.

6. Stop everything.

hillclimb stop --all

7. Next.

• Your own problem. Copy a bundled problem and edit verify.py. See docs/problems.md.
• Another climber. hillclimb run heilbronn-11 --climber openevolve. hillclimb climber show openevolve prints it as the block it is; hillclimb climber new mine --from greedy copies greedy's source into climbers/mine.py for editing. See docs/climbers.md.
• Compare two. hillclimb run heilbronn-11 --climber greedy --climber openevolve --parallel-searches 2, then hillclimb experiment report <run-id>. See docs/experiments.md.

Example problems

Construction problems in one shape: the submission is a small CSV of numbers, the verifier checks the constraints and computes the score exactly, there is no dataset, no holdout split and no noise. Each ships with the best known value as a reference line on the chart, and each family is a ladder, so a ten-minute run visibly climbs on the small instance and an hour does not saturate the large one.

hillclimb problem list prints the catalog with the best known value and who found it. Problems that need data, a hidden split or a provider (Kaggle competitions through MLE-bench, energy forecasting through emflow) are documented in docs/providers.md.

Climbers

A climber is one block of config, defined where the run is defined — in a run spec, or in hillclimb.yaml as the folder's default:

climber:
  policy: greedy                  # what to try next (or `loop:` for the whole control flow)
  select: map-elites              # which candidate it expands
  operators: [draft, debug, improve, crossover.py:Crossover]
  tuner: optuna
  memory: files
  params: {num_drafts: 5}

Every slot names a prebuilt module, a .py file of your own, or package.module:Class. Three presets stand for whole blocks: greedy (debug failing tips, draft a few branches, improve the best), openevolve (the same schedule over a MAP-Elites archive) and gepa (reflective Pareto search, brings its own loop). The same building blocks compose in Python:

import hillclimb as hc

climber = hc.Climber(policy=hc.policies.Greedy(num_drafts=5), select=hc.selectors.MapElites(), tuner="optuna")
hc.run("heilbronn-11", climber=climber, budget="10m")

A run records the block it ran, a search snapshots its climber (so editing the live files never changes a running search), and hillclimb climber check replays recorded journals through an edited climber before an agent hour is spent on it.

What is where

Docs

• Problems — the verifier contract, floors, unit tests, tunable parameters, per-instance scores, noise
• Climbers — the climber: block, presets, your own policy / selector / operator / loop, composing in Python, climber check, mixed fleets, GEPA
• Agents — Claude Code, Codex, pi; connect; billing through OpenRouter; sampling
• The sandbox — what agents and solutions can write, read and reach; agents without internet
• Experiments — studies of experiments, repeats, matched budgets, the report
• Providers — emflow, MLE-bench, Einstein Arena
• Operators and memory — operator scaffolds, model routing, the knowledge graph
• The hillclimb dir — config precedence, run specs, how runs are laid out, the store, pruning
• Commands — every command, the TUIs, the demo suite
• Development
• Changelog