Sphinx: explaining the changed code before it can be pushed

The problem

Code written by a coding agentcoding agentAn AI program that reads and edits code and runs commands for a developer. Claude Code and Codex are examples. can be pushed without the developer reading it. Parth Bhagat made Sphinx and posted it on Hacker News as a Show HNShow HNA post on Hacker News, a developer community, in which someone presents what they made. Its title starts with "Show HN:". on October 18, 2026. He summed up the product in one sentence: you can outsource your thinking, but not your understanding.

Developers commonly use GitHub’s branch protection rules to require approval before merging a change into a branch. Collaborators must open a pull requestpull requestA request to merge the changes on one branch into another. Other developers review and approve it. when a repository administrator sets "Require pull request reviews before merging" on a protected branch. GitHub documents this on the About protected branches page on docs.github.com. The change can be merged into that branch only after the required number of reviewers with write permission approve it. This rule checks another user’s approval. It checks neither whether the author understood the change nor whether the reviewer read the code.

How it solves it

Sphinx uses a Git hookhookA script registered to run automatically at a set moment. Git, for example, runs hooks right before a commit or a push. to ask the author what the changed code does. sphinx install changes core.hooksPath in the user’s global Git settings, so that Sphinx’s pre-push hook runs in every repository. At push time, the repository’s existing hooks run before Sphinx. Right after install, pushes to the main and master branches are checked in every repository. sphinx init changes that default by writing each repository’s branch and event settings to .sphinxconfig.

A push to a checked branch stops. The terminal prints the address of a local page. The conversation between the author and the coding agent is not sent to the reviewer. The reviewer investigates the committed change through read-only Git tools (file list, diff, search) and then writes the question. To answer it, the author has to predict how the changed code behaves under given conditions. The reviewer model checks the question once more before it appears on the page. When the author sends an answer, the reviewer grades it as correct, incorrect or ambiguous. If the answer is wrong, it gives an explanation and a new scenario. On a right answer, the blocked push continues.

The user chooses the reviewer model through a signed-in Claude Code or Codex CLI plan, OpenRouterOpenRouterA service that offers many companies' AI models through one API and one account., or an OpenAI-compatible endpointOpenAI-compatible endpointA server address that accepts requests in the same format as the OpenAI API. Other companies' models and self-hosted models can be connected through it in the same way.. By default, Sphinx does not send .env files, private keys or common credential files to the reviewer. The user can list more paths to exclude in .sphinxignore. Sphinx sends the project description in .sphinxcontext.md to the reviewer every time.

What is different

First, GitHub’s branch protection rules check the number of other users’ approvals. Sphinx makes the author predict what the changed code does, so the gate also works for a solo developer. On GitHub the approval comes from a human reviewer, while Sphinx’s verdict comes from an LLMLLMA large language model. It is an AI model trained on large amounts of text to understand and generate text.. The README says the reviewer model can be wrong. I used a stubstubA fake version of a real component that returns only fixed responses. It is used in tests. instead of the reviewer model today, so I did not test the quality of a real model’s questions.

Second, GitHub’s rule is enforced by the server at merge time. Sphinx runs on the author’s computer at push time. One installation covers every repository. A local hook can be skipped with --no-verify. The README says Sphinx is a practice tool, not a security gate. A gate on the server needs GitHub’s rules.

Third, with GitHub’s reviews the code is already on GitHub. Sphinx sends the reviewer model the committed change and related files, the project description and the author’s answers. The requests recorded by the stub endpoint today did not contain the contents of .env or the private key file key.pem. A fake token pasted into a source file was included as is.

What it makes easier

• A solo developer who has an agent write code and pushes straight to main. The author has to explain what the changed code does in their own words before the push, so unread code is less likely to be pushed. Today the push stayed blocked until the answer passed, and then the same push continued.
• A team that wants the author’s understanding checked before a colleague reviews. The reviewer model reads the committed change and writes the question. Today’s requests contained the commit diff, the project description and the author’s answers.
• A user running an external model on a repository with secret files. Sphinx does not send .env files or private key files to the reviewer. Today Sphinx sent the reviewer 2 requests to produce the question and 2 to grade the answer. None of these 4 requests contained the values of .env or key.pem.

How it was built

• 78 commits over five days from 2026-10-14, by Parth Bhagat alone. 54 of them end with a Co-authored-by line crediting Claude Opus 5.5.
• The repository’s .itervox directory contains agent instructions for roles such as implementer, reviewer and merge bot. It also contains handoff notes dated 2026-10-17 and screen captures.
• 9,736 lines of JavaScript (33 modules in src) and 56 test files. It depends directly on only two external packages, both from the Pi SDKPi SDKA library for running the Pi coding agent inside another program. It handles the agent session and the loop of tool calls.. The reviewer session runs on that SDK.

Running it

1. Install and tests. npm install fetched 118 packages in 5 seconds. All 697 tests passed in 42 seconds. sphinx install finished in 0.14 seconds. core.hooksPath in the global Git settings changed.
2. Stub reviewer. I pointed the OpenAI-compatible endpoint at a local HTTP server instead of a reviewer model. It records every request and returns one fixed question and a "correct" verdict. It does not call the investigation tools.
3. Repository setup. In a new repository, sphinx init created .sphinxconfig, .sphinxignore and .sphinxcontext.md. The commit included a .env with fake secrets, a fake private key key.pem, and src/signup.js with a fake token string. I had also created a pre-push hook in the repository. When it runs, it creates a check file.
4. Push. git push origin main printed "understanding check needed" and the local page address, then stopped. The existing hook’s check file appeared first. The page showed 5 changed files and "2 changed files excluded by privacy or ignore rules".
5. The data the reviewer received. Sphinx sent the reviewer 2 requests to produce the question and 2 to grade the answer. Requests sent in the failed attempts of step 6 are not counted here. Sphinx rejected the stub’s first grading reply because of a format error and sent one more request. The request bodies came to 60.8 KB in all. None of these 4 requests contained the values from .env or key.pem. The fake token in src/signup.js and the sentence from .sphinxcontext.md were included as is.
6. Failure path. When the stub returned three malformed responses, the page showed "Review did not finish". Git kept waiting. When I pressed the pause button, the push printed "progress is saved" and stopped. When I pushed again, Sphinx sent no new request to the reviewer and reused the saved question.
7. Pass. When I sent the answer, Sphinx made a grading request and then showed "Passed". The blocked push printed "Continuing this Git operation" and pushed 3 commits to the remote repository.

$ git push origin main
Sphinx: understanding check needed for refs/heads/main (medium change).
Sphinx: Git is waiting for your answers in the local Sphinx questionnaire. It will continue automatically after you pass.
Sphinx questionnaire: http://127.0.0.1:32875/9VaP6pNPvCosJSRYGcGF6S3IwCeSVZv-qkz0aA2eKKo
Sphinx: open the local URL above to answer. No application was brought to the foreground.
Sphinx: understanding check complete. Continuing this Git operation.
To /tmp/run/remote.git
 * [new branch]      main -> main

Not checked

• The quality and call count of a real reviewer model. Next time, I will use OpenRouter’s free models (the openrouter-free preset) as the reviewer and push the same commit again.
• The coding-agent integrations. Sphinx installs an MCPMCPModel Context Protocol: a standard for how AI models connect to outside tools and data. server and hooks for Claude Code and Codex. They can be checked with sphinx install --agents codex,claude on a computer where both CLIs are installed.

Verdict

It works. The push stayed blocked until the answer passed, and then the same push continued. That said, I used a stub instead of the reviewer model, so I did not test the quality of a real model’s questions. It is worth a try if you push agent-written code to main alone and want at least to check that you can explain it in your own words. You also need to accept the cost of a reviewer model. Sphinx is not a replacement for a team’s code review or a security gate.

What to take away

• Check whether the author can explain agent-written code, regardless of who approved it. Sphinx stopped the push and made the author predict what the changed code does.
• Check the request log to see what goes to an external model. Today the stub endpoint’s log showed that Sphinx excluded .env but sent the token in the source file unchanged.
• When the reviewer fails, keep the push stopped by default. When the reviewer returned three malformed responses, Sphinx did not let the push through. It handed the decision to the user.