pinrule

🇬🇧 English (current) · 🇨🇳 中文

Pin the 5-10 rules your AI must not drift from during long tasks. Ships with a 7-rule dev preset; switch to any other scenario with one sentence: /pinrule I mainly do X, switch to this scenario.

Runtime: pure engineering · zero LLM · zero network · zero runtime deps · ~50-70ms hook · ~2% token overhead. (Scenario rule pack generation runs in your Agent — see Path B below.)

Andrej Karpathy's CLAUDE.md teaches your AI how to write good code. pinrule keeps your AI aligned with your personal preferences in long tasks — what to never do, what to always do, what to push back on — so you don't have to repeat yourself every 30 turns.

---

Quick start

Let your Agent install it (recommended — least friction)

Since you're already using Claude Code / Codex / Cursor (otherwise you wouldn't need pinrule), paste this prompt to your Agent:

Install pinrule (github.com/jhaizhou-ops/pinrule) — a universal AI behavior rule
framework that keeps my long-task rules from being lost. Steps:

1. Verify Python is actually installed (Windows: run `python --version` — if it
   silently exits to Microsoft Store, first `winget install Python.Python.3.12`
   and reopen PowerShell). Use `python -m pinrule` form on Windows to avoid PATH issues.
2. pip install pinrule
3. pinrule init      # auto-installs default rules + hooks for every detected client
4. pinrule doctor    # verify install
5. Show me the 7 default rules + how to add my own via /pinrule

The Agent figures out your OS, Python state, and which clients you have. After install, restart your client and rules take effect.

Manual install

pip install pinrule && pinrule init

pinrule init auto-installs hooks for any detected client (Claude / Codex / Cursor / Hermes) + writes default rules to ~/.pinrule/. If you install a new client later, run pinrule install-hooks to wire it up.

Restart Claude / Codex / Cursor / Hermes — default rules become active once hooks load.

Uninstall — pinrule uninstall-hooks (auto-removes pinrule entries from every detected client surgically; doesn't touch hooks installed by other tools).

Windows without Python: python --version silently jumping to Microsoft Store means no real Python — install via winget install Python.Python.3.12, reopen PowerShell, then use python -m pip install pinrule && python -m pinrule init (the python -m form avoids needing Scripts\ on PATH).

---

What pinrule does

• Injects your 5-10 directions at session start, compact anchor each turn, full reinject on long-context decay.
• Blocks drift in real time — Bash sleep, Edit-before-Read, "let me hardcode this" intent declarations all caught before they ship.
• Survives compact — dumps full rule state pre-compact; reloads + re-injects post-restart.

Per-hook lifecycle: see ARCHITECTURE.md.

---

How it fits together

flowchart LR
    R[(rules.json5-10 core directions)]
    K[pinrule engineregex + counting]
    A[🤖 AgentClaude / Codex / Cursor / Hermes]
    V[(violations.jsonlaudit history)]

    R ==> K
    K ==>|prompt header| A
    A ==>|tool call / response| K
    K -.->|hit → deny + log| V
    V -.->|next-turn drift marker| K