pinrule 0.18.3

Pin the 5-10 rules your AI must not drift from during long tasks — Claude / Codex / Cursor, pure engineering, zero LLM, zero runtime deps, ~50-70ms hook latency

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) + writes default rules to ~/.pinrule/. If you install a new client later, run pinrule install-hooks to wire it up.

Restart Claude / Codex / Cursor — 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.json<br/>5-10 core directions)]
    K[pinrule engine<br/>regex + counting]
    A[🤖 Agent<br/>Claude / Codex / Cursor]
    V[(violations.jsonl<br/>audit history)]

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

rules.json is the only thing you maintain. The engine reads it, injects at the right hook points, watches Agent traffic for drift — no retrieval, no scoring, no LLM in the loop.

---

Not just another AI memory tool

Tool category	What it stores	When it fires
Memory (mem0, Claude memory)	Facts about you (preferences, history, profile)	Agent chooses to query
pinrule	Behaviors you've articulated as long-term directions	Hooks fire automatically every prompt + every tool call

Use both. Memory holds "I prefer TypeScript"; pinrule enforces "non-negotiable directions, hook-enforced."

---

Performance

Runtime deps	0 (Python stdlib only — JSON, no third-party packages)
Rule count	7 default (dev-scenario preset) · soft cap 10 · hard cap 12 (load refused beyond)
Hook latency	~50-70ms typical (machine-bound; reproduce via scripts/measure_perf.py)
Token overhead	~2% of conversation context in real dogfood (methodology: docs/EVALUATION.md)
Tests	800+ unit tests, green on 6-matrix CI (ubuntu + macOS + Windows × Python 3.11 / 3.12)
Supported clients	Claude / Codex / Cursor — add a backend

---

/pinrule — one command, three jobs

You only need to remember one command — /pinrule. Based on the natural-language content you type, the pinrule skill auto-dispatches to one of three paths, guides your Agent through tone refinement, schema validation, and monitoring wiring, then writes to your rule library after your confirmation.

You type	Routes to	Wall time
/pinrule (no args)	Data dashboard — which engine checks fire most, real-vs-false-positive split	<1s (pure CLI, no LLM synthesis)
/pinrule <single rule>	Path A: add / modify / remove one rule — 7-step skill flow	~30s
/pinrule <scenario, switch to this>	Path B: scenario rule pack — synthesize 5-7 rules from 4 signals, two-phase confirm, atomic batch write	3-5 min

Path A: /pinrule When I say "done" I want test pass evidence attached → 30s end-to-end.

Path B: see next section.

---

Switch any work scenario in one line

Whatever your work is, your Agent researches the matching rule pack:

/pinrule I mainly do UX user research + interviews, switch to this scenario

The Agent synthesizes 4 signals into a 5-7 rule pack:

Signal	Content
A. Your local rule files	~/.claude/CLAUDE.md / ~/.codex/AGENTS.md / project CLAUDE.md / .cursor/rules/*.mdc
B. Online best practices	WebSearch finds high-star GitHub repos / industry blogs / papers
H. Karpathy CLAUDE.md baseline	Cross-scenario engineering principles
S. Session context	What you're working on right now

Two-phase approval (content → mechanism), then atomic batch write with backup. Full walkthrough: SKILL.md Path B.

Boundary: pinrule runtime does not call LLMs or the network. Your Agent does the scenario research; pinrule validates and runs the resulting rules locally.

---

Tried and rejected

Several ideas looked attractive but failed in practice. Recorded so the same paths don't get re-walked:

Tried	Why rejected
LLM auto-distilling new rules	Latency + noise. Hearing something once doesn't make it a long-term direction.
Retrieval / cosine recall	The pain is "persistence," not "recall" — 5-10 rules can be always-on.
More than 12 rules	LLMs pattern-match "a rule list exists" instead of reading it (Mnilax's 30-codebase study).
Reshipping as MCP server	Hooks are enforced; MCP tools are chosen. In long-session decay, the Agent drifts before it asks "what rules apply."

---

Honest tool boundaries

pinrule is regex + counting, not LLM semantic understanding. Each known failure mode has a regression test you can run yourself:

Failure mode	Evidence you can reproduce
False positives (table cells quoting a term, python -c literals, commit messages)	pytest tests/test_check_fp_fixes_v0_16_13.py — locks down 4 historical FP fixes (negation prefix, fenced code blocks, inline backticks, full-width punctuation). pinrule audit flags suspected FPs at runtime.
False negatives (Agent disguising a violation)	pytest tests/test_false_negative_regression.py — 30+ FN cases pinned. Regex can't read intent — pinrule assumes you're not cheating yourself.
Zero hits ≠ fix correct	Pattern may just be too wide. Cross-check with pinrule audit on real session data, not synthetic prompts.

Sits between git and a linter — signals, not verdicts.

---

FAQ

Nothing happens after install?

Run pinrule doctor — checks hook events, rule loading, session state.

Too many false positives?

pinrule audit shows triggers tagged "⚠️ possible false positive" — report via Issue. Disable a single rule: pinrule rule remove <id>, or edit ~/.pinrule/rules.json and remove its violation_keywords / violation_checks fields.

Custom rule sets for non-dev scenarios (writing / research / legal / UX)?

Say /pinrule I mainly do X scenario, switch to this. Agent synthesizes 5-7 rules from 4 signals (your local CLAUDE.md / AGENTS.md / .cursor/rules, online best practices via WebSearch, Karpathy baseline, session context), previews with source attribution, two-phase confirms, atomic batch write — 3-5 min end-to-end. See "Switch any work scenario" above.

How do I sync rules across devices?

Ask the Agent to copy ~/.pinrule/rules.json. Safe to sync: rules.json + config.json. Never sync: violations.jsonl, session-state/ (runtime data, per-device — cloud-synced folders can corrupt cross-device state).

Does this overlap with Karpathy's CLAUDE.md?

Complementary. Karpathy's 12 rules are universal coding principles (cross-user). pinrule's are personal preferences (per-user). Use both.

---

What Agents say after running pinrule

Claude (Opus 4.7): Like having a senior tech director reviewing every action in real time — tiring, but it delivers. Without pinrule, a lot more behavior-the-user-didn't-want would have shipped.

Codex (GPT 5.5): I noticed myself being "behaviorally nudged," but didn't strongly feel "blocked or interrupted."

— Matches pinrule's positioning: guardrails + background noise, speaking up only when you hit a rule.

---

Mental model

A rules file isn't a wishlist. It's a behavioral contract closing out failure modes you've actually observed. Each rule should answer: what error is this rule preventing?

The 7 default rules in data/rules.dev.example.json are pain points from self-use, not a template to copy verbatim. Keep what matches your own failure scenes, replace the rest via /pinrule <natural language>.

---

Documentation

• PRD.md — product requirements + scenario positioning
• ARCHITECTURE.md — hook protocol, 8 check implementations, sandbox model
• HOOK_CONFIGURATION_GUIDE.md — per-hook lifecycle + tunable thresholds
• EVALUATION.md — methodology behind performance numbers (hook latency, token overhead)
• CHANGELOG.md — release notes (grouped by minor version)
• CODEX_BACKEND.md — Codex backend ownership boundary
• CLAUDE.md — project charter for Claude collaboration

All bilingual (.md English + .zh.md Chinese).

Acknowledgments

• Andrej Karpathy's CLAUDE.md template — universal coding-principles companion to pinrule's personal preferences.
• Mnilax's 30-codebase 6-week CLAUDE.md study — pinrule's soft cap 10 / hard cap 12 comes from this.

Contributing

• Bugs / ideas: GitHub Issues
• Add a new AI client backend: HOWTO
• Scenario rule templates: PR to data/

License

MIT