grip-hook 0.2.1__tar.gz

grip_hook-0.2.1/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+/build/
+.venv/
+venv/
+.eggs/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+site/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

grip_hook-0.2.1/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-19
+
+grip is on PyPI.
+
+### Changed
+
+- grip is published to PyPI as `grip-hook`: `pipx install grip-hook` or
+  `uv tool install grip-hook`. Releases publish there through trusted publishing, and
+  the GitHub release carries the same sdist and wheel.
+- The prebuilt binaries are gone. They bundled the build machine's Python, so the 0.1.0
+  and 0.2.0 Linux binaries needed glibc 2.38 and failed on Ubuntu 22.04 and older with
+  `GLIBC_2.38 not found`. `install.sh` now installs the package with uv or pipx, and
+  replaces a binary left by an earlier install.
+- Windows is supported through the same install.
+
+### Fixed
+
+- Whiteboard layout: a reply arrow (`allow -> handler` after `handler -> allow`) no longer
+  pushes the board into extra columns, a part that only feeds others (tests, a fixture)
+  sits just before what it feeds instead of across the input's arrow, and each column is
+  ordered by what feeds it so fewer arrows cross.
+- Whiteboard page: long labels and roles end in an ellipsis inside their box (the full
+  text is in the tooltip and the side panel), long arrow labels wrap onto two lines and
+  slide along their arrow when they would cover another label, a box or a pin, and a pin
+  on an arrow sits on the arrow.
+- Whiteboard page: two questions pinned to the same box or arrow were drawn on the same
+  spot, so one was hidden and could not be clicked. They now line up side by side.
+- `--unpushed` described its range as `sha..sha` with the same commit twice; the base is
+  now resolved to the parent's hash.
+
+## [0.2.0] - 2026-10-15
+
+The whiteboard release.
+
+### Added
+
+- `grip whiteboard`: the change drawn as a whiteboard (its parts, how they connect, which
+  inputs are untrusted) with five questions pinned to it, defended in the browser. It asks
+  the two whiteboard questions the quiz does not: what a malicious actor could do and why
+  a data structure was chosen. Graded on the same 100-point scale; a pass counts for the
+  push hook. `--interview` shows the rubrics to the person asking and records nothing,
+  `--export` writes a shareable page without rubrics. Served on 127.0.0.1 behind a random
+  token, with `Host`/`Origin` checks and a hash-based Content-Security-Policy.
+- `/grip-whiteboard` skill for Claude Code, Codex, Gemini CLI, Cursor and friends.
+- Providers draw boards (`generate_board`); the `fake` provider draws one from the changed
+  files or from a scripted `board`.
+
+### Changed
+
+- grip is now explained around the whiteboard defense: could you explain and defend this
+  change at a whiteboard? The README, the docs homepage and a new
+  [whiteboard defense](https://guilyx.github.io/grip/whiteboard-defense/) page map grip's
+  five questions to that bar, and say when to leave grip off (prototypes, demos,
+  experiments).
+
+## [0.1.0] - 2026-10-15
+
+The first public release.
+
+### Added
+
+- `grip quiz`: five questions about your staged, unpushed or ranged diff, graded to a Grip
+  Score out of 100 with a configurable pass mark.
+- `grip hook pre-commit` / `grip hook pre-push`: hook entry points, both for native git
+  hooks and for the pre-commit framework (`.pre-commit-hooks.yaml`).
+- `grip install` / `grip uninstall` / `grip status` / `grip config` / `grip forget`.
+- Providers: Anthropic (default, `claude-opus-5`), any OpenAI-compatible API including
+  Ollama, and an offline `fake` provider for tests and demos.
+- Configuration through `.grip.toml`, `[tool.grip]` in `pyproject.toml`, `GRIP_*`
+  environment variables and command-line flags.
+- Passed diffs are remembered for a configurable time so you are not quizzed twice.
+- Documentation site built with MkDocs Material and published to GitHub Pages.
+- A brand identity under `branding/`: the grip mark (an 87.5 percent score ring that
+  reads as a G) in ember orange on warm graphite, Archivo wordmark lockups, a social card,
+  and a palette generated in OKLCH by `branding/build.py`, which refuses to write colours that fail WCAG 2 or APCA contrast or
+  that collapse under simulated colour-blindness. `tests/test_branding.py` keeps the
+  generated files current.
+- A redesigned docs site: the generated palette and brand type, tabs for each section, a
+  homepage with an install switcher and feature cards, dark code blocks with checked
+  syntax colours, an announcement bar, social preview tags, and a Brand page.
+- Feature clips under `docs/assets/features/`: one MP4 and GIF per new feature and a
+  stitched "what's new" cut, recorded by `scripts/demo/make_features.py` against the real
+  CLI with a scripted offline scenario.
+- Every recording in the brand: the demo, the feature clips, the launch video and the
+  Product Hunt stills now use the ember and graphite palette, JetBrains Mono in the
+  terminal, Archivo and Instrument Sans on the title cards, and the mark. Colours come from
+  `branding/tokens.json` through `scripts/demo/brandkit.py`, so videos and docs cannot drift.
+- Two more skills: `grip-review` quizzes a reviewer on a range of commits (or prints the
+  questions for the author with `--questions-only`), `grip-explain` turns the developer's
+  answers from the last quiz into a commit message or pull request description. `grip last`
+  shows the last graded quiz, with `--json` for skills to build on.
+- An evals harness under `evals/`: eight fixture diffs with author notes, three answer
+  arms (blank, generic, notes), repeated grading for noise, a committed fake-provider
+  snapshot the tests keep current, and a Markdown summary. A "Honest numbers" docs page
+  says what is measured, what is not, and where grip gets in the way.
+- `CITATION.cff` and a Cite section in the README; `.github/FUNDING.yml`. The README opens
+  with a three-tile summary and a before/after comparison, and its Why section cites the
+  METR, GitClear, DORA and Stack Overflow findings on AI-assisted code.
+- `grip skip` skips the next hook run once, `grip skip --hours N` pauses hooks for a
+  while, `grip resume` cancels. Both the git hooks and the Claude Code push gate honour
+  it; a manual `grip quiz` does not. `grip status` gained an activity section: last quiz,
+  whether the staged and unpushed diffs have passed, and the skip state.
+  `grip statusline` prints `grip 92/100 pass` for editor and Claude Code status lines.
+- `grip init`: one command that writes a commented `.grip.toml` (defaulting to an
+  installed coding agent as provider), installs the pre-push hook and writes the agent
+  rule files. `--provider`, `--passing-score`, `--difficulty`, `--stage`, `--no-hook`,
+  `--no-agents`, `--force`. `config.render_template` produces the file.
+- `grip agents`: detects the coding agents installed on the machine (Claude Code, Codex,
+  Gemini CLI, Cursor, Windsurf, Cline, Copilot, OpenCode) and writes, inside the
+  repository, the rule file each one reads so it runs `grip check` before pushing.
+  Marked blocks in `AGENTS.md`, `CLAUDE.md` and `GEMINI.md`, grip-owned rules files for
+  Cursor, Windsurf and Cline, and the plugin enablement merged into
+  `.claude/settings.json`. `--list`, `--all`, `--agent`, `--dry-run` and `--remove`.
+- Keep A Grip, the problem platform: `grip login`, `grip logout`, `grip whoami`,
+  `grip problems`, `grip solve SLUG` and `grip submit`. Solve a problem with any assistant,
+  get quizzed on the diff, have the score reported with an API token. `Diff` gained a
+  `context` field that the prompts pass to the model as data, and `Git.worktree_diff` diffs
+  everything since a base commit, uncommitted work included.
+
+- Demo recording (`docs/assets/demo.gif`, `.webm`, `.cast`) and the script that
+  regenerates it, `scripts/demo/make_demo.py`.
+- Scripted mode for the `fake` provider through `GRIP_FAKE_SCRIPT`, plus `GRIP_FAKE_DELAY`
+  for artificial latency.
+- Providers that reuse a coding agent already installed and signed in, so no API key is
+  needed: `claude-code` (alias `claude`), `codex` and `gemini`. Each runs the CLI in
+  non-interactive mode with tools disabled, in an empty scratch directory.
+
+- Claude Code plugin, served from this repository as a marketplace
+  (`/plugin marketplace add guilyx/grip`): `/grip` relays the quiz through Claude and
+  a `PreToolUse` hook blocks `git push` until the diff has passed.
+- The quiz skill lives at `skills/grip/SKILL.md` in the Agent Skills layout, so
+  `npx skills add guilyx/grip` installs it into any agent that reads `SKILL.md` files.
+  The plugin is served from the repository root (`hooks/hooks.json`, `skills/`).
+- `grip ask`, `grip grade`, `grip check` and `grip agent-hook`: the quiz as
+  non-interactive JSON steps so any coding agent can drive it.
+- `grip study export` and `grip study status`: an anonymised JSON summary of every quiz
+  taken on the machine (scores and per-question focus only, never code, paths, questions,
+  answers or feedback) for study platforms. Graded quizzes are now appended to
+  `.git/grip/history.jsonl` and the repository is recorded in
+  `$XDG_DATA_HOME/grip/repos.json`. Nothing is uploaded by grip.
+
+- Launch assets under `docs/assets/launch/` (Product Hunt image, icon, 1080p launch video)
+  and `docs/assets/demo.mp4`, generated by `scripts/launch/make_launch.py`; a Media page
+  on the docs site.
+
+### Changed
+
+- `grip init` reports agent files as "wrote" or "updated" instead of "written", and the
+  generic `AGENTS.md` target is labelled "AGENTS.md readers".
+
+- The demo now quizzes a ROS 2 change: a `cmd_vel` safety filter gaining a lidar scan
+  watchdog, instead of a payment refund.
+- Distribution: `install.sh` (`curl -fsSL .../install.sh | sh`) downloads a prebuilt,
+  checksum-verified binary from GitHub Releases into `~/.local/bin`. The release workflow
+  builds binaries for Linux and macOS (x86_64 and arm64) with PyInstaller; nothing is
+  published to PyPI anymore.
+- `model` now defaults to empty, meaning the provider's own default (`claude-opus-5` for
+  Anthropic, the CLI's default for coding agents). `openai` and `ollama` require it.
+- The score table uses rounded borders, matching the panels.
+- The "blocked" message prints the report path relative to the working directory.
+
+[Unreleased]: https://github.com/guilyx/grip/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/guilyx/grip/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/guilyx/grip/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/guilyx/grip/releases/tag/v0.1.0

grip_hook-0.2.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Erwin L.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

grip_hook-0.2.1/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.5
+Name: grip-hook
+Version: 0.2.1
+Summary: Pass the whiteboard defense before you push: a git hook that quizzes you on your own diff.
+Project-URL: Homepage, https://github.com/guilyx/grip
+Project-URL: Documentation, https://guilyx.github.io/grip/
+Project-URL: Repository, https://github.com/guilyx/grip
+Project-URL: Issues, https://github.com/guilyx/grip/issues
+Project-URL: Changelog, https://github.com/guilyx/grip/blob/main/CHANGELOG.md
+Project-URL: Releases, https://github.com/guilyx/grip/releases
+Author-email: "Erwin L." <erwin.lejeune15@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: code-review,git,hook,llm,pre-commit,pre-push,quiz,understanding
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anthropic<2,>=1.0
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: rich>=13.7
+Provides-Extra: demo
+Requires-Dist: fonttools>=4.40; extra == 'demo'
+Requires-Dist: imageio-ffmpeg>=0.5; extra == 'demo'
+Requires-Dist: pillow>=10.0; extra == 'demo'
+Requires-Dist: pyte>=0.8; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Description-Content-Type: text/markdown
+
+**Pass the whiteboard defense before you push.** grip is a git hook that pulls you aside
+at the moment you ship and asks what a senior engineer would: what does this do, why this
+way and not another, where does it fail, what could go wrong. Five questions written from
+your own diff, a Grip Score out of 100, and a pass mark your team sets. Below the mark,
+nothing goes upstream.
+
+[![CI](https://github.com/guilyx/grip/actions/workflows/ci.yml/badge.svg)](https://github.com/guilyx/grip/actions/workflows/ci.yml)
+[![Docs](https://github.com/guilyx/grip/actions/workflows/docs.yml/badge.svg)](https://guilyx.github.io/grip/)
+[![PyPI](https://img.shields.io/pypi/v/grip-hook)](https://pypi.org/project/grip-hook/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/guilyx/grip/blob/main/LICENSE)
+
+<table>
+<tr>
+<td align="center" width="33%"><h3>5 questions</h3>written from <em>your</em> diff, graded against a hidden rubric, 100 points</td>
+<td align="center" width="33%"><h3>12 → 92</h3>the same diff blocked with lazy answers, through with real ones (<a href="https://github.com/guilyx/grip/blob/main/docs/assets/demo.mp4">demo</a>)</td>
+<td align="center" width="33%"><h3>0 new tools to learn</h3>a git hook, or <code>/grip</code> inside Claude Code, Codex, Gemini CLI, Cursor and friends</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<th width="50%">Without grip</th>
+<th width="50%">With grip</th>
+</tr>
+<tr>
+<td valign="top">
+
+```text
+$ git push
+Enumerating objects: 14, done.
+...
+To github.com:acme/robot.git
+   3f2a1c9..8e7d4b2  main -> main
+```
+
+Four hundred lines the assistant wrote, nobody on the team can explain, now upstream.
+
+</td>
+<td valign="top">
+
+```text
+$ git push
+grip  5 questions about your push (pre-push). Pass mark: 70/100.
+
+Q1/5 (behaviour) What happens to a cmd_vel message
+     whose linear.x exceeds the new limit?
+> it is clamped to the limit, not dropped, so the
+> robot keeps moving at the max speed
+
+...
+
+Grip Score: 92/100  PASS
+```
+
+Same push, one minute later. You can explain it in the review because you just did.
+
+</td>
+</tr>
+</table>
+
+![grip blocking a commit with lazy answers, then letting it through after real ones](https://raw.githubusercontent.com/guilyx/grip/main/docs/assets/demo.gif)
+
+<sub>A commit blocked at 12/100, then accepted at 92/100. [Video version](https://github.com/guilyx/grip/blob/main/docs/assets/demo.mp4). Recorded with the offline scripted provider, so questions are canned; a real model writes them from your diff.</sub>
+
+## The whiteboard defense
+
+> I should be able to pull you aside at any moment and ask you to explain any
+> customer-facing system you've shipped. [...] I don't expect line-level familiarity with
+> the code. [...] But if I ask "why did you do X instead of Y?", "what happens if this
+> actor behaves maliciously?", "what data structure did you use here and why?", or "where
+> does this fail?" you should be able to answer confidently.
+>
+> Mitchell Hashimoto
+
+We found this post after we built grip, and it is the clearest statement of what grip is
+for. (Mitchell is not involved with grip.) The bar is not line-level recall. It is being
+able to explain and defend a system you put in front of customers, however much of it a
+model wrote.
+
+grip runs that conversation at the last moment it is cheap: before the push.
+
+| At the whiteboard | What grip asks |
+| --- | --- |
+| How does it work? | **behaviour**: what the change does, in your words |
+| Why X instead of Y? | **motivation**: why it is built this way |
+| Where does this fail? | **edge case**: the input or state that breaks it |
+| What could go wrong? | **risk**: side effects, and what else it touches |
+| How do you know? | **testing**: how you would show it works |
+
+The questions never ask for line numbers, exact strings or function names. A model writes
+them from the diff with a hidden rubric, then grades your answers against it.
+
+### `grip whiteboard`: the whole defense
+
+`grip whiteboard` draws your change the way you would on a whiteboard: its parts, how they
+connect, which inputs are untrusted. It pins five questions to the drawing, including the
+two the quiz does not ask directly, **what a malicious actor could do** and **why this data
+structure**, and opens it in your browser. Click a part, answer, hand in. Same score, same
+pass mark, and a pass counts for the push hook.
+
+```bash
+grip whiteboard                    # defend your staged change in the browser
+grip whiteboard --interview        # for the person asking: rubrics visible, tick what you hear
+grip whiteboard --export board.html  # a shareable copy, no rubrics
+```
+
+![grip whiteboard: the change drawn as parts, with questions pinned to them](https://raw.githubusercontent.com/guilyx/grip/main/docs/assets/whiteboard.png)
+
+**Prototype freely, defend what ships.** For a spike, a demo or an experiment, generate
+all of it: `grip skip` lets one push through, `grip skip --hours 2` pauses grip for a
+session, or leave the hook out of that repository. Keep the hook where customers are.
+
+## Why now
+
+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 gap grip aims at is measured, not imagined. In METR's 2025 randomised trial,
+experienced open-source developers using AI tools were [19% slower while believing they
+were 20% faster](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/).
+GitClear's analysis of 153 million changed lines found [code churn on track to double
+since AI assistants arrived](https://www.gitclear.com/coding_on_copilot_data_shows_ais_downward_pressure_on_code_quality).
+The [2024 DORA report](https://dora.dev/research/2024/dora-report/) linked higher AI
+adoption to lower delivery stability, and the [2025 Stack Overflow survey](https://survey.stackoverflow.co/2025/ai)
+put developer trust in AI output at a low. Every one of these tools checks the code. grip
+is the only one that checks the human.
+
+## Install
+
+grip is on PyPI as [`grip-hook`](https://pypi.org/project/grip-hook/). Install it as a
+command-line tool with pipx or uv (Python 3.11+):
+
+```bash
+pipx install grip-hook        # or: uv tool install grip-hook
+```
+
+Plain `pip install grip-hook` works too, inside a virtualenv. You get `grip` and a
+`git grip` alias, on Linux, macOS and Windows. Upgrade with `pipx upgrade grip-hook` (or
+`uv tool upgrade grip-hook`).
+
+Neither pipx nor uv? `curl -fsSL https://raw.githubusercontent.com/guilyx/grip/main/install.sh | sh`
+uses whichever one it finds and tells you how to get uv when there is neither.
+
+Then, in your repository:
+
+```bash
+grip init
+```
+
+That writes a commented `.grip.toml`, installs the pre-push hook and tells the coding
+agents on your machine to run the quiz before they push. Commit the files and the team
+shares the setup. Prefer to do it by hand? Two ways to wire it into git:
+
+### Option A: native git hook
+
+```bash
+cd your-repo
+grip install                  # pre-push (recommended)
+grip install --stage pre-commit --stage pre-push   # both
+```
+
+### Option B: pre-commit framework
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/guilyx/grip
+    rev: v0.2.1
+    hooks:
+      - id: grip          # runs at pre-push
+      # - id: grip-commit # runs at pre-commit
+```
+
+```bash
+pre-commit install --hook-type pre-push
+```
+
+### Inside a coding agent
+
+grip is an [Agent Skill](https://agentskills.io). One command installs it into Claude
+Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Copilot and friends:
+
+```bash
+npx skills add guilyx/grip -g
+```
+
+Then type `/grip` before you push. The agent relays the five questions, you answer, grip
+grades; the skill forbids the agent from answering for you. `/grip-review main..feat`
+quizzes a reviewer on someone else's branch, `/grip-explain` turns your answers into the
+commit message, and `/grip-whiteboard` opens the whiteboard in your browser so you answer
+there. Claude Code users can take the
+plugin instead, which also blocks `git push` until the diff has passed:
+
+```text
+/plugin marketplace add guilyx/grip
+/plugin install grip@grip
+```
+
+`grip agents` writes the rule file each agent on your machine reads (`AGENTS.md`,
+`CLAUDE.md`, `GEMINI.md`, Cursor, Windsurf, Cline, Copilot) so it runs `grip check` before
+every push. See the [docs](https://guilyx.github.io/grip/agents/) for the raw
+`grip ask` / `grip grade` flow any agent can drive.
+
+### Provider
+
+Already using Claude Code, Codex or Gemini CLI? grip can reuse it, so there is no API key
+and no extra bill:
+
+```toml
+# .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:
+
+```toml
+# .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.
+
+```bash
+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 whiteboard               # draw the change and defend it in the browser
+grip status                   # hooks, last score, what has passed, configuration
+grip skip && git push         # bypass once (GRIP_SKIP=1 and --no-verify work too)
+grip skip --hours 1           # pause the hooks for a demo; grip resume cancels
+```
+
+A diff that passed is remembered for 24 hours, so a pre-push right after a pre-commit
+does not ask again.
+
+## Practice on Keep A Grip
+
+[Keep A Grip](https://keepagrip.vercel.app) is a catalogue of ROS 2, robotics and AI
+problems built for this loop: solve one with any assistant, then let grip quiz you on the
+diff. Scores land on your dashboard; anyone can add a problem.
+
+```bash
+grip login kag_…                   # token from your dashboard
+grip solve cmd-vel-safety-filter   # a repo with PROBLEM.md, pass mark preset
+grip submit                        # tests, five questions, score reported
+```
+
+Only the score leaves your machine. See the [docs](https://guilyx.github.io/grip/keepagrip/).
+
+## 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.
+
+```toml
+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](https://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`.
+
+## When grip gets in the way
+
+A one-line typo fix does not deserve five questions, and grip cannot tell a rename from a
+rewrite. That is what the escape hatches are for: `grip skip` for one push,
+`grip skip --hours 1` for a pairing session, `exclude` for generated files,
+`remember_passes_hours` so a passed diff is not asked twice. Questions and grading come
+from a language model, so they are sometimes unfair; the per-question feedback shows you
+why, and `grip quiz` gives a fresh set. What has and has not been measured about the
+quiz, and where it is known to be annoying, is on the
+[honest numbers](https://guilyx.github.io/grip/honest-numbers/) page; the
+[evals harness](https://github.com/guilyx/grip/blob/main/evals/) behind it runs offline. Treat the Grip Score as a prompt to
+re-read, not a verdict.
+
+## Cite
+
+If grip is part of a study or a course, please cite it ([CITATION.cff](https://github.com/guilyx/grip/blob/main/CITATION.cff)):
+
+```bibtex
+@software{lejeune2026grip,
+  author = {L., Erwin},
+  title  = {grip: keep a grip on your code},
+  year   = {2026},
+  url    = {https://github.com/guilyx/grip}
+}
+```
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/guilyx/grip/blob/main/CONTRIBUTING.md) for the
+development setup, and [SECURITY.md](https://github.com/guilyx/grip/blob/main/SECURITY.md) for what data grip touches.
+
+## Media
+
+A [launch video](https://github.com/guilyx/grip/blob/main/docs/assets/launch/grip-launch-1080p.mp4), the
+[Product Hunt image](https://raw.githubusercontent.com/guilyx/grip/main/docs/assets/launch/grip-producthunt-1270x760.png) 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](https://guilyx.github.io/grip/media/).
+
+## License
+
+[BSD-3-Clause](https://github.com/guilyx/grip/blob/main/LICENSE). Copyright (c) 2026, Erwin L.