grip-hook 0.2.1__tar.gz → 0.2.2__tar.gz

{grip_hook-0.2.1 → grip_hook-0.2.2}/CHANGELOG.md

@@ -6,6 +6,45 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-10-19
+
+### Changed
+
+- Releases are automatic. Each pull request carries one label, `release:patch`,
+  `release:minor`, `release:major` or `release:none`; merging a labelled one bumps the
+  version, dates the changelog, tags `main` and publishes to PyPI and GitHub. A check
+  makes sure every pull request has exactly one.
+- `grip init` asks, in a terminal, which model to use, the pass mark and whether to quiz
+  before pushes, commits or both, with defaults detected on the machine, then says what
+  the chosen provider still needs. `--yes` takes every default; scripts are not asked.
+- `grip install` says which model will write the questions when none is configured.
+
+### Fixed
+
+- Pushing a new branch said "nothing to quiz" when its commits were also on a branch that
+  had been deleted upstream (a merged pull request) but not pruned locally: the stale
+  `origin/...` ref made them look pushed. grip now asks the remote with `git ls-remote`
+  whenever the local refs say a new branch has nothing to send.
+- With no provider configured, grip used the Anthropic API even when Claude Code, Codex or
+  Gemini CLI was installed, and without an API key it crashed with a traceback. The
+  default provider is now `auto`: the first installed coding agent, else Anthropic. A
+  missing Anthropic key is now a clear error that says what to set.
+- `grip quiz --range main..feat/x` cut branch names to 12 characters in its header
+  (`main..feat/kidnap-`); only full hashes are shortened now.
+
+### Documentation
+
+- A shorter README in the usual open-source shape: what grip is, install, quick start,
+  configuration, links. The long-form material moved to the docs site.
+- New [walkthrough](https://guilyx.github.io/grip/walkthrough/): one real change, from
+  `git commit` to an accepted push, with the real questions, grades and screenshots.
+- New [inside grip](https://guilyx.github.io/grip/internals/) deep dive: the checks before
+  a quiz, diff collection, prompts, structured output per provider, rubric grading, pass
+  memory, the agent flow, the whiteboard's validation, layout and server, and what is
+  stored or sent.
+- The docs navigation is regrouped into Get started, Guides, Deep dive, Reference and
+  Project.
+
 ## [0.2.1] - 2026-10-19
 
 grip is on PyPI.
@@ -167,7 +206,8 @@ The first public release.
 - 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
+[Unreleased]: https://github.com/guilyx/grip/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/guilyx/grip/compare/v0.2.1...v0.2.2
 [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.2/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: grip-hook
+Version: 0.2.2
+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
+
+# grip
+
+**Pass the whiteboard defense before you push.**
+
+[![CI](https://github.com/guilyx/grip/actions/workflows/ci.yml/badge.svg)](https://github.com/guilyx/grip/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/grip-hook)](https://pypi.org/project/grip-hook/)
+[![Python](https://img.shields.io/pypi/pyversions/grip-hook)](https://pypi.org/project/grip-hook/)
+[![Docs](https://img.shields.io/badge/docs-guilyx.github.io%2Fgrip-ff8644)](https://guilyx.github.io/grip/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/guilyx/grip/blob/main/LICENSE)
+
+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.
+
+![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)
+
+## 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
+
+```bash
+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
+
+```bash
+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](https://guilyx.github.io/grip/providers/).
+
+Other commands you will use:
+
+```bash
+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](https://guilyx.github.io/grip/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:
+
+```toml
+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](https://guilyx.github.io/grip/configuration/).
+
+## Documentation
+
+**[guilyx.github.io/grip](https://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](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 reporting vulnerabilities and what data grip sends. This project follows a
+[code of conduct](https://github.com/guilyx/grip/blob/main/CODE_OF_CONDUCT.md).
+
+## Citation
+
+If grip is part of a study or a course, please cite it; GitHub's "Cite this repository"
+button reads [CITATION.cff](https://github.com/guilyx/grip/blob/main/CITATION.cff).
+
+## License
+
+[BSD-3-Clause](https://github.com/guilyx/grip/blob/main/LICENSE). Copyright (c) 2026, Erwin L.

grip_hook-0.2.2/README.md

@@ -0,0 +1,100 @@
+# grip
+
+**Pass the whiteboard defense before you push.**
+
+[![CI](https://github.com/guilyx/grip/actions/workflows/ci.yml/badge.svg)](https://github.com/guilyx/grip/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/grip-hook)](https://pypi.org/project/grip-hook/)
+[![Python](https://img.shields.io/pypi/pyversions/grip-hook)](https://pypi.org/project/grip-hook/)
+[![Docs](https://img.shields.io/badge/docs-guilyx.github.io%2Fgrip-ff8644)](https://guilyx.github.io/grip/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/guilyx/grip/blob/main/LICENSE)
+
+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.
+
+![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)
+
+## 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
+
+```bash
+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
+
+```bash
+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](https://guilyx.github.io/grip/providers/).
+
+Other commands you will use:
+
+```bash
+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](https://guilyx.github.io/grip/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:
+
+```toml
+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](https://guilyx.github.io/grip/configuration/).
+
+## Documentation
+
+**[guilyx.github.io/grip](https://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](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 reporting vulnerabilities and what data grip sends. This project follows a
+[code of conduct](https://github.com/guilyx/grip/blob/main/CODE_OF_CONDUCT.md).
+
+## Citation
+
+If grip is part of a study or a course, please cite it; GitHub's "Cite this repository"
+button reads [CITATION.cff](https://github.com/guilyx/grip/blob/main/CITATION.cff).
+
+## License
+
+[BSD-3-Clause](https://github.com/guilyx/grip/blob/main/LICENSE). Copyright (c) 2026, Erwin L.

{grip_hook-0.2.1 → grip_hook-0.2.2}/src/grip_hook/__init__.py

@@ -3,7 +3,7 @@
 A git hook that quizzes you about your own diff before you commit or push it.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 QUESTION_COUNT = 5
 """Number of questions asked in every quiz. Fixed by design."""

{grip_hook-0.2.1 → grip_hook-0.2.2}/src/grip_hook/cli.py

@@ -6,6 +6,7 @@ import contextlib
 import dataclasses
 import json
 import os
+import shutil
 import subprocess
 import sys
 import webbrowser
@@ -32,8 +33,11 @@ from grip_hook.agent import (
     report_payload,
 )
 from grip_hook.config import (
+    AGENT_PROVIDERS,
+    AUTO_PROVIDER,
     DEFAULT_PASSING_SCORE,
     Config,
+    auto_provider,
     describe,
     load_config,
     render_template,
@@ -41,7 +45,7 @@ from grip_hook.config import (
 from grip_hook.errors import GripError, NoTerminalError, ProviderError, QuizFailed
 from grip_hook.git import Diff, Git, PushedRef
 from grip_hook.hooks import INSTALLABLE_STAGES, install, status, uninstall
-from grip_hook.integrations import AGENTS, Action, agent, apply, detect, is_installed
+from grip_hook.integrations import AGENTS, Action, agent, apply, detect
 from grip_hook.memory import PassMemory, SkipState
 from grip_hook.models import Difficulty, QuestionSet, Report, Stage
 from grip_hook.platform import (
@@ -634,10 +638,92 @@ def _push_diff(git: Git, cfg: Config, hook_args: tuple[str, ...]) -> Diff:
 
 def _default_provider() -> str:
     """The provider ``grip init`` picks: a signed-in coding agent when there is one."""
-    for key in ("claude-code", "codex", "gemini"):
-        if is_installed(agent(key)):
-            return key
-    return "anthropic"
+    return auto_provider()
+
+
+_PROVIDER_HINTS = {
+    "claude-code": "Claude Code, already signed in: no key, no extra bill",
+    "codex": "Codex CLI, already signed in: no key, no extra bill",
+    "gemini": "Gemini CLI, already signed in: no key, no extra bill",
+    "auto": "each teammate's installed coding agent, else anthropic",
+    "anthropic": "Anthropic API: needs ANTHROPIC_API_KEY or `ant auth login`",
+    "ollama": "a local model through Ollama: free, set `model` in .grip.toml",
+    "openai": "any OpenAI-compatible API: set `base_url` and OPENAI_API_KEY",
+}
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class _InitChoices:
+    provider: str
+    passing_score: int
+    stages: tuple[str, ...]
+    agents: bool
+
+
+def _init_wizard(
+    defaults: _InitChoices,
+    *,
+    ask_provider: bool,
+    ask_score: bool,
+    ask_stages: bool,
+    ask_agents: bool,
+) -> _InitChoices:
+    """Ask, in the terminal, for what the flags did not say. Enter keeps each default."""
+    _out.print("[bold]grip init[/bold] [dim]· Enter keeps the default in brackets[/dim]\n")
+    provider = defaults.provider
+    if ask_provider:
+        installed = [name for name, command in AGENT_PROVIDERS if shutil.which(command)]
+        options = [*installed, "auto", "anthropic", "ollama", "openai"]
+        _out.print("[bold]Which model asks and grades the questions?[/bold]")
+        for name in options:
+            _out.print(f"  [cyan]{name:<12}[/cyan] {_PROVIDER_HINTS[name]}")
+        provider = click.prompt(
+            "Provider", type=click.Choice(options), default=defaults.provider, show_choices=False
+        )
+    score = defaults.passing_score
+    if ask_score:
+        score = click.prompt(
+            f"\nPass mark, out of {MAX_SCORE}", type=click.IntRange(0, MAX_SCORE), default=score
+        )
+    stages = defaults.stages
+    if ask_stages:
+        when = click.prompt(
+            "\nQuiz before every push, every commit, or both?",
+            type=click.Choice(["push", "commit", "both"]),
+            default="push",
+        )
+        stages = {"push": ("pre-push",), "commit": ("pre-commit",)}.get(
+            when, ("pre-commit", "pre-push")
+        )
+    agents = defaults.agents
+    if ask_agents and (found := detect()):
+        names = ", ".join(a.name for a in found)
+        agents = click.confirm(
+            f"\nTell the coding agents here ({names}) to run the quiz before they push?",
+            default=True,
+        )
+    _out.print()
+    return _InitChoices(provider, score, stages, agents)
+
+
+def _interactive() -> bool:
+    """Whether someone is at the keyboard to answer ``grip init``'s questions."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _provider_tip(provider: str) -> str | None:
+    """What still has to happen for ``provider`` to work, if anything."""
+    resolved = auto_provider() if provider == "auto" else provider
+    command = dict(AGENT_PROVIDERS).get(resolved)
+    if command and not shutil.which(command):
+        return f"`{command}` is not on PATH yet; install it and sign in before the next push."
+    if resolved == "anthropic" and not os.environ.get("ANTHROPIC_API_KEY"):
+        return "set ANTHROPIC_API_KEY (or run `ant auth login`) before the next push."
+    if resolved == "ollama":
+        return "set `model` in .grip.toml to a model you have pulled, e.g. qwen3:14b."
+    if resolved == "openai":
+        return "set `base_url` in .grip.toml and export OPENAI_API_KEY."
+    return None
 
 
 @cli.command(name="init")
@@ -669,6 +755,7 @@ def _default_provider() -> str:
 @click.option("--no-hook", is_flag=True, help="Do not install a git hook.")
 @click.option("--no-agents", is_flag=True, help="Do not write coding-agent rule files.")
 @click.option("--force", is_flag=True, help="Overwrite an existing .grip.toml.")
+@click.option("--yes", "-y", is_flag=True, help="Take every default instead of asking.")
 def init_cmd(
     *,
     provider: str | None,
@@ -678,34 +765,56 @@ def init_cmd(
     no_hook: bool,
     no_agents: bool,
     force: bool,
+    yes: bool,
 ) -> None:
     """Set a repository up in one go: .grip.toml, the git hook and the agent rule files.
 
-    Picks a provider you will not need a key for when Claude Code, Codex or Gemini CLI is
-    installed. Everything it writes is meant to be committed so the whole team shares it.
+    In a terminal it asks which model to use, the pass mark and when to quiz, with
+    defaults picked for this machine; flags answer a question up front and --yes takes
+    every default. It picks a provider you will not need a key for when Claude Code, Codex
+    or Gemini CLI is installed. Everything it writes is meant to be committed so the whole
+    team shares it.
     """
     git = Git()
     root = git.root()
     toml_path = root / ".grip.toml"
-    if toml_path.exists() and not force:
+    writing = force or not toml_path.exists()
+    choices = _InitChoices(
+        provider=(provider or _default_provider()).lower(),
+        passing_score=DEFAULT_PASSING_SCORE if passing_score is None else passing_score,
+        stages=stages or (Stage.PRE_PUSH.value,),
+        agents=not no_agents,
+    )
+    if not yes and _interactive():
+        choices = _init_wizard(
+            choices,
+            ask_provider=writing and provider is None,
+            ask_score=writing and passing_score is None,
+            ask_stages=not no_hook and not stages,
+            ask_agents=not no_agents,
+        )
+    if not writing:
         _out.print(
             f"[dim]grip: {_pretty_path(toml_path)} exists, keeping it (--force overwrites)[/dim]"
         )
     else:
-        chosen = (provider or _default_provider()).lower()
         text = render_template(
-            provider=chosen,
-            passing_score=DEFAULT_PASSING_SCORE if passing_score is None else passing_score,
+            provider=choices.provider,
+            passing_score=choices.passing_score,
             difficulty=difficulty or Difficulty.NORMAL.value,
         )
         toml_path.write_text(text, "utf-8")
-        _out.print(f"[green]grip:[/green] wrote {_pretty_path(toml_path)} (provider {chosen})")
+        _out.print(
+            f"[green]grip:[/green] wrote {_pretty_path(toml_path)} (provider {choices.provider})"
+        )
+        if tip := _provider_tip(choices.provider):
+            _out.print(f"[yellow]grip:[/yellow] {tip}")
     if not no_hook:
-        for stage in stages or (Stage.PRE_PUSH.value,):
+        for stage in choices.stages:
             result = install(git, Stage(stage), append=True)
             how = "appended to" if result.appended else "installed at"
             _out.print(f"[green]grip:[/green] {stage} hook {how} {_pretty_path(result.path)}")
-    if not no_agents:
+    if choices.agents:
         changes = apply(root, detect())
         past = {Action.WRITTEN: "wrote", Action.UPDATED: "updated"}
         for change in changes:
@@ -808,6 +917,15 @@ def install_cmd(stages: tuple[str, ...], force: bool, append: bool) -> None:
         result = install(git, Stage(stage), force=force, append=append)
         how = "appended to" if result.appended else "installed at"
         _out.print(f"[green]grip:[/green] {stage} hook {how} {result.path}")
+    cfg = _config(git)
+    if cfg.provider == AUTO_PROVIDER:
+        _out.print(
+            f"[dim]grip: no provider configured, so the questions come from "
+            f"{cfg.provider_name} (provider auto). `grip init` sets the model, the pass mark "
+            "and the team's defaults.[/dim]"
+        )
+        if tip := _provider_tip(cfg.provider):
+            _out.print(f"[yellow]grip:[/yellow] {tip}")
     _out.print("[dim]Run `grip status` to check, `grip uninstall` to remove.[/dim]")
 
 

{grip_hook-0.2.1 → grip_hook-0.2.2}/src/grip_hook/config.py

@@ -12,6 +12,7 @@ Precedence, highest first:
 from __future__ import annotations
 
 import os
+import shutil
 import tomllib
 from dataclasses import dataclass, fields, replace
 from pathlib import Path
@@ -47,6 +48,27 @@ DEFAULT_EXCLUDES: tuple[str, ...] = (
 
 ENV_PREFIX = "GRIP_"
 
+AUTO_PROVIDER = "auto"
+AGENT_PROVIDERS: tuple[tuple[str, str], ...] = (
+    ("claude-code", "claude"),
+    ("codex", "codex"),
+    ("gemini", "gemini"),
+)
+"""Coding-agent providers ``auto`` tries, in order, with the command each one needs."""
+
+
+def auto_provider() -> str:
+    """What ``provider = "auto"`` means on this machine.
+
+    A coding agent that is installed (and so, usually, signed in) needs no API key and adds
+    no bill, so the first of Claude Code, Codex and Gemini CLI on ``PATH`` wins; without
+    one, the Anthropic API.
+    """
+    for name, command in AGENT_PROVIDERS:
+        if shutil.which(command):
+            return name
+    return "anthropic"
+
 
 @dataclass(frozen=True, slots=True)
 class Config:
@@ -55,9 +77,10 @@ class Config:
     passing_score: int = DEFAULT_PASSING_SCORE
     """Minimum Grip Score (0-100) required to let the commit or push through."""
 
-    provider: str = "anthropic"
-    """Provider name: ``anthropic``, ``openai``, ``ollama``, ``claude-code``, ``codex``,
-    ``gemini`` or ``fake``."""
+    provider: str = AUTO_PROVIDER
+    """Provider name: ``auto``, ``anthropic``, ``openai``, ``ollama``, ``claude-code``,
+    ``codex``, ``gemini`` or ``fake``. ``auto`` picks an installed coding agent, else
+    ``anthropic``; see :func:`auto_provider`."""
 
     model: str = ""
     """Model identifier passed to the provider. Empty means the provider's default."""
@@ -106,6 +129,12 @@ class Config:
             raise ConfigError("provider must not be empty")
         return self
 
+    @property
+    def provider_name(self) -> str:
+        """The provider that will actually run: ``auto`` resolved on this machine."""
+        name = self.provider.lower()
+        return auto_provider() if name == AUTO_PROVIDER else name
+
 
 _FIELD_NAMES = {f.name for f in fields(Config)}
 
@@ -205,7 +234,8 @@ passing_score = {passing_score}
 # easy | normal | hard
 difficulty = "{difficulty}"
 
-# anthropic | claude-code | codex | gemini | openai | ollama | fake
+# auto | anthropic | claude-code | codex | gemini | openai | ollama | fake
+# (auto: an installed coding agent, else anthropic)
 provider = "{provider}"
 
 # model = ""                   # empty: the provider's default
@@ -239,16 +269,21 @@ def describe(cfg: Config) -> list[tuple[str, str]]:
             text = value.value
         else:
             text = str(value) if value != "" else "(provider default)"
+        if f.name == "provider" and value == AUTO_PROVIDER:
+            text = f"{AUTO_PROVIDER} ({cfg.provider_name})"
         rows.append((f.name, text))
     return rows
 
 
 __all__ = [
+    "AGENT_PROVIDERS",
+    "AUTO_PROVIDER",
     "DEFAULT_EXCLUDES",
     "DEFAULT_MODEL",
     "DEFAULT_PASSING_SCORE",
     "TEMPLATE",
     "Config",
+    "auto_provider",
     "describe",
     "load_config",
     "render_template",