indexhillclimb

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 typeWhat Hillclimb improves
OptimizationPacking, routing and scheduling solutions, scored by solution quality, cost or constraint violations.
Prediction and forecastingTraining and prediction code, evaluated on hidden data using metrics such as MAE, pinball loss or CRPS.
Performance engineeringCode for a fixed workload, scored by runtime, memory use, binary size or another resource constraint.
Parameter fittingEstimation code that recovers unknown parameters, tested against cases with known ground truth.
Strategies and policiesDispatch, bidding and cache-eviction strategies, evaluated by replaying historical or simulated scenarios.
Generated artifactsSQL queries, regular expressions, solver configurations and prompts—anything that can be generated and scored.
Mathematical discoveryConstructions, 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 verifiers

Two 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:

partwhat does it decide?comes with
selector policywhich candidate to build on nextBest, MapElites
operator policywhich operator to use on itGreedy
operatorswhat the agent is asked to doDraft, Debug, Improve
tunerwhich parameter values to tryRandomSearch, Optuna
historynothing. It is the record of this search: every candidate, its score, its parentthe journal
memorywhat to keep from earlier searches, and leave for later onesFilesMemory, 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.

You or your agent call the hillclimb CLI, which runs the search, scores every candidate through the verifier, journals it and keeps the best. It executes each step by running one headless coding agent such as Claude Code or Codex. you, or your top-level agent hillclimb CLI runs the search, scores through the verifier, journals every candidate, keeps the best claude code codex … headless coding agents as operators

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.

problemyou writeproblem.yaml · description.md · verify.py · interface.pyclimberdecidesselectorpolicyoperatorpolicyoperatorstunermemoryharnessfixedloop · sandbox · scoring · budget · history (journal)agentwrites codeclaude code · codex · pi

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:

climberdecidesharnessfixedagentwrites codenext step, until the budget closesattemptsandboxedsolution.pyoutcomeproposepreparecandidateeditverifyjournalobserve

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

fromhowread more
the CLIhillclimb run … — the headless engine, every command and flagCLI reference
PythonClimber(...).search(problem) — the same search from a script or a notebookPython SDK
your agentthe skill that lets Claude Code start, watch and steer runs for youSKILL.md

Next steps