Most attempts to keep an AI on track during long sessions lean on memory stores or retrieval pipelines. Tools like mem0 or Claude's built-in memory capture facts about you and hope the model consults them. pinrule takes a different stance: your preferences aren't data to be recalled, they're constraints to be enforced. The project is a small Python framework that injects 5-10 behavioral rules into the prompt stream of Claude, Codex, or Cursor, then watches every tool call and response for drift.

What pinrule does differently

The README describes pinrule as a "behavioral contract" rather than a wishlist. Rules live in a single rules.json file. The engine reads them using regex and counting — no LLM calls, no network requests at runtime, no third-party dependencies. Each prompt and each tool call gets the rules re-injected, and the engine logs violations to violations.jsonl. If the conversation is compacted, the full rule state is dumped beforehand and restored after restart.

Where memory tools wait for the agent to decide it wants a refresher, pinrule's hooks fire automatically on every turn. That's a meaningful architectural difference. The README frames it bluntly: "Memory holds 'I prefer TypeScript'; pinrule enforces 'non-negotiable directions, hook-enforced.'" The trade-off is coverage versus nuance. pinrule can catch a bash sleep command or an intent to hardcode something, but it can't read underlying intent the way an LLM could. The maintainers acknowledge this openly, and ship regression tests for false positives and false negatives.

Scenario switching is handled through a single command. You type something like /pinrule I mainly do UX user research + interviews, switch to this scenario and the agent synthesizes a 5-7 rule pack from four signals: your local CLAUDE.md or AGENTS.md files, web search results for best practices, Andrej Karpathy's universal engineering baseline, and current session context. Two-phase confirmation and an atomic batch write follow. The README stresses that the agent does the research, not pinrule — the runtime stays strictly local.

The trade-offs

pinrule is lean on purpose. Zero runtime dependencies beyond Python's standard library, ~50-70ms hook latency, and ~2% token overhead in real usage. For a developer who wants deterministic guardrails without spinning up an LLM or paying for API calls per turn, that's compelling. The rule cap of 10 soft / 12 hard is drawn from Mnilax's study of CLAUDE.md effectiveness across 30 codebases — more than a dozen rules and models start pattern-matching "a rule list exists" without actually reading them.

On the flip side, regex-based enforcement will miss subtlety. The README documents known failure modes with test files you can run yourself: false positives around code literals and commit messages, false negatives when an agent disguises a violation, and the risk that a silent "zero hits" result just means the pattern is too wide. The maintainers recommend cross-checking with pinrule audit on real session data. It's a guardrail, not a verdict engine. If you need deep semantic judgment, this isn't that tool.

What it ships with

  • Three supported clients: Claude, Codex, Cursor — backends are swappable via a HOWTO guide
  • 7 default dev-scenario rules shipped out of the box in data/rules.dev.example.json
  • /pinrule command with three dispatch paths: data dashboard, single-rule add/modify/remove, and scenario rule pack generation
  • 800+ unit tests, green on a 6-matrix CI across Ubuntu, macOS, Windows, Python 3.11 and 3.12
  • Hook lifecycle documentation covering per-hook configuration, violation logging, and the compact/resume cycle
  • Scenario rule synthesis pulling from local files, web search, Karpathy's CLAUDE.md baseline, and session context
  • Violations audit flagging suspected false positives at runtime

If you want to try it

The project requires Python 3.11 or newer and runs on Windows, macOS, and Linux. Installation is a single pip install plus an init step that auto-wires hooks for any detected client. The README walks through both an agent-assisted install path and a manual one, including Windows PATH caveats. Head to the GitHub repo for exact commands — the README covers OS-specific gotchas and the pinrule uninstall-hooks option for clean removal.

pinrule fits a narrow but real niche: developers running long sessions with Claude, Codex, or Cursor who want lightweight, deterministic enforcement of personal coding standards without an LLM or network call per turn. It's not a replacement for memory tools, but a complement that treats preferences as rules rather than facts. The source is on GitHub and the package is on PyPI.