TL;DR: Sphinx is a free, MIT-licensed git hook that pauses your push to a protected branch until you correctly answer scenario questions about the diff — questions written by a separate LLM that never saw your agent conversation. It checks whether you understand the code, not whether the code is correct. Teams merging agent-written code daily should trial it; solo devs will probably sphinx yolo it within a week.

	Sphinx (comprehension hook)	AI review bot (Bugbot-class)	Reading the diff yourself
Best for	Teams where “LGTM without reading” is the norm	Catching bugs the author missed	Small diffs, senior reviewers
What it checks	The human’s understanding	The code itself	Both, if you’re honest
Price / cost	$0 + ~$0.004 per check on Claude Haiku rates, or $0 on a local model	Typically bundled or $15–$40/mo per seat	Your time
The catch	Passing a quiz ≠ correct code; anyone local can bypass it	Approves code nobody on the team understands	Nobody enforces it

Honest take: Sphinx is the first tool that targets the actual failure mode of agentic coding — shipping code no human can explain — instead of piling on another reviewer bot. Install it on team repos where agent-written PRs merge daily. Skip it solo: with no one watching the skip log, the friction loses to the deadline.

AI code review tools keep multiplying — we’ve covered when to trust an AI reviewer’s suggestion and Anthropic’s Claude Security Plugin — but every one of them reviews the code. Sphinx, which hit the Hacker News front page as a Show HN on October 18, 2026, reviews you. As of October 29, 2026 the project sits at 461 GitHub stars, ships as sphinx-understand v0.1.19 on npm, and is two weeks old. That version number matters: this is a 0.1 product with real gaps, and this review names them.

What does Sphinx actually do?

Sphinx installs a machine-wide git hook that intercepts pushes to protected branches and blocks them until you pass a short comprehension check about the committed diff. A reviewer LLM — separate from whatever agent wrote the code — reads the change through read-only git tools, then asks scenario questions about behavior, failure modes, and invariants: “what happens when this payment call fails?”, not “what is this function named?”. Answer correctly and the same push continues. Answer wrong and you get an explanation plus a new scenario.

Three design choices define it, all verified against the project README on October 29, 2026:

1. The examiner never sees your agent conversation. It reads only the committed change, so it can’t be steered by the chat session that produced the code.
2. The check is open-book. You can read the diff while answering. The point is forcing the read, not memory testing.
3. Question count scales with the diff. Small changes get up to one question, large ones up to three at the default depth. Questions are prepared in the background after each commit, so they’re usually ready by push time.

It works whether you type git push or your coding agent runs it — which is the point. Claude Code, Codex, Cursor, OpenCode, and Pi all get native integrations; plain git works with no agent at all.

How much does a Sphinx check cost?

About $0.004 per check on Claude Haiku 5.5 API rates, or $0 if the reviewer runs on your subscription plan or a local model. Sphinx has no hosted service and no account — the only cost is the reviewer LLM’s inference, and you pick where that runs:

Reviewer route	Setup	Billing	Catch
Signed-in Claude Code or Codex CLI	--preset claude-economy or codex-economy	Your existing plan’s allowance	Strips API keys from the CLI environment by default (override: --cli-billing api)
OpenRouter	--preset openrouter-value --allow-paid	Paid credits	API key required even for the openrouter-free route
Any OpenAI-compatible endpoint	sphinx auth --provider openai --base-url <url>	Per-token, or free locally	Endpoint must support tool calls AND JSON-schema structured output

The docs (cost figures checked by the project on October 15, 2026, re-verified October 29) plan for roughly 5 / 7 / 8 requests per small / medium / large check, plus about one request per answer. At Haiku 5.5’s $0.10 input / $0.50 output per million tokens, the project estimates a typical check — about 30,000 input and 2,000 output tokens — at $0.004. Even at 20 pushes a day that’s under $2.50/month.

Two cost caveats the docs are upfront about. First, maxModelCalls defaults to null — no cap. Set one before pointing Sphinx at a paid key:

$ sphinx config --max-model-calls 30

Second, the claude-economy preset routes through your Claude Code plan, so heavy pushing eats the same usage allowance your agent sessions use.

The local route deserves more attention than the docs give it. Ollama, LM Studio, and vLLM all qualify as OpenAI-compatible endpoints, and plain http:// is allowed for localhost with no key. But the endpoint must handle tool calling and structured output — the same constraint that trips people up in Cline and Continue.dev local setups, so pick a model tagged for tools. A quiz-writing reviewer is a light workload; any machine from our sister site’s GPU buying guide for local AI that runs a 7B–14B instruct model comfortably will do, and your diffs never leave the machine — relevant if the whole reason you’re nervous about agent code is cloud exposure.

How do you install Sphinx?

Three commands, verified against the README and docs/integrations.md on October 29, 2026. Requirements: Node.js 22.19+, git, and macOS, Linux, or WSL — native Windows is not supported yet.

$ npm install -g sphinx-understand
$ sphinx install --yes --preset claude-economy --agents claude
$ cd your-repo && sphinx init

sphinx install runs a guided setup (the flags above skip it), registers the git hook, and wires up whichever agents you name. sphinx init drops three files in the repo: .sphinxconfig (committed — which branches and events to guard, question depth), .sphinxignore (files the reviewer never reads; .env files and private keys are always excluded), and .sphinxcontext.md (project notes sent with every reviewer request). sphinx doctor verifies the wiring.

A .sphinxconfig guarding main and release branches at default depth:

{
  "version": 1,
  "events": ["pre-push"],
  "branches": ["main", "release/*"],
  "level": "standard",
  "distance": "mixed",
  "exclude": ["vendor/**"]
}

One install detail you should know before running it: Sphinx sets your global git core.hooksPath, so it applies to every repository on the machine. Existing repo hooks still run first and their rejections are preserved, but if a repo already sets its own core.hooksPath, Sphinx is silently absent there until you run sphinx install --repo inside it — sphinx doctor flags this case.

Per-agent wiring, from docs/integrations.md:

Agent	What’s installed	Gotcha
Claude Code	MCP server + lifecycle hooks	Start a new session; confirm sphinx shows connected under /mcp
Codex	MCP server + lifecycle hooks	Open /hooks and trust them; in Codex 0.162.1, approval policy never cancels the native quiz form — recover with sphinx check
Cursor 1.7+	Local user hooks	Covers local sessions only, not Cursor cloud agents
OpenCode 1.x	Plugin in OpenCode’s config dir	Start a new session
Pi 1.2+	Native extension	Needs an interactive session; otherwise check stays pending

Install a new agent later and Sphinx won’t notice — rerun sphinx install.

Can you bypass it? (Yes — and that’s the design)

sphinx yolo disables checks for the current repo (or globally), an optional --reason "prod hotfix" attaches context, and running it again re-enables them. The questionnaire also offers “Skip this time,” which lets the push through immediately. Here’s the part that makes Sphinx viable for teams: every skip and yolo toggle is logged with its reason, skips never count as passing, and sphinx status lists recent ones. With the GitHub CLI signed in, a pass can stamp the pushed commit and post a PR summary comment; sphinx init --github-check adds a non-blocking Sphinx check to PRs.

So the enforcement model is social, not technical. The README says this plainly: anyone with local access, including a coding agent, can bypass hooks or get outside help. Sphinx is practice with an audit trail, not a security gate. If you need a gate, that’s a branch-protection and CI problem — Sphinx explicitly does not cover web merges, CI-required checks, or deployments in v0.1.

Where Sphinx breaks today

Running a 0.1.x product means hitting edges. These are the documented and observed failure modes, each with its fix:

The 25-minute wait vs. your agent’s shell timeout. A blocked push serves the questionnaire on 127.0.0.1 and waits up to 25 minutes, but the browser auto-opens only on macOS, and an agent’s shell wrapper may kill the hanging git push first. Sphinx saves progress: finish the check (reopen the printed URL or run sphinx check in a terminal), then rerun the push once. Don’t launch a second copy of a push that’s still waiting. Over SSH, answer in the terminal with sphinx check or forward the loopback port.

Codex cancels the quiz form. In Codex 0.162.1 with approval policy never, the native form gets cancelled unless the host enables full-access form input. Sphinx won’t change your approval policy for you; sphinx check in a plain terminal completes the stranded check.

The grader marks right answers wrong. The project’s own eval/RESULTS.md is unusually honest here — it’s labeled development measurement on five synthetic repos, “not an all-green semantic evaluation.” In the strongest run, Claude Haiku 5.5 matched 33 of 39 verdict probes, and two documented false negatives graded sufficient answers as ambiguous because they lacked specific literal wording. A GLM 5.3 Flash run produced no completion after about 180 seconds on one case. Practical translation: on the claude-economy preset expect the occasional unfair “wrong,” read the explanation, and re-answer with more literal phrasing. The examiner is an LLM; the README says it can be wrong.

Passing proves understanding, not correctness. The sharpest criticism in the Show HN thread: a leftover debug print, an assertion weakened until it matches the bug it was meant to catch, or an import of a package that doesn’t exist can all survive a comprehension quiz. True, and the README agrees — Sphinx “tests understanding; it does not audit the code.” It’s a complement to a reviewer bot, not a replacement. In a two-tool stack, the bot checks the code and Sphinx checks the human; neither covers the other’s blind spot.

Is Sphinx trustworthy enough to pipe your diffs through?

Reasonable question for a two-week-old tool that reads your code and calls an LLM. The checkable facts, as of October 29, 2026: MIT license, all source on GitHub, no telemetry service of its own — code from the commit, your answers, and .sphinxcontext.md go only to the reviewer provider you configured, and a localhost endpoint keeps everything on-device. The npm package is published via GitHub Actions trusted publishing with SLSA provenance attestation rather than from a personal laptop — better supply-chain hygiene than most week-old npm CLIs, worth noting in a month when we audited what Codex CLI’s daemon ships by default. The caveats: 461 stars means a small review surface so far, the package carries a postinstall hook (standard, but skim it if your org cares), and .sphinxignore matches file paths — it will not catch a secret pasted into ordinary source code.

Who should actually install this?

Install it: teams where multiple devs merge agent-written code daily and PR review has quietly become theater. The per-check cost is a rounding error, the skip log creates accountability without hard blocking, and the GitHub check surfaces who’s passing versus yolo-ing. Start with level: relaxed on one repo and tighten from there.

Skip it: solo developers with nobody reading the skip log — be honest about how long the quiz survives your first urgent Friday push. Windows-native teams (WSL only for now). Anyone who wants a correctness gate — that’s a review bot plus CI, and if you want the fully open-source version of that pipeline, the FOSS coding-tool comparisons at aifoss.dev cover the self-hosted end.

The deeper bet Sphinx makes is that comprehension debt — code in production that no human can explain — is the real long-term risk of agentic coding, and that the cheapest fix is a forcing function at push time. Two weeks in, with a 33/39 grader and a yolo command, it’s an earnest 0.1 of that idea rather than the finished product. It’s also the only tool in this space checking the side of the human-agent pair that every other vendor ignores.

FAQ

Does Sphinx work without an AI coding agent? Yes. The git hook is the checkpoint; plain git push triggers it with no agent installed. The agent integrations only make the quiz render natively inside Claude Code, Codex, Cursor, OpenCode, or Pi.

Can my coding agent answer the quiz for me? Technically yes — the README admits anyone with local access can bypass or outsource the check. Skips and yolos are logged, but a pass doesn’t prove the answer was unaided. Sphinx keeps honest people honest.

Does it send my code to a server? Only to the reviewer provider you choose. Point it at Ollama or LM Studio on localhost and nothing leaves your machine. There is no Sphinx-hosted service or account.

What does it cost per month? On the claude-economy preset, nothing beyond your existing Claude plan allowance. On API billing, the project’s estimate is ~$0.004 per check at Haiku 5.5 rates (verified October 2026) — single-digit dollars per month even for heavy pushers. Set --max-model-calls first; there’s no default cap.

Does it run in CI? No. CI never starts a questionnaire — the check stays pending and git stops. v0.1 covers local commits and pushes only, not web merges or CI-required checks.

Sources

• parthh01/sphinx — GitHub repository and README
• Sphinx configuration and cost documentation
• Sphinx integrations documentation (Claude Code, Codex, Cursor, OpenCode, Pi)
• Sphinx evaluation results — eval/RESULTS.md
• sphinx-understand on the npm registry (v0.1.19)
• Show HN: Sphinx — Hacker News discussion, October 18, 2026

Last verified October 29, 2026. Sphinx is pre-1.0 software; commands, presets, and limits change quickly — check the repository before relying on specifics.

Know which coding tool is worth paying for

Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.

Email address Subscribe