Quickstart
Install the CLI, get a problem, start climbing.
Quick quickstart
Seven commands, then you lean back.
uv tool install hillclimb
hillclimb --help
hillclimb connect claude # or codex, pi, openrouter
hillclimb init
hillclimb problem get heilbronn-convex-13
hillclimb run heilbronn-convex-13 --budget 30m --parallel-searches 2 --parallel-agents 3
hillclimb watchEvery command, one at a time
Install the CLI through PyPI, it needs Python 3.12+.
uv pip install hillclimbOr install it once for your whole machine, so hillclimb works without activating an
environment:
uv tool install hillclimbAgents and solutions run inside a sandbox. macOS has it built in; on Linux
install it once with sudo apt install bubblewrap; on Windows, run hillclimb inside
WSL2.
Check out the hillclimb commands (and enjoy our ASCII art).
hillclimb --helpConnect your coding agent, hillclimb will use it in the background.
hillclimb connect claude # or codex, pi, openrouterDo this once, even if you are already logged in to Claude Code or codex: operators run in a home of
hillclimb's own, so your settings, plugins and skills stay out of a search, and that home logs in on its own.
Your own login is left as it is. Skip it and hillclimb run stops before it starts, asking you to connect.
Initialise hillclimb to make your working directory a hillclimb dir. By default everything
hillclimb reads and writes lives here: hillclimb.yaml, problems/, runs/ (with the run defaults in runs/config.yaml) and climbers/.
hillclimb initThe command hillclimb problem get [problem] gets the problem definition into your working
directory. The following command loads the Heilbronn triangle problem (get a feel how to hillclimb
on this problem here).
hillclimb problem get heilbronn-convex-13Start climbing. Parallelism in hillclimb has two levels: --parallel-searches is how many
independent climber 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.
# --budget: or CPU time, tokens, evaluations
hillclimb run heilbronn-convex-13 \
--budget 30m \
--parallel-searches 2 \
--parallel-agents 3 \
--agent claude-code \
--model claude-sonnet-5Then run hillclimb watch to open the TUI, then lean back and watch as the agents search action.
Some other useful commands are hillclimb chart, which gives the chart with successive progression
and hillclimb stop --all stops the run. At the end of the run you can run hillclimb summit to
extract the best solution.py and its submission.csv into the root of your working directory.
hillclimb watchRun hillclimb problem list to see the pre-created problems. It currently lists 23, among them
circle-packing, knapsack, and heilbronn-convex-13. Get one with hillclimb problem get <problem> before
running it.
hillclimb stop --all ends every search (the best solutions stay in runs/); hillclimb reset ends
it AND deletes what hillclimb made in this folder (problems/, runs/, …) — only engines pinned to that dir are killed, never
another folder's; 2 searches x 3 agents is 6 agents, capped machine-wide by
concurrency.machine_max_agents; each search's engine log is under 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 # all searches, live
hillclimb watch candidates # one search's candidates
hillclimb chart # best score so far
hillclimb chart --detail # the chart with its tree
hillclimb tree # one search's tree
hillclimb graph # the knowledge graph