Sphinx Makes You Prove You Understand Your AI Agent's Code Before You Push

A small open-source Git hook asks one question about your agent's change before it lands on main. The question is about you, not the code.

Coding agents have made writing code cheap. Reading it has not gotten any cheaper. A new open-source Git hook called Sphinx bets the fix is to quiz the human, not the code.

So a strange thing happens on a lot of teams now. The agent writes a few hundred lines, the tests pass, the diff looks reasonable at a glance, and it ships. Weeks later something breaks at an odd hour, and the person who merged it opens the file and sees it, really sees it, for the first time.

Every review tool on the market asks whether the code is right. Sphinx asks whether the person pushing it understands what it does when things go wrong.

That is a small shift with a real payoff. You can delegate the typing. You cannot delegate being the one who gets paged.

What Sphinx is

Sphinx is a free, MIT-licensed Git hook (a script Git runs automatically at certain moments, here right before a push). It appeared as a Show HN on October 18, 2026 (the project site is here), and its npm package, sphinx-understand, has shipped five versions since October 16 per the npm registry. It is very new. As of October 18, npm's latest is 0.1.4 (the repo's main branch still declares 0.1.3), GitHub shows about 40 stars, and there are no GitHub releases yet.

Its tagline is the whole pitch: "Outsource your thinking, not your understanding."

It works alongside the agents most people already use. The README lists Codex, Claude Code, Cursor, OpenCode and Pi, or plain Git with no agent at all.

How a check works

Say your agent just rewrote the retry logic in a payment client, and you push to main. Here is what happens, per the README:

1. Git pauses the push.
2. A separate reviewer model reads the committed change through read-only Git tools.
3. It asks you to predict what the change will do in a specific situation, usually a failure. Think "what happens if the second retry times out after the first one already charged the card?"
4. If you answer correctly, the same push continues. If you answer wrong, you get an explanation and a new scenario.

Small changes get one question. Large ones get up to three at the default depth. A pass lasts 24 hours unless the code, the destination branch or your policy changes, so pushing the same change twice does not quiz you twice.

The design choice that matters

The reviewer "does not see the conversation that produced the code." That one line is the interesting part.

Think about how you usually learn what an agent did. You read its summary. The summary is written by the same model that wrote the code, and it is persuasive by design. It tells you what the code is supposed to do. If the code does something else, the summary will not mention it, because the agent does not know.

Sphinx's examiner has no summary to lean on and neither do you. It only has the diff and the related files, so its questions come from what the code actually does. And your answers, the README says, never reach the coding agent, so the agent cannot help you pass.

That is the insight worth taking even if you never install it. Review asks "is this code right?" Sphinx asks "do you know what this code does when it breaks?" Those are different checks, and most teams only run the first one.

Put this into practice

You need Node.js 22.19 or newer, Git, and macOS, Linux or WSL. Native Windows is not supported yet.

npm install -g sphinx-understand
sphinx install

sphinx install walks you through picking a reviewer model and loading Sphinx into your agent. Know that it sets your global Git core.hooksPath (the setting that tells Git where to find hook scripts), so it touches every repository on the machine; per the README, "Your existing hooks still run first." For an unattended setup with Claude Code, the README gives:

sphinx install --yes --preset claude-economy --agents claude

Then set up each repository:

cd your-repo
sphinx init
sphinx doctor

sphinx init creates three files. .sphinxconfig holds your policy, .sphinxignore lists paths the reviewer must never read, and .sphinxcontext.md is a short description of the project that goes along with every request. Write that description well. Beyond the changed code and your answers, it is the only standing context the examiner gets about your project.

Each agent needs one manual step. In Codex you open /hooks and trust the Sphinx hooks yourself (Sphinx cannot do it for you). In Claude Code, Sphinx installs questionnaire hooks plus an MCP server, a small plug-in service the agent can talk to; start a new session and check that /mcp shows sphinx connected.

Out of the box, pushes to main and master are checked in every repository. Then push something and answer your first question.

What to expect. A typical check makes about 5 to 8 model requests, plus about one per answer. A blocked push waits up to 25 minutes for you. There is no default cap on model calls; set one with sphinx config --max-model-calls.

Which model asks the questions

You choose. Sphinx can use a signed-in Codex or Claude Code CLI, which spends that plan's allowance; an OpenRouter key, which bills separately and is required even for free models; or any OpenAI-compatible endpoint. Guided setup suggests Haiku through Claude Code or GPT-6 Luna through Codex.

Cost per check should be small with a cheap model. The project's own evaluation notes report $0.344 in total across 472 requests in their exploratory runs, under a tenth of a cent per request. Those are the maintainer's numbers on test repositories, and the notes warn that zero-cost entries in their logs do not prove a route is free.

What leaves your machine. The reviewer receives the changed code and related files from the commit, your answers, and .sphinxcontext.md. Sphinx has no hosted service of its own, so that data goes only to the model provider you picked. .env files, private keys and common credential files are excluded by default. The README is honest about the gap: ignore rules match file paths, so they "will not catch a secret pasted into ordinary source."

A worked example

Here is what a good setup looks like for that payment client from earlier. This is an illustration, not real Sphinx output; the site itself notes its sample questions are illustrative and real ones come from your diff.

A useful .sphinxcontext.md is short and says what matters to the business, not how the code is laid out:

Payments client for an online store. Card charges go through an
external processor. A duplicate charge is the worst failure we can
have. Timeouts from the processor are common at peak hours.

With that context, a question about the retry change might read: "The processor times out on the first attempt but actually completes the charge. What does the new retry code do next, and does the customer get charged twice?"

A passing answer names the behavior: "It retries with the same idempotency key (a unique ID that tells the processor this is the same charge as before), so the processor returns the original charge and nothing new is billed." A failing answer describes the intent: "It retries up to three times so payments are more reliable." The second answer is what the agent's summary would have told you. The first is what you need to know at 3 a.m.

If you get it wrong, that is the point. You just found out, before your customers did, that you did not know whether the agent kept the idempotency key.

Honest limitations

Sphinx says the most important thing about itself plainly: "This is practice, not a security gate." Anyone with local access can bypass Git hooks. It does not stop a bad change from shipping. It makes you look at it.

The examiner is an LLM, and the README says it "can be wrong." The evaluation notes show this in the numbers. They used five small synthetic repositories, and in one run with Claude Haiku 5.5, 33 of 39 test answers were graded the way the authors expected. In other runs, good-enough answers about styling and authorization were wrongly rejected. The authors call their results "not an all-green quality result" and say they do not certify arbitrary repositories. Expect the occasional bad question and the occasional unfair "wrong."

The skip button is always there. "Skip this time" lets a push through immediately, and sphinx yolo turns checks off for a repo, or for everything when run outside one. Skips are logged with an optional reason and never count as passing, and sphinx status lists recent ones. On a team, that log is the real enforcement, and only if someone reads it.

Version 0.1 also covers only local commits and pushes. Merges made in the GitHub web interface, required CI checks and deployments are out of scope. If your team merges pull requests in the browser, Sphinx never sees them. It cannot read binary files either.

And it costs attention. A question takes a minute or two. On a day with twenty pushes, that adds up, which is why the 24-hour pass and the protected-branch default matter. Keep it on main and off your scratch branches.

Who should try it

Solo developers and small teams who ship agent-written code to a main branch they personally own get the most from it. If you have ever merged something you could not explain an hour later, this is a cheap habit-builder.

Teams that already require human review on every pull request will get less. Their gate lives in the browser, where Sphinx does not reach yet. For them, the idea is worth more than the tool: ask the reviewer to state, in one sentence, what happens when the change fails.

What to do with this

Install it on one repository you care about, the one where a 3 a.m. page would land on you. Run it for a week. Count how often the question catches something you had not thought about, and how often it is just noise.

If the count is mostly noise, uninstall it and keep the question. If it catches even one thing, you have your answer.

Sources: parthh01/sphinx README and evaluation notes on the main branch (no tagged release yet), read October 18, 2026; sphinx-understand on npm, version 0.1.4; Sphinx site.