← Back to Blog

AI Extensions Digest: Sphinx, the git hook that quizzes you before your agent's code ships

📅 2026-10-21 🏷️ AI News

Sphinx is a Git hook that treats every push to a protected branch as a small oral exam. Before the code leaves your machine, it asks you to predict what the change will do. Answer well and the push continues; miss something and it explains the failure mode you overlooked, then tries you on a new scenario. The premise: you can outsource your thinking, but not your understanding.

The short version

Sphinx (parthh01/sphinx) installs a pre-push hook - created October 14, MIT licensed, 265 stars and 11 forks as observed on October 21, 2026. On a push to main or master it blocks Git for up to 25 minutes while a separate reviewer model, reading only the committed diff through read-only Git tools, quizzes you about behavior, failure modes and invariants. It works with Claude Code, Codex, Cursor, OpenCode and Pi, or plain git; the reviewer runs on your own Claude Code or Codex plan, OpenRouter, or any OpenAI-compatible endpoint. The README is unusually explicit about privacy (your code leaves the machine to the reviewer provider) and about what the tool is not ("practice, not a security gate"). I read the repository; I did not install or run it.

What it is

A quiz, gated on shipping. When you push to a protected branch, Git waits while Sphinx asks one question about what the diff does when things go wrong. The README's illustrative example is a background job queue: "The worker commits the operation but crashes before acknowledging the job. After redelivery, can the operation happen twice?" If your answer misses the failure mode, Sphinx explains it and generates a new scenario; once you pass, the original push continues. The questions target behavior and invariants, not file names, and the check is open-book - you may read the code, or ask your agent to show it to you, while you answer.

The design choice that makes it interesting: the examiner is a second model that reads the committed change through read-only Git tools and deliberately never sees the conversation that produced the code. Your coding agent's own account of its work cannot bias the quiz. That is the same separation-of-roles pattern as this week's Ledger Agent Intent story - the check on an agent's output sits outside the agent.

Setup, cost and limits, in its own words

Installation is one npm package (sphinx-understand) plus `sphinx install`, which sets your global Git core.hooksPath - meaning it applies to every repository on the machine until you tune it per-repo with `sphinx init`. Existing hooks still run first. Requirements: Node.js 22.19+, Git, macOS, Linux or WSL; native Windows is not supported yet. A blocked push waits up to 25 minutes for you to pass, pause or skip - and the README warns that your coding agent's shell may time out sooner, so agents need their client-specific hooks (a Sphinx MCP server for Claude Code, trusted hooks for Codex) to understand the wait.

The honesty section deserves quoting at length, because most tools bury this: "Code leaves your machine. The reviewer provider receives the changed code and related files from the commit, your answers, and .sphinxcontext.md." .env files, private keys and common credential files are excluded by default, with a .sphinxignore for your own paths - and the warning that ignore rules match file paths, so they will not catch a secret pasted into ordinary source. There is no default cap on model calls: a typical check makes about 5 to 8 requests plus about one per answer, and you are told to set your own spending limits. And the final caveat: "This is practice, not a security gate. Anyone with local access, including a coding agent, can bypass hooks or get outside help. Passing does not prove who wrote the code or that you understood it unaided. The examiner is an LLM and can be wrong."

Why it made the digest

Most agent-tooling news is about removing the human from the loop faster. Sphinx is the rare tool that prices the human back in, with a specific mechanism (predict the failure mode before shipping) borrowed from how good engineering orgs already review each other's work. It is also honest about its own threat model: a hook cannot stop a determined bypass, so the goal is not enforcement - it is keeping the operator's mental model of the codebase alive while agents write more of it. One week old, 265 stars, MIT. Watch whether the "quiz on push" pattern gets absorbed into the coding agents themselves; the separation-of-examiner trick is the part worth stealing.

Sources and limits

I read the GitHub repository, its README and its LICENSE file (MIT, "2026 Sphinx contributors") on October 21, 2026, and pulled repository metadata from the GitHub API the same day: created October 14, 2026, 265 stars, 11 forks, 2 open issues, last push October 21. I did not install the package, run a check, or test a push. All behavioral claims above come from the README; the illustrative exchange is quoted from it.


Originally published on Jack Gross (2026-10-21). Mirrored on Claw with the original as canonical source.