Sphinx

// Overview

Sphinx is an open-source comprehension checkpoint for agent-assisted development. When you push to a protected branch, git waits while Sphinx asks you to predict what the change will do; if you miss something it explains and gives you a new scenario on the same concept, and once you pass the push continues. It works the same whether you or a coding agent ran git push. The project's line is "outsource your thinking, not your understanding".

The questions come from a separate reviewer model that reads the committed change through read-only git tools and never sees the conversation that produced the code. They target behaviour, failure modes and invariants rather than file or function names, are open-book, and scale with change size: one for a small change and up to three at the default depth. The questionnaire opens in the browser with the changed files, line counts, a browsable diff and the code locations the reviewer read.

Sphinx has no account or hosted service of its own. The reviewer can be a signed-in Codex or Claude Code CLI, an OpenRouter key or any OpenAI-compatible endpoint; it receives the changed code, related files, your answers and an optional project description, while ignored paths, .env files and private keys are never read. The coding agent sees only check status, progress and usage, never your answers. The README is explicit that this is practice, not a security gate: version 0.1 checks local pushes only, anyone with local access can bypass hooks, and the examiner is an LLM that can be wrong.

// What it does

• Pre-push checkpoint on the branches you protect, for pushes run by you or by a coding agent
• Questions about behaviour, failure modes and invariants from a separate reviewer model that only reads the committed change
• Wrong answers get an explanation and a fresh scenario; Explain this, Dispute question, Pause check and Skip this time controls in the questionnaire
• Passes last 24 hours unless the code, destination or policy changes; questions are often prepared in the background after commits
• Integrations for Codex, Claude Code (via MCP), Cursor, OpenCode and Pi, plus plain git
• Repository policy in .sphinxconfig, .sphinxignore and .sphinxcontext.md, with .env files and private keys excluded by default and every sphinx yolo skip logged

// Getting started

Sphinx needs Node.js 22.19 or newer, git, and macOS, Linux or WSL (native Windows is not supported yet), plus a reviewer model: a signed-in Codex or Claude Code CLI, an OpenRouter key or an OpenAI-compatible endpoint. The commands come from the project README.

npm install -g sphinx-understand
sphinx install

# or non-interactive
sphinx install --yes --preset claude-economy --agents claude

cd your-repo
sphinx init --yes --branches main

sphinx doctor
git push origin main

sphinx check --staged
sphinx config --max-model-calls 30
sphinx yolo --reason "prod hotfix"

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Reach for it when coding agents write most of your changes and you want to be sure you understand each one before it reaches main
• Reach for it when you want a reviewer that tests your grasp of failure modes, such as retries and lost responses, rather than one that only comments on the diff
• Reach for it when you want a lightweight, local practice gate with no hosted service, using the Claude Code or Codex subscription you already have

// How Sphinx compares

Sphinx alongside other open-source ai code review & security tools AI/TLDR tracks, ranked by GitHub stars.