pinrule 0.18.1

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) · 🇨🇳 中文

A universal AI behavior-rule runtime, with a dev-scenario preset and Agent-generated scenario packs. Pin your 5-10 most-important rules so your AI doesn't drift in long tasks.

The runtime is deterministic engineering: hook injection, regex detection, atomic rule library. The rule packs are content — pinrule ships a 7-rule dev preset, and your Agent generates packs for other scenarios on demand: /pinrule I mainly do X, switch to this scenario invokes the installed pinrule Agent skill, which composes the pack through your Agent's existing toolset (WebSearch / Read / etc.) and writes it through pinrule's atomic CLI.

pinrule runtime: zero LLM · zero network · zero runtime deps · ~50-70ms hook · ~2% token overhead in typical dogfood. Scenario generation: uses your Agent's existing reasoning + WebSearch / WebFetch / Read tools — not pinrule.

Performance numbers measured on author self-use — methodology in docs/EVALUATION.md.

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 (new in v0.17.1) — 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

Starting v0.17.1, pinrule isn't locked to dev scenarios. Whatever your work is, the Agent researches the matching rule pack:

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

The Agent synthesizes 4 signals:

Signal	Content
A. Your local rule files	~/.claude/CLAUDE.md / ~/.codex/AGENTS.md / project CLAUDE.md / .cursor/rules/*.mdc — preferences you've already written
B. Online best practices	WebSearch finds high-star GitHub repos for your domain / industry blogs / papers
H. Karpathy CLAUDE.md baseline	Cross-scenario principles (explicit failure / minimal abstraction / etc.)
S. Session context	What you're doing this session, vocabulary, domain

Two-phase flow: Phase 1 content preview (5-7 rules with source attribution) → you approve → Phase 2 mechanism config (keywords + engine check semantic mapping — e.g. read_before_write partially maps to "design before reading research", not semantic understanding of UX methodology) → you approve → atomic batch write + backup. Full walkthrough: SKILL.md Path B.

pinrule itself stays 0 runtime deps / 0 network / 0 LLM — all research happens in your Agent's existing toolset.

---

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.

• False positives happen. Table cells quoting a term, python -c literals, commit messages — all can hit. pinrule audit flags suspected false positives.
• False negatives happen. Regex can't tell if you're disguising a violation. pinrule assumes you're not cheating yourself.
• Zero hits after a fix doesn't prove the fix is correct. The pattern might just be too wide.

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)?

v0.17.1+: just 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