grip

Pass the whiteboard defense before you push.

grip is a git hook that asks you five questions about your own diff before it leaves your machine: what it does, why it is built this way, where it fails, what could go wrong, how you know it works. A model writes the questions and a hidden rubric from the diff, then grades your answers. Score below your team's pass mark and the push is blocked.

It checks the developer, not the code: you can ship code a model wrote, as long as you can explain and defend it.

Features

• Five questions from your diff, graded against a hidden rubric into a Grip Score out of 100. Never line numbers or trivia.
• grip whiteboard: your change drawn as parts and arrows in the browser, with the questions pinned to it, including what a malicious actor could do.
• Works with what you have: reuse Claude Code, Codex or Gemini CLI as the model (no API key), or use Anthropic, any OpenAI-compatible API, or Ollama locally.
• Inside coding agents: /grip in Claude Code, Codex, Gemini CLI, Cursor and others, and a gate that keeps the agent from pushing until you pass.
• Out of the way when it should be: a passed diff is remembered, grip skip lets one push through, CI and non-interactive runs are skipped.

Installation

pipx install grip-hook        # or: uv tool install grip-hook

Python 3.11 or newer, on Linux, macOS or Windows. This installs the grip command and a git grip alias.

Quick start

cd your-repo
grip init        # writes .grip.toml, installs the pre-push hook
git push         # grip asks five questions first

grip init picks Claude Code, Codex or Gemini CLI as the model when one is installed. Otherwise set ANTHROPIC_API_KEY, or see Providers.

Other commands you will use:

grip quiz                  # quiz your staged changes now, no hook needed
grip whiteboard            # defend the change in the browser
grip quiz --provider fake  # try it offline with a scripted grader
grip skip                  # let the next push through
grip status                # hooks, last score, configuration

The walkthrough follows one real change from git commit to an accepted push.

Configuration

.grip.toml at the root of the repository, committed so the team shares one bar:

passing_score = 70        # 0-100
difficulty = "normal"     # easy | normal | hard
provider = "claude-code"  # auto | anthropic | claude-code | codex | gemini | openai | ollama

Every option, environment variables and the pre-commit framework hook are in the configuration reference.

Documentation

guilyx.github.io/grip: getting started, a walkthrough, coding agents, the whiteboard, how grip works inside, and the honest numbers on what the score does and does not measure.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development setup and SECURITY.md for reporting vulnerabilities and what data grip sends. This project follows a code of conduct.

Citation

If grip is part of a study or a course, please cite it; GitHub's "Cite this repository" button reads CITATION.cff.

License

BSD-3-Clause. Copyright (c) 2026, Erwin L.