Data storage

Everything a search does is recorded in your hillclimb dir, under runs/. It is the same whether you started it with hillclimb run, from Python with climber.search(...), or from a run spec.

runs/
└── <run-id>/                          # one run: one `hillclimb run`, one spec, one climber.search
    ├── run.yaml                       # what the run is: its name, target and problems
    ├── spec.yaml                      # every search as launched; `hillclimb run spec.yaml` reruns it
    ├── logs/                          # each search's engine log
    └── searches/<search-id>/          # one climber on one problem: <problem-id>, then -2, -3
        ├── search.yaml                # the search's settings, fixed when it starts
        ├── status.json                # live state: running or not, budget left, what is in flight
        ├── journal.jsonl              # every candidate and result, in order
        ├── climber/                   # a copy of the climber, which resume runs
        ├── control/                   # stop and prune commands waiting for the engine
        ├── best/                      # the selected solution.py and what it wrote
        └── candidates/<candidate-id>/ # one folder per attempt
            ├── prompt.md              # what the coding agent was asked
            ├── agent_stream.jsonl     # what it did
            ├── notes.md               # what it says it did
            ├── solution.py            # what it wrote
            └── trials/                # each scored run of that code

The journal is the record that counts. Everything you see in hillclimb watch, chart or status, and everything hillclimb resume picks up from, is read from it.

Only the engine writes

A search's records are written by its engine process and nothing else. The TUIs, hillclimb stop, prune and your own coding agent send commands to the engine instead. Never edit journal.jsonl or status.json by hand.

Files or a database

search.yaml, status.json, journal.jsonl and control/ are how the default DataStore keeps a search's records. You can keep them in one SQLite database instead:

hillclimb.yaml

store:
  backend: files        # the default: the folders above, readable and git-versionable
  # backend: sqlite     # one database file: store.sqlite in your hillclimb dir

With sqlite, a search folder only holds what has to be real files (candidates/, best/, climber/, logs), because coding agents and verifiers work on files. Everything else lives in the database. That makes views across many runs faster, and many engines can write to it at once.

hillclimb store sync copies the searches already in your folder into the DataStore you switched to, so earlier history shows up. hillclimb store searches lists what the DataStore holds.

Search states

state	meaning
`running`	the engine is alive and its heartbeat is fresh
`parked`	paused on purpose, for example by a rate limit or a cost ceiling; resume it later
`stopped`	stopped by you, with `hillclimb stop` or `kill`
`done`	the budget ran out
`failed`	the engine hit an error; `last_error` in the status says which
`crashed`	the engine died without saying so: its process is gone or its heartbeat went stale
`unknown`	no status record yet

parked, stopped and crashed searches can be continued with hillclimb resume.

Data storage

Files or a database

Search states

On this page