Quickstart
Install the CLI, get a problem, start climbing.
$ pip install hillclimb$ claude login # agents run through the Claude Code CLI$ hillclimb problem get heilbronn-convex-13$ hillclimb run heilbronn-convex-13 --budget 30m --parallel-searches 2$ hillclimb watch # the searches, live
The four steps
Install the CLI. It needs Python 3.12+ and a logged-in claude or codex to drive.
pip install hillclimbAgents and solutions run inside a sandbox. macOS has it built in; on Linux
install it once with sudo apt install bubblewrap.
Get the problem definition into your working directory. This creates a hillclimb/ folder and
copies the bundled Heilbronn-triangle problem into hillclimb/problems/. The file verifier.sh
is the only process hillclimb ever starts and verify.py is the scorer that it's using. The
following command gets the Heilbronn triangle problem into your working directory (get a feel for
this problem here).
hillclimb problem get heilbronn-convex-13Start climbing. Parallelism in hillclimb has two levels: --parallel-searches is how many
independent searches (exploration trees) attack the problem (each its own engine process, all in
one run so they share what they learn), --parallel-agents how many coding agents each search
keeps busy at once, each generating one candidate at a time running in the background.
hillclimb run heilbronn-convex-13 \
--budget 30m \
--parallel-searches 2 \
--parallel-agents 3 \
--agent claude-code \
--model claude-sonnet-5Then run hillclimb watch for the watching the agents in action, hillclimb chart for the chart
with successive progression. hillclimb stop --all ends it, and the best solution.py of every
search stays in hillclimb/runs/.
Or in one command
hillclimb demo is problem get + run --parallel-searches in one command:
hillclimb demo --budget 10m --parallel-searches 3 --parallel-agents 3Run hillclimb problem list to see the bundled catalog. It currently includes circle-packing,
knapsack, and heilbronn-convex-13. Get one with hillclimb problem get <problem> before
running it.
hillclimb stop --all ends the demo (the best solutions stay in runs/); hillclimb reset ends
it AND deletes this folder's hillclimb/ dir — only engines pinned to that dir are killed, never
another folder's; 3 searches x 3 agents is 9 agents, capped machine-wide by
concurrency.machine_max_agents; each search's engine log is under hillclimb/runs/<run-id>/logs/.
Try it without spending agent calls
--agent dummy runs the whole engine — candidate dirs, journal, charts, TUIs — with a scripted
operator and no model calls at all.
While they climb
hillclimb watch candidates # one search's candidates: drafting, debugging, improving
hillclimb watch # all the searches side by side
hillclimb chart # the hillclimb: best score so far across every search, every candidate a dot
# (several charts in the folder: a table first — enter opens one, esc comes back)
hillclimb graph # the knowledge graph growing as searches finish
hillclimb tree # one search's exploration tree: expanded vs discontinued lineages
hillclimb chart --detail # the curve with that tree drawn on it (every scored candidate, parent edges)