Sphinx: The Git Hook That Quizzes You on AI Code
Sphinx holds a git push until the developer can explain the AI-written change. This guide covers when a comprehension gate helps, where it misleads, and why its logged skip list is the real control.
The Short Answer
AI coding agents have changed the hardest part of shipping software. Writing code is no longer the slow step for many teams. Reading it, understanding it, and standing behind it is. That is the gap the Sphinx git hook AI code quiz is built to close. Sphinx is an MIT licensed git hook that holds…
AI coding agents have changed the hardest part of shipping software. Writing code is no longer the slow step for many teams. Reading it, understanding it, and standing behind it is. That is the gap the Sphinx git hook AI code quiz is built to close. Sphinx is an MIT licensed git hook that holds a push until the developer can answer questions about the change.
Posted to Show HN on October 18, 2026, Sphinx asks an uncomfortable question. If an agent wrote the code, and you have not read it closely, should you ship it? Coverage put it at about 252 Hacker News points by October 20, 2026. Its first commit dates to October 14, 2026. Sphinx does not test the code. It tests the person.
This is a business guide, not a repeat of the launch announcement. It explains how Sphinx works, where it helps, where it can mislead, and how to adopt it without turning it into theatre. The central point is plain. A quiz you can bypass with one command is a habit, not a control. The logged list of skips is the real control.
How the Sphinx git hook AI code quiz Works
Sphinx installs as a git hook and runs on pushes to branches you protect, such as main or master. When you push, git waits while Sphinx shows a short questionnaire in the browser. A separate reviewer model reads only the committed diff, through read only git tools. That model never sees the conversation between the developer and the coding agent.
The questions focus on behaviour, failure modes, and invariants, not on file names or trivia. A good question asks what happens when input is missing, when a dependency times out, or when part of the change fails. Sphinx asks one to three questions at its default depth, with up to five reported in some accounts. You answer with a prediction and a short reason. A correct answer lets the push continue. A wrong answer brings an explanation, then another scenario on the same concept.
Install it globally from npm as sphinx-understand, then run its install command to set your global git hooks path, and its init command in a repository to write its configuration files. Those files let a team choose protected branches and ignored paths. Sphinx works with Codex, Claude Code, Cursor, OpenCode, and Pi, plus plain git. It needs Node.js 22.19 or newer, and supports macOS, Linux, and Windows Subsystem for Linux. The questionnaire is open book, so you can study the diff while you answer. The pause is the product. The quiz makes that pause hard to fake.
Why the Bottleneck Moved From Writing to Verifying
Before coding agents, the bottleneck was production. A developer typed slowly, thought while typing, and usually understood the result. Agents reversed that sequence. A developer can now receive hundreds of lines in seconds, across files they did not open, using libraries they did not choose. Review becomes the work, but review is the step most rushed when a deadline nears and tests are green.
Green tests do not prove understanding. Tests prove that the cases somebody wrote behave as expected. They do not prove the shipper knows what happens in cases nobody wrote. That is where incidents live: a missing input, a slow dependency, a retry that doubles an action, or a fallback that silently discards data. A comprehension gate asks the shipper to predict behaviour before users discover it. That is why Sphinx belongs inside a broader quality effort, not as a replacement for it. A structured approach to software testing and QA still matters. Our guide to testing AI generated code makes the same point: agent written code needs deliberate verification, not a faster glance.
When the Sphinx git hook AI code quiz Helps, and When It Hurts
Sphinx helps most when a team ships agent written code it has not read. A developer prompts an agent, accepts a large diff, runs the tests, and pushes. The quiz interrupts that loop before code leaves the machine. It helps most on high stakes paths: payment flows, authentication, data migration, and integrations where failure is hard to reverse. It also trains developers. Answering forces them to trace data, name edge cases, and state the failure path in their own words.
But a gate can hurt if applied without judgement. Quizzing a developer on a typo fix or a trivial config edit teaches them the gate is noise. Once it feels like noise, they look for the fastest way past it, and that habit carries to changes where the gate matters. Protect only branches where understanding is genuinely load bearing.
The second risk is subtler. The grader is itself a model. Sphinx says so openly, and its evaluation notes say its semantic evaluation is not all green, even though hundreds of guarded unit and integration tests pass. Unit tests check that the pipeline moves data correctly. They do not guarantee fair judgement of a free text answer. A good answer in different words can still be marked wrong. Teams should expect false negatives, and provide a dispute path and a human override.
The third risk is false confidence. Passing a quiz does not prove a change is correct. A developer can pass on code that is still wrong, because the quiz tests their model of what code should do, not whether every line matches that model. A leftover debug statement or a weakened assertion can survive any quiz. That is why the project calls itself practice, not a security gate. It improves people. It does not certify code.
Questions that test behaviour, not trivia
Question quality decides everything. Asking for a function name or a file path tests memory, not understanding. It rewards skimming for labels instead of tracing behaviour. Apply a simple test. If a developer can answer by searching the diff for a word, it is trivia. If they must predict behaviour in an unseen scenario, it is a real comprehension question. Review early questions together, dispute weak ones, and refine context files so the reviewer aims at failure paths.
The Logged Skip Is the Real Control
Here is the insight that matters most for team leads. Sphinx has a command, sphinx yolo, that bypasses the check. The questionnaire also offers a skip option, and git has its own hook skipping flag. The quiz cannot stop a determined developer. The hook can be removed, and an agent could even be asked to answer. Sphinx tells users not to let an agent answer, but it cannot enforce that from the developer's own machine.
What changes the equation is logging. Every sphinx yolo skip is logged. That turns a private shortcut into a visible record. A lead can review skips, ask why a push skipped, and spot patterns: constant skipping, skips clustering before releases, or skips on the riskiest modules. The quiz trains individuals. The skip log governs the team.
Any bypassable control should leave a receipt. Silent bypasses teach people rules are optional. Logged bypasses teach people exceptions are accountable. Review the skip log weekly, discuss it without blame, and agree in advance when a skip is legitimate, such as an incident fix watched live by a human reviewer. A skip with a reason, recorded at the time, is a judgement call. A skip with no reason, found later, is a culture problem. The optional GitHub commit status Sphinx posts is visibility, not enforcement, because it comes from the pusher's own machine. Real enforcement lives in protected branches, reviewed pull requests, and server side checks.
Adopting It Without Turning It Into Theatre
Start small. Pick one repository, protect one branch, and run Sphinx for two weeks before expanding. Collect three things in the pilot: useful questions, trivia questions, and skips with reasons. If useful questions are rare, fix the context file before blaming the tool. If skips are frequent, ask whether the scope is too broad or the dispute path too slow. Friction data is diagnostic data.
Set the rules in writing before the pilot ends. State protected branches, who may skip and when, how skips are reviewed, and how disputed questions are handled. Keep the dispute path short, or developers will bypass the gate rather than argue with it. Pair Sphinx with checks it cannot replace: tests, human review, and security scanning in continuous integration. For teams building custom software and enterprise systems, where one misunderstood integration can affect operations for months, that human check is worth protecting, even though it never replaces the rest of the pipeline.
- Agent written change to payments, auth, or data migration: use the gate, because failure is expensive and hard to reverse.
- Large diff the author has not fully read: use the gate, because the quiz forces the read that time pressure skipped.
- Trivial copy, typo, or config change: skip the gate, because quizzing noise teaches developers to bypass it everywhere.
- Emergency fix with a live reviewer: skip, and log it, because speed matters but the log keeps the exception accountable.
- As a replacement for tests or security review: never use it this way, because a quiz checks the person, not the code.
What Sphinx Cannot Do
Sphinx cannot verify that a diff is correct, secure, or complete. It cannot catch a bug the developer also misunderstands. It cannot stop a developer who removes the hook, or prove to an outsider that a check happened, since it runs locally. Independent assurance still needs server side checks, reviewed pull requests, and audit trails. It also cannot fix a review culture alone. If pull requests are approved without reading, a pre push quiz feels like a chore, not a safeguard. When we examined why test design matters in AI evaluation, the lesson was similar: check design decides what a check can prove. The gate is a prompt to think, not a verdict on risk.
Frequently Asked Questions
What is Sphinx?
Sphinx is an MIT licensed git hook that holds a push to a protected branch until the developer answers questions about the diff. A separate reviewer model, which never sees the developer's agent conversation, reads only the committed diff and asks what the change does, especially under failure conditions such as missing input, timeouts, or dependency behaviour. A correct answer lets the push continue. A wrong answer brings an explanation plus another scenario.
Does Sphinx replace code review or testing?
No. Sphinx tests the person shipping the code, not the code itself. It cannot catch every bug or certify security, and the project calls itself practice, not a security gate. Tests, human review, and server side checks remain essential.
Which coding agents does Sphinx work with?
Sphinx works with Codex, Claude Code, Cursor, OpenCode, and Pi, plus plain git. It installs from npm as sphinx-understand. It can post a pass as a GitHub commit status, but that status comes from the pusher's own machine, so treat it as visibility, not enforcement.
Can developers bypass the quiz?
Yes. The sphinx yolo command bypasses the check, the questionnaire offers a skip option, and git hook skipping flags also exist. The key difference is that sphinx yolo logs every skip. Review that log regularly, and agree in advance when a skip is legitimate, so bypasses stay accountable, not invisible.
What happens if the grader marks a good answer wrong?
This can happen, because the grader is a model judging free text answers, and the project's evaluation notes say its semantic evaluation is not all green. A gate that fails closed then is safe, because nothing ships, but unfair to the developer. Provide a quick dispute path and a human override.
How should a business start with Sphinx?
Start with one repository and one protected branch, run a two week pilot, and review useful questions, trivia questions, and the skip log together. Protect only branches where understanding is load bearing, write down skip rules before expanding, and keep Sphinx alongside tests, review, and continuous integration.
If your team ships agent written code faster than it can review it, that gap will not close on its own. A comprehension habit, backed by a visible skip log and a real review process, is a practical place to start. To talk through how a verification workflow fits your product and release process, contact Skills Technology Solutions and tell us where your review bottleneck sits today.
Related Articles
Keep reading — more guides you may find useful.
Related Services
Services connected to this guide.
