Install AI coding agent guardrails in minutes

1. Requirements

2. Install (about a minute)

These steps work from Cotterpin 0.3.0, its first working release, coming soon. Until then the cotterpin package is a name reservation that installs nothing useful. Founding Developers are first in line.

pipx install cotterpin
pipx inject cotterpin cotterpin-pack-java     # each language pack is its own package: add the ones you use
cotterpin --version                           # names the packs it found

No Python 3.11 yet? On macOS, install one beside the system copy first, for example brew install python@3.12, then pipx install --python python3.12 cotterpin.

3. Connect your agent tool (once per machine)

cotterpin adapters install claude     # or: codex, grok — one for each tool you use

This puts Cotterpin into Antigravity,Claude, Codex or Grok for your whole machine, in the tool's own user folder: never into a repository, so there is nothing to commit and your team's repositories stay as they are. It lists every file first, shows line for line any block it adds to a file of yours (such as ~/.codex/AGENTS.md), and asks. Then start or restart the tool. Its hooks act only in a repository set up with Cotterpin; in your other repositories they stay silent. cotterpin adapters uninstall claude takes it back exactly.

4. Set up your repository (under a minute)

cd path/to/your-repository
cotterpin init

init asks once whether it may list the file names at the top of your repository, to choose a language pack. It never reads file contents. Say no and choose the pack yourself with cotterpin init --pack java. It writes two files for your team to commit, .cotterpin/policy.yaml and .cotterpin.lock.json, and one marked block in Git's own exclude file (.git/info/exclude, never committed) so Cotterpin's per-developer state stays out of commits. Your .gitignore is never touched. It never overwrites an existing policy or lock, and --dry-run shows the plan without writing anything.

5. Check your machine (1–2 minutes)

cotterpin doctor

One line per prerequisite: PASS, FIX with the exact command that fixes it, or SKIP for a check you declined. Run each fix, then cotterpin doctor again until no line says FIX.

6. Sign in to a provider (if doctor said so)

claude auth login        # or: codex login
cotterpin connect        # confirms the sign-in; Cotterpin stores no provider secret

7. Commit the setup

git add .cotterpin/policy.yaml .cotterpin.lock.json
cotterpin commit -m "Set up Cotterpin"

From here, keep prompting your agent the way you do now. Cotterpin checks every “done”, and cotterpin report shows what it caught. To run your own tests through it, declare them in .cotterpin/checks.yaml, then run cotterpin update and cotterpin check.

8. Removing it again

• cotterpin uninstall removes it from one repository, and lists everything first.
• cotterpin adapters uninstall claude (or codex, grok) takes one agent tool's adapter back, exactly as it was installed.
• cotterpin --uninstall removes it from your whole machine, the agent tool adapters included.
• Every change it made to your code was a commit, so each one can be reverted.