quickstarthillclimb

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 watch

Every command, one at a time

Install the CLI through PyPI, it needs Python 3.12+.

uv pip install hillclimb

Or install it once for your whole machine, so hillclimb works without activating an environment:

uv tool install hillclimb

Agents 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 --help

Connect your coding agent, hillclimb will use it in the background.

hillclimb connect claude  # or codex, pi, openrouter

Do 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 init

The 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-13

Start 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-5

Then 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 watch

Run 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