parthh01/sphinx

What it solves

Agent-assisted development can produce code that the human operator doesn't fully understand. Sphinx adds an understanding check to the push workflow: when you push to a protected branch, Git pauses and asks you to predict what your change will do. If you miss something, it explains and gives a new scenario. Once you pass, the push continues. It works whether you or a coding agent ran the push, and it applies to every repository on your machine after installation.

How it works

Sphinx installs global Git hooks (core.hooksPath) that trigger on pushes to branches you configure (default: main and master). A separate reviewer model reads the committed change through read-only Git tools — it never sees the conversation that produced the code. It generates questions about behavior, failure modes, and invariants, not file or function names. You answer in a local browser page (or terminal) with a prediction and brief reasoning. Wrong answers get an explanation and a new scenario; disputes are handled specially. The check is open-book: you can read the code while answering. A pass lasts 24 hours and the same push won't re-ask. Reviews run on your Claude Code or Codex plan, OpenRouter, or any OpenAI-compatible endpoint. Sphinx itself has no hosted service.

Who it’s for

Developers who use coding agents (Claude Code, Codex, Cursor, OpenCode, Pi, or plain git push) and want to ensure they understand the changes being committed to protected branches. It requires Node.js 22.19+, Git, and macOS/Linux/WSL (Windows not yet supported). It also assumes you have a reviewer model account (e.g., signed-in Codex or Claude Code CLI, OpenRouter key, or OpenAI-compatible endpoint). It is meant as a personal practice tool, not a security gate.

Highlights

• Blocks Git until you pass, pause, or skip — a matching push waits up to 25 minutes, and you can resume later.
• Open-book questions cover behavior and failure modes — not file names, with a browsable diff and the reviewer's evidence shown beside each question.
• Works across many agents and providers — Claude Code, Codex, Cursor, OpenCode, Pi, plain git, and any OpenAI-compatible endpoint.
• Per-repository and global policy files — .sphinxconfig, .sphinxignore, and .sphinxcontext.md let you control branches, question depth, and what code the reviewer can see.
• Transparent and controllable — sphinx doctor checks setup, sphinx status shows recent skips, and you can cap model calls or switch models with presets.