Ollama Pre-Commit Hook: Field Notes on Wiring a Local Model Into git commit

Git runs .git/hooks/pre-commit before it asks for the commit message. The githooks manual gives the two facts that shape everything else: the hook takes no parameters, and a non-zero exit aborts the commit. It also says the hook "can be bypassed with the --no-verify option".

So the hook reads the staged change itself (git diff --cached), and it can only ever be a guard rail, never a gate: anyone can step around it. That is the right size for a model's opinion anyway.

Kept: read the staged diff, exit 1 only to block.

Ollama listens on 127.0.0.1 port 11434 by default (Ollama FAQ), so the diff never leaves the machine. The API reference describes POST /api/generate as a streaming endpoint; with "stream": false it returns a single JSON object with the whole reply in response. A hook has no use for tokens arriving one by one, so streaming goes off.

Kept: /api/generate, stream: false.

Free text is useless to a shell script. The same API reference says the format field takes either json or a JSON schema, and that the model then returns a response matching the schema. It also warns to ask for JSON in the prompt as well, or the model "may generate large amounts whitespace".

The schema here has two fields: verdict, limited to pass or block, and a list of findings with file, line and issue. The script reads verdict and nothing else decides the exit code.

Kept: a schema in format, and "Answer in JSON" in the prompt.

The FAQ states that Ollama uses a context window of 4096 tokens by default, changed per request with options.num_ctx or for the server with OLLAMA_CONTEXT_LENGTH. The prompt, the whole diff and the answer have to fit in it. A refactor that touches twenty files does not.

The hook asks for num_ctx: 8192 and skips any staged diff over 20,000 bytes, printing that it skipped. The byte cap is a rough guard picked for this log, not a token count: tune it to your model and your memory. Lock files are left out of the diff, since no reviewer reads them.

Kept: raise num_ctx, cap the diff, say so when skipping.

A model has to be loaded into memory before it answers. The API reference gives keep_alive a default of 5m: five idle minutes and the model is unloaded, so the next commit pays the load again. The final response reports this cost as load_duration, in nanoseconds, so you can see it on your own machine.

The hook sends keep_alive: "30m". The FAQ also shows how to preload a model with an empty request, which fits in a shell profile or an editor start-up task.

curl http://127.0.0.1:11434/api/generate -d '{"model": "qwen2.5-coder:7b", "keep_alive": "30m"}'

Kept: keep_alive: "30m"; preload optional.

A reviewer that blocks a commit, then passes the identical retry, teaches everyone to retry. The API reference passes temperature through options and says that for reproducible outputs you set seed to a number. The hook sets temperature: 0 and a fixed seed.

Kept: temperature 0, fixed seed.

The laptop is on battery, Ollama is not running, or the model is not pulled yet. If the hook fails closed, every one of those becomes a blocked commit and a --no-verify habit. So any failure to get an answer (no connection, an HTTP error, a 90-second timeout, a reply that is not JSON) prints one line and exits 0. Only a well-formed block verdict stops the commit. The trial runs below show both paths.

Kept: fail open, loudly.

A model asked to "review this code" will always find something: a name, a missing comment, a style it prefers. If any finding blocks, the hook blocks every commit. The prompt names the only reasons to block (a leaked secret or key, a debug statement left in, an obvious crash such as a null dereference, code that cannot run) and says style and naming never block. Findings still print on a pass; they just do not stop anything.

How well a given model keeps to that list is the part this log could not test, and it is the part to watch in your first week: count the blocks you overrode.

Kept: a closed list of block reasons; everything else is advice.

The hook reads its model from LLM_REVIEW_MODEL and defaults to qwen2.5-coder:7b. The Ollama library page lists that family in six sizes, from 0.5B to 32B parameters, so the same hook can run a small model on a laptop and a large one on a desktop with a big GPU. ollama ps shows whether a loaded model sits on the GPU, the CPU or both (FAQ).

ollama pull qwen2.5-coder:7b

Kept: model in an environment variable, 7B as the default.

Teams that already use pre-commit can register the script as a local hook. Its docs list the parts that matter here: pass_filenames defaults to true and must be false, because the script reads the diff itself; the language for a plain system executable is now called unsupported ("new in 4.4.0: previously language: system", and the old alias will be removed); and SKIP=llm-review git commit skips this one hook without turning the others off.

repos:
  - repo: local
    hooks:
      - id: llm-review
        name: local LLM review of the staged diff
        entry: .githooks/llm-review
        language: unsupported
        pass_filenames: false
        stages: [pre-commit]

Kept: language: unsupported, pass_filenames: false.

The hook was installed in a scratch repository and pointed at a stand-in server on a spare port that answers /api/generate with a fixed verdict. That tests the plumbing (diff, request, parsing, exit codes), not a model's judgement.

In run 2 the request the server received carried stream: false, the schema with verdict limited to pass and block, and the options temperature 0, seed 7 and num_ctx 8192.