Install

cogpin is a Claude Code plugin. The engine is a single stdlib-only cogpin.py, so python3 (3.11+) needs to be on your PATH — including the non-interactive shell’s PATH for Nix/nvm setups. If it isn’t, nothing errors; the gate just stays quiet.

Agent layer — per developer

1. Add the marketplace:

   /plugin marketplace add IvanWng97/cogpin

2. Install the plugin (a separate prompt — send it after the first):

   /plugin install cogpin@cogpin

That’s the agent layer immediately: the PreToolUse deny + Stop nudge fire every session, and /cogpin-init / /cogpin-check become available. “Default-on” means enforcement is a property of your client + the repo, not a step the agent has to remember.

The desktop app has no /plugin command — install from the UI: Customize → the + by personal plugins → Create plugin and add marketplace → Add from repository → the repo URL.

Change layer — per repo (authoritative)

The agent layer is per-developer and bypassable; the change layer (pre-push + CI, base-pinned, un-bypassable) is per-repo. Run once, inside Claude Code:

/cogpin-init

One command runs cogpin install — vendors the engine to .cogpin/cogpin.py, scaffolds cogpin.toml, wires a pre-push managed block into your effective hooks dir (coexisting with any husky/lefthook/pre-commit — it appends, never clobbers), and adds .github/workflows/cogpin.yml — then drafts a policy from your CLAUDE.md house rules as cogpin.toml.draft for you to review and rename. Then /cogpin-doctor confirms both layers are live. Commit .cogpin/cogpin.py, cogpin.toml, and the workflow, and every clone — every agent, every PR — meets the same gate. The scaffolded CI is two steps over the composite action:

permissions: { contents: read, pull-requests: read, checks: read }  # reviews/checks SKIP without these
jobs:
  cogpin:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0 }          # base-pinning needs history
      - uses: IvanWng97/cogpin@v0         # rev-pinned engine over your base-pinned config

The action runs its own rev-pinned engine (not the repo’s head-side copy) over your base-pinned config, so a PR can’t rewrite the engine to exit 0 or relax the policy in the same diff it’s gated on. No npm, no package manager, no binary download — one stdlib-Python file, committed.

The change layer needs no Claude Code at all, so it gates human PRs and any agent CLI too; only the real-time agent layer is Claude-Code-specific. Not on GitHub Actions? A teammate’s local pre-push is python3 .cogpin/cogpin.py install --no-vendor --no-config --no-ci; on GitLab CI, set GIT_DEPTH: 0, fetch the default branch, and run python3 .cogpin/cogpin.py check (PR-review facts degrade-to-skip off-GitHub).

Next: lift a recipe → for your stack.