Examples

The repository has an examples/ folder with one script for each thing on these pages. Claude Code writes the solutions, so you see real code being written and scored in the background. Most of them run on fitness-landscape; pass toy on the command line and they run on the free scripted agent instead, in seconds, which is also how the test suite runs them.

If you read one, read nano_climb.py. It is the smallest complete hill-climbing agent: the problem is "compute digits of pi", the selector picks the best attempt so far, the policy says write or revise, and the two operators are the two prompts. Nothing sits in a config file.

script	shows
`nano_climb.py`	the whole thing in one file, about a hundred lines: a problem, a selector, a policy, two operators, a budget, a search. Start here
`run_and_read.py`	build a climber, `climber.search(problem)`, read the result off it: best, history, spend, a table of candidates
`step_by_step.py`	`climber.start`, then `propose`, `run` and `step` by hand, a move of your own, then `finish`
`custom_policy.py`	your own `OperatorPolicy`, compared with two others on the same budget
`custom_operator.py`	your own `Operator`, and the prompt it writes
`custom_selector.py`	your own `SelectorPolicy` under the built-in greedy policy
`custom_agent.py`	`register_agent` with a scripted agent of your own
`define_a_problem.py`	`Problem(name, score=...)`: a problem of your own from a scoring function, searched

From a checkout of the repository, which is a hillclimb dir already, with a logged-in claude:

uv run python examples/run_and_read.py          # Claude Code, a few minutes
uv run python examples/run_and_read.py toy      # the scripted agent, a few seconds

Anywhere else, after pip install hillclimb, make a folder a hillclimb dir first:

hillclimb init
python run_and_read.py

Here is what one of them prints on the scripted agent. Three policies get the same thirty evaluations. The peak is at 17.11 and the best decoy at 13.00.

best elevation after 30 evaluations (the peak is 17.11, the best decoy 13.00):
  drafts only         12.067   {'draft': 30, 'baseline': 1}
  draft, then climb   15.629   {'improve': 26, 'draft': 4, 'baseline': 1}
  greedy              16.645   {'improve': 9, 'draft': 3, 'baseline': 1}

Each search lands in runs/, so you can look at it with hillclimb watch, hillclimb chart or hillclimb surface, which draws the candidates on the 3D terrain.