Yes. Sphinx is free and open source (FOSS), installed globally via npm: `npm install -g sphinx-understand`.

What are the system requirements?

Node.js 22.19 or newer, running on macOS, Linux, or WSL. After installing, run `sphinx install` to connect Git and your coding agents, then push as usual.

Can I skip the check when I'm in a hurry?

Yes. `sphinx yolo` lets pushes through, and every skip is logged so there's an audit trail.

Sphinx — A Git hook that quizzes you before agent code ships

Sphinx is a free, open-source Git hook for agent-assisted development. When you (or your coding agent) push code, Sphinx pauses the push on protected branches, reads the diff, and asks you a question about what the change actually does — particularly how it behaves when things go wrong. If you answer incorrectly, it explains why and presents a new scenario; answer correctly and the push continues. The goal is to force genuine understanding of agent-generated code before it ships.

Key Features

Understanding check on push

Git pauses on protected branches while Sphinx asks a question generated from your diff about what the change does in failure scenarios.

Socratic follow-up questions

Wrong answers get an explanation of why they were wrong, then a follow-up scenario; the push only proceeds once you demonstrate understanding.

Works alongside coding agents

Compatible with Codex, Claude Code, Cursor, OpenCode, and Pi, or plain Git without any agent.

Flexible model backends

Runs on minimal tokens using your existing coding agent, OpenRouter, or any OpenAI-compatible endpoint; `sphinx install` connects Git and your agents and asks which model should review.

Privacy by design

Your answers never reach the coding agent, and .env files and keys are never opened by the reviewer.

Escape hatch with audit trail

`sphinx yolo` lets pushes through when you're in a hurry, and every skip is logged.

How It Works

1. You push

You push — or your agent does. Git pauses on the branches you protect.

2. Sphinx asks

A reviewer that never saw your chat reads the diff and asks what the change does when things go wrong.

3. You answer

Get it wrong and you learn why, then try a new scenario. Get it right and the push continues.

Pros & Cons

Pros

Free and fully open source (FOSS)
Integrates directly into the existing git push workflow — no separate review step
Works with popular coding agents (Codex, Claude Code, Cursor, OpenCode, Pi) as well as plain Git
Runs on minimal tokens and supports OpenRouter or any OpenAI-compatible endpoint
Strong privacy stance: answers never reach the coding agent, and .env files/keys are never opened
Skips are permitted (`sphinx yolo`) but logged, preserving an audit trail

Who It's For

Best for

Developers shipping AI-agent-generated code who want to be forced to understand it before it merges
Teams that protect key branches and want a lightweight, token-efficient comprehension gate in the git workflow
Engineers already using tools like Codex, Claude Code, Cursor, OpenCode, or Pi who want a model-agnostic review hook

Not ideal for

Teams wanting automated CI-only checks with no human interaction at push time
Developers on native Windows (WSL is required)
Organizations that cannot allow any LLM to read their diffs, or that need fully offline tooling

Use Cases

Verifying that developers (and their AI agents) actually understand code before it lands on protected branches

Teams adopting agent-assisted development who want a comprehension checkpoint on git push

Reviewing failure-mode behavior of changes such as webhook handlers, retries, and idempotency logic

Individual developers using Codex, Claude Code, Cursor, OpenCode, or Pi who want a lightweight guardrail

FAQ

What is Sphinx?

Sphinx is a Git hook for agent-assisted development. Before your agent's code ships, it pauses the push and asks you a question about what that code actually does, especially how it behaves when things go wrong.

How does the push-time check work?

When you push to a protected branch, Git pauses. Sphinx's reviewer — which never saw your chat with your coding agent — reads the diff and asks what the change does in a failure scenario. A wrong answer gets an explanation and a new scenario; a correct answer lets the push continue.

Which coding agents does it work with?

Sphinx works with Codex, Claude Code, Cursor, OpenCode, and Pi, or with plain Git if you're not using an agent.

Which AI models does it use?

Sphinx