ISSUE 067  ·  17 NOVEMBER 2026 ELEN RSS
CodeCity
AUTOMATION № 0049

lefthook: the checks you forget become automatic, and they run in parallel

lefthook: οι έλεγχοι που ξεχνάς γίνονται αυτόματοι, και τρέχουν παράλληλα

lefthook: the checks you forget become automatic, and they run in parallel

What it does

You have caught yourself pushing code you never checked. You did not do it out of carelessness. You were tired, or in a hurry, or you simply forgot. lefthook exists so that does not happen.

Two words first, because without them the rest makes no sense. “Git hooks” are points where git pauses and gives you the chance to run something of your own before it moves on. The best known is pre-commit: it runs right before the commit is sealed. commit-msg runs when you write the commit message. pre-push runs just before you send to the remote. If one of those checks fails, the action is blocked.

lefthook takes over running all of them for you. It is a Go binary — an executable that needs no language or library installed behind it to work. It reads its configuration from a file of its own, lefthook.yml, where you write which checks run at which point. And the key part: it runs them in parallel, not one after the other.

That last point is the whole value. Picture five checks that each take two seconds. Serially, ten seconds. In parallel, near two. In practice the checks are the same ones you would run by hand — it is just that you never remember them, and you never wait for them.

The project is maintained by Evil Martians, the studio behind other well-known tools in the ecosystem. The repository has been alive since February 2019 and today holds 8,953 stars, 329 forks and 105 open issues, under the MIT licence, with the last activity on 26 October 2026 (repository).

One clarification you need from the start: lefthook is not an MCP server. It does not speak to the model, it loads no tool schema, it takes up no room in your session. It is a shell tool, and it runs when git runs.

Who it is for

For anyone working in a team, or alone across many projects, who wants to stop shipping code that breaks other people’s code. The beginner who just heard the word “agent” will grasp the benefit the first time they forget to run the tests: the tool runs them anyway, and the commit does not close if something fails. The professional gains something sharper: no more carrying the project’s rules in their head, because they write them once in the YAML and never think about them again.

It shines when a project has many checks — formatting, static analysis, tests — and the wait on every commit has started to annoy you. It shines in a project that will live a while, because the only thing you pass on to the next person is a text file.

It is not for you if you are working alone on a throwaway script you will never open again. There the setup cost does not pay back. And it is not for you if you want something that inspects code inside the conversation with the assistant; that is a different class of tool, and lefthook does not touch it.

Install

You want Node, only so it can fetch the binary; from then on the execution needs neither Node nor Python. The package’s engines field is empty (null) — it requires no version at all. npm here is the carrier, not the engine.

Run this from the root of your project:

npm i -D lefthook@2.2.2

Then write lefthook.yml at the root, with one hook you want. And then tell lefthook to install the hook itself into git:

npx lefthook install

That writes the hook into .git/hooks/pre-commit — the point git reads on its own. From here you call nothing by hand: git calls lefthook every time you commit.

One Windows trap we hit. npm gives you two files: a .cmd shim, and the real .exe under the lefthook-windows-x64 folder. If you call the shim from a bash shell, you get “No such file or directory” — it is not a lefthook fault, it is the shim that does not run that way. Through npx the problem does not appear.

The vendor documents other install routes — Homebrew, go install, a direct binary from the releases. That is a vendor claim: we only ran the npm route, and I will not describe steps I did not execute.

Using it per LLM

Care is needed here, because lefthook does not look like the tools we usually cover. It is not an MCP server. You do not write it an mcpServers entry, you do not declare an executable and arguments, you do not restart so the assistant can see it. You do not need to declare it at all.

The reason is simple and worth understanding. lefthook sits on top of the git hooks. The hooks run when git runs — which means also when the assistant commits. The agent does not need to know lefthook exists; git calls it on its own. The only thing you add per assistant is an instruction, so it does not break the hook with a bypass such as --no-verify. I stood up no session inside Claude Code, Codex or Cursor; the commands are shell commands, and I say where I know them from.

Claude Code

You write the project convention into CLAUDE.md: before every commit the hook runs, with no bypass. And if you want to test it yourself, you run this from the project root:

npx lefthook run pre-commit

Codex CLI

The same, in an instructions file AGENTS.md at the root. There is no settings section to add — just the convention and the same command:

npx lefthook run pre-commit

Cursor

Here too the same shape: one instruction in the project rules, no server declaration. To check by hand:

npx lefthook run pre-commit

In CI

This is where the great virtue of the YAML shows: the same file works in CI too, with no second configuration. You add a step that runs the same command before the build:

npx lefthook run pre-commit

That way the rules do not live on each person’s machine; they live in one file that goes through review like the rest of the code. The same configuration for local hooks and for CI is, in our view, the most underrated advantage of the tool.

Where it wins, where it loses

It wins on the core point: the checks you forget become automatic. In our test, a hook banning the word TODO blocked the commit with exit 1 when it found it, and passed with exit 0 when the file was clean.

It wins on speed. The run took 0.09 seconds for one hook — and because they run in parallel, the gap grows as you add checks. It wins on cleanliness: one static binary, zero runtime dependencies, no process left hanging. And it wins because the configuration is a text file that a human reads and CI executes the same way.

Now where it loses.

First, the innovation is modest, and we want to say so plainly. lefthook opens no new road. It replaces husky — the JavaScript-world tool doing the same job. It brings no new idea; it brings better execution. Parallel instead of serial, one static binary instead of Node, zero dependencies instead of a package tree. That is not a flaw — it is exactly why it is a good choice for a project that will live in six months’ time. But do not expect a revolution; expect something that works and stops bothering you.

Second, the trap of silence. When you run the hook with nothing staged, it is skipped with a message and exits with exit 0. So a broken hook can look like it passed, if you test it blind. We unpack that in the next section, because we found it ourselves and it is the most useful thing in this article.

Third, it wants YAML. Anyone who has never written YAML will make one indentation mistake. It is a small hurdle, but it is there.

Testing

Everything below we ran on Windows 11, on a Dell Inspiron 3576, with Node 26.7.0, no graphics card.

I set up a fresh git repository and wrote lefthook.yml with one hook banning the word TODO inside app.js. The first thing I ran was installing the hook:

npx lefthook install

It wrote the hook into .git/hooks/pre-commit, as expected.

Then I put a clean app.js in place, staged it and ran the check. It returned exit 0 and printed “done in 0.09 seconds”. Then I put a TODO inside, staged it, and ran again. It returned exit 1 — the commit is blocked. The promise holds: the check runs, judges, and stops the mistake.

And then the trap, which I discovered myself and which deserves a paragraph.

The first time I ran npx lefthook run pre-commit before doing git add, with an empty staging area. The hook was skipped. It printed no-todo (skip) no matching staged files and exited with exit 0. Had I not noticed, I would have recorded “it passed” — while in reality nothing had run at all. This is the silent failure that can burn you: a broken hook looks healthy if you test it without staging files. I learned it when my first run came back “clean” without having checked anything.

So the test recipe, in the order that works: install with npm i -D lefthook@2.2.2, write lefthook.yml, run npx lefthook install, git add your file, and then run npx lefthook run pre-commit. Skip the git add and you get a green light for work that never happened.

What I did not run, and I say so. I stood up no session inside Claude Code, Codex or Cursor — we do not have all of those on our machine, and I will not hand you steps I did not see. I did not measure peak memory: the process lives about 100 milliseconds, and a memory figure from such a short life would be invention. The repository figures — 8,953 stars, 329 forks, 105 open issues, MIT licence, last push 26 October 2026 — and the npm figures — 21,072,106 downloads from 26 September to 25 October 2026, latest version 2.2.2 published on 13 October 2026 — come from our research, as GitHub and npm report them.

What it costs

The model. Our own figure: zero tokens. lefthook is not an MCP server, it loads no tool schema, it takes no room in any session. You pay nothing in the assistant’s context, whether you use it or not.

The machine. Our own figure: 14 MB on disk, in one file — node_modules/lefthook-windows-x64/bin/lefthook.exe, 14,252,032 bytes. No process left running after execution. I did not measure memory, for the reason I gave.

In money, nothing. MIT licence, no key, no service, no account. There is no paid tier, and there is no telemetry we know of.

Vendor claim, not our own figure: platform support (macOS, Linux, Windows) and the full set of YAML features. We read those in the documentation; we did not test them one by one.

Verdict

Score: 8.3/10.

lefthook solves a problem you know but do not name: you push code you have not checked. It solves it automatically, in parallel, with one static binary that carries no dependencies. On our test: exit 0 on a clean file, exit 1 with one TODO, 0.09 seconds, 14 MB on disk, zero tokens in the model, zero money.

It keeps or loses the remaining points for three reasons. The innovation is modest — it replaces husky, opens no road, and its value is execution and maintenance, not the idea. The trap of silence is real: with no git add, the hook is skipped and exits with exit 0. And it wants YAML, which for some is a hurdle.

Where we recommend it without hesitation: when a project will live a while and you want the rules to live in one text file, the same for your machine and for CI. There lefthook is the right choice, precisely because it stops bothering you.

Sources: repository https://github.com/evilmartians/lefthook · npm package https://www.npmjs.com/package/lefthook · documentation https://lefthook.dev/ · releases https://github.com/evilmartians/lefthook/releases