grip

Keep a grip on your code. grip is a git hook that quizzes you about your own diff before you commit or push it. Five questions, a Grip Score out of 100, and a pass mark you choose. Below the mark, nothing goes upstream.

_{A commit blocked at 12/100, then accepted at 92/100. Video version. Recorded with the offline scripted provider, so questions are canned; a real model writes them from your diff.}

Why

Generated code, big refactors, late-night pastes: it is easy to ship a change you could not explain in a code review. grip makes you explain it before it leaves your machine. It is a lightweight forcing function, not a gate for correctness: the model asks about behaviour, motivation, edge cases, risks and verification, and grades your answers against a rubric it wrote from the diff.

Install

One command, no Python or package manager needed. It downloads the prebuilt binary for your OS and CPU from the latest release, verifies its checksum, and puts grip (and a git grip alias) in ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/guilyx/grip/main/install.sh | sh

Pin a version with sh -s -- --version v0.1.0, change the directory with --dir, remove it with --uninstall. Linux and macOS, x86_64 and arm64. On Windows use the pre-commit framework route below.

Then pick one of two ways to wire it into git.

Option A: native git hook

cd your-repo
grip install                  # pre-push (recommended)
grip install --stage pre-commit --stage pre-push   # both

Option B: pre-commit framework

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/guilyx/grip
    rev: v0.1.0
    hooks:
      - id: grip          # runs at pre-push
      # - id: grip-commit # runs at pre-commit

pre-commit install --hook-type pre-push

Inside Claude Code

/plugin marketplace add guilyx/grip
/plugin install grip@grip

/grip:quiz has Claude relay the five questions to you and grade your answers, and a hook blocks git push until the diff has passed. Codex and Gemini CLI can drive the same flow through grip ask / grip grade; see the docs.

Provider

Already using Claude Code, Codex or Gemini CLI? grip can reuse it, so there is no API key and no extra bill:

# .grip.toml
provider = "claude-code"      # or "codex", or "gemini"

Otherwise grip talks to Anthropic by default: export ANTHROPIC_API_KEY (or run ant auth login). For a local, free setup use Ollama:

# .grip.toml
provider = "ollama"
model = "qwen3:14b"

Any OpenAI-compatible API works with provider = "openai" plus base_url and OPENAI_API_KEY.

Use

Nothing to do: commit or push as usual. When grip runs, answer five questions in the terminal. Pass the mark and the commit or push continues; fail it and it is blocked with per-question feedback so you know what to go read.

grip quiz                     # quiz your staged changes right now, no hook needed
grip quiz --unpushed          # quiz everything not yet on a remote
grip quiz --provider fake     # try the flow offline with a dummy grader
grip status                   # installed hooks and effective configuration
GRIP_SKIP=1 git push          # bypass once (git's --no-verify also works)

A diff that passed is remembered for 24 hours, so a pre-push right after a pre-commit does not ask again.

Configure

.grip.toml at the repository root, or [tool.grip] in pyproject.toml. Environment variables (GRIP_PASSING_SCORE=80) and flags (--passing-score 80) override files.

passing_score = 70            # 0-100, the Grip Score you need
difficulty = "normal"         # easy | normal | hard
provider = "anthropic"        # anthropic | claude-code | codex | gemini | openai | ollama | fake
model = ""                    # empty = provider default (claude-opus-5 for anthropic)
effort = "medium"             # low | medium | high | xhigh | max | none
exclude = ["*.lock", "*.snap"]
max_diff_bytes = 200000
remember_passes_hours = 24
require_tty = false           # fail instead of skipping in non-interactive runs
fail_open = false             # let commits through when the provider is down

Full reference: guilyx.github.io/grip.

How the score works

• The model reads the diff and writes exactly five questions, each with a hidden rubric.
• You answer each in a sentence or two.
• The model grades all five against the rubrics: 0 to 20 points each, summed to a Grip Score out of 100.
• Score at or above passing_score lets the commit or push through.

Only the diff (after exclude) and your answers are sent to the provider. Reports are saved to .git/grip/last-report.json.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development setup, and SECURITY.md for what data grip touches.

Media

A launch video, the Product Hunt image and the icon live under docs/assets/launch/, all generated from the demo recording by scripts/launch/make_launch.py. Use them freely. More on the media page.

License

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