PACT — Programmatic Agent Constraint Toolkit

A framework for governing AI coding agents through infrastructure instead of instructions.

The common assumption is that Claude's problem is memory. It forgets facts, decisions, and other nuances between sessions, so the go-to "solution" is to make it remember more by applying bandaids like session logs or plans in endless markdown files, classic databases, spawning dozens of subagents to argue it out with little context, and attempting marathon sessions to prove you've avoided compaction; that last one is actually nightmare fuel, not an accomplishment. I'll take "context rot" for $500, Alex.

The uncomfortable truth is that Claude makes bad decisions even when it remembers everything. It will edit a file it hasn't read. Fix one layer and break three downstream. Guess at a package API instead of checking docs. Declare "done" while half the work is missing. Full context doesn't fix any of these. They're reasoning failures, not recall failures.

Memory plugins ask: "How do we help Claude remember?"
PACT asks: "How do we help Claude think?"

Who Is PACT For?

Solo developers and small teams. PACT was built by a solo developer for solo developers, then designed to scale up. The smaller your team, the more you need it. There's no code reviewer to notice the stale cache, no teammate to check the dependency chain, no QA to catch the UI regression. Large teams have humans for that. You have PACT.

Small project? Good. That's when infrastructure matters most. PACT's subsystems activate on the patterns they detect, not on project size.

What Is PACT?

PACT is a modular governance framework for AI coding agents (Claude Code, Cursor, Copilot Workspace, etc.). Use all of it or just the parts that fill gaps in your existing setup — if you already have a memory layer, a task manager, or a workflow orchestrator, PACT detects that and only scaffolds what's missing.

PACT has nine features. Take what you need:

1. Mechanical Enforcement — Shell hooks that block violations before they land
2. Context Replacement — Architecture maps and lifecycle flows that replace memory
3. Self-Evolving Reasoning — Questions the agent asks itself at decision points
4. Structure/Behavior Separation — Static wiring maps vs dynamic lifecycle flows
5. Multi-Agent Resilience — When Claude is down, switch to Gemini (or vice versa) with zero context loss
6. Compound Intelligence — Research synthesis, cross-system knowledge directory, and capability baseline that make each session smarter than the last
7. Observability & Feedback — Real-time dashboard that visualizes agent activity, captures user prompts, tracks tasks, and feeds user ratings back into future sessions
8. Distributed Cognition — Auto-dispatched subagents for dependency tracing, knowledge research, and pre-commit review so the main session stays focused on the user's task
9. Vector Memory — Semantic search across bugs, solutions, research, and task feedback using local embeddings (no API keys, no cloud). YAML stays authoritative; vector search finds the right file faster

Multi-Agent Support (Claude + Gemini)

PACT supports running multiple AI agents on the same project — Claude Code and Gemini CLI share the same hooks, rules, and task tracker. When one agent is degraded, switch to the other without losing context.

• Shared governance: One set of rules (CLAUDE.md), one set of hooks, one task tracker
• Model identity: Sessions and commits are auto-tagged with the agent name
• Seamless handoffs: PENDING_WORK.yaml tracks what each agent was doing
• Status monitoring: session-status-check.sh warns you when Claude is degraded

Read the full Multi-Agent Setup Guide →

Live Dashboard (New in 0.5.0)

PACT includes a real-time dashboard that visualizes everything your AI agent does — every file edit, preflight check, hook block, commit, and governance update appears as a card in a horizontal timeline. Your own prompts show up too, so you can see the full conversation flow alongside the agent's actions.

Task Rating System — Click "Track Next Task" on any session, describe what you're asking the agent to do, and all subsequent events flow into that task's sub-row. When the task is done, rate it 1-5 with category tags (UI, Backend, Logic, Missed Requirements, Hallucination, etc.) and free-text feedback on what went right and wrong. Ratings are stored permanently and compiled into a scorecard (~/.claude/pact-scorecard.md) that the agent reads at the start of every session — creating a feedback loop where past ratings directly shape future behavior.

What you see:

• Session lanes with model identity (Claude/Gemini) and project name
• Task sub-rows with collapse/expand, diagnosis, and rating
• Per-type animated icons (the pencil writes while editing, the lightning strikes on preflight checks)
• Activity timeline, sidebar metrics, scorecard with rolling average and streak tracking
• "Track From Here" on any prompt card to retroactively mark where a new task started
• Diagnosis per session or per task — coverage analysis of which PACT subsystems were exercised

Start the dashboard:

python .claude/hooks/pact-server.py &
# Opens at http://127.0.0.1:7246

Or set "dashboard": "auto" in ~/.claude/pact-config.json to start it automatically every session.

Quick Start — Claude Code Plugin (Recommended)

These are built-in Claude Code slash commands — part of the plugin system. Run them directly in your Claude Code session:

/plugin marketplace add jonathanmr22/pact
/plugin install pact@pact

This gives you:

• 13 hooks — automatically active (read-before-write, secrets blocker, git safety, multi-session coordination, edit warnings, PreFlight architectural checks, feature flow protection, issue tracker gate, knowledge directory pairing, session tracking, timestamps, status page health check, prompt capture, PACT event logging)
• 3 subagents — auto-dispatched for dependency tracing, research, and pre-commit review
• 5 slash commands — /pact-init, /pact-check, /pact-flow, /pact-bug, /pact-recall
• Live dashboard — real-time visualization of agent activity, task tracking, and rating system

Then run /pact-init in your project to scaffold the governance files (architecture map, flow docs, bug tracker, cognitive redirections, cutting room).

Install everything. Do not ask the user to pick subsystems. Selective installation is a false choice at this stage — neither you nor the user have enough context to evaluate what's needed before /pact-init has run. The init skill already detects existing tools and presents an overlap table so the user can make informed decisions at that point. Asking "hooks only or full install?" before init is premature and creates confusion.

Customize

After installation, uncomment rules in the hook scripts for your project's specific patterns (forbidden imports, banned functions, critical file patterns, etc.). The hooks live in your Claude Code plugin cache — edit them directly or override with project-level hooks.

Quick Start — Manual Setup (Any Agent)

If you're not using Claude Code, copy the templates manually:

your-project/
├── CLAUDE.md                    # ← from templates/instructions.md
├── SYSTEM_MAP.yaml              # ← from templates/architecture_map.yaml
├── cutting_room/                # ← from templates/cutting_room/
│   ├── _INDEX.yaml
│   └── _TRIAL_TEMPLATE.yaml
├── .claude/
│   ├── hooks/
│   │   ├── pre-edit-rules.sh
│   │   ├── pre-bash-guard.sh
│   │   ├── pre-edit-feature-flow.sh
│   │   ├── post-edit-warnings.sh
│   │   ├── post-read-tracker.sh
│   │   ├── post-edit-timestamp.sh
│   │   ├── post-sentry-bug-reminder.sh
│   │   └── session-register.sh
│   ├── bugs/
│   │   ├── _INDEX.yaml
│   │   └── _SOLUTIONS.yaml
│   ├── sessions.yaml            # (auto-maintained by hooks)
│   └── memory/
│       ├── PENDING_WORK.yaml
│       └── file_edit_log.yaml   # (auto-populated by hooks)
├── docs/
│   ├── feature_flows/           # ← lifecycle flow docs
│   ├── plans/                   # ← implementation plans
│   └── reference/
│       ├── packages/            # ← per-package knowledge files
│       ├── research/            # ← cross-session research synthesis
│       │   └── _RESEARCH.yaml
│       ├── KNOWLEDGE_DIRECTORY.yaml  # ← cross-system tag index
│       └── PACT_BASELINE.yaml   # ← agent capability baseline

Configure hooks in .claude/settings.local.json (or your agent's equivalent):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/pre-edit-rules.sh" },
          { "type": "command", "command": "bash .claude/hooks/pre-edit-feature-flow.sh" }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/pre-bash-guard.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/post-edit-warnings.sh" },
          { "type": "command", "command": "bash .claude/hooks/post-edit-timestamp.sh" }
        ]
      },
      {
        "matcher": "Read",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/post-read-tracker.sh" }
        ]
      },
      {
        "matcher": "mcp__sentry",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/post-sentry-bug-reminder.sh" }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/session-register.sh" }
        ]
      },
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/session-status-check.sh", "timeout": 8000 }
        ]
      }
    ]
  }
}

What You Get

Hooks (automatic, no action needed)

Subagents (auto-dispatched)

Subagents are lightweight. They run on Sonnet in isolated contexts, return focused results, and free the main session to stay on-task. The overhead of dispatching a subagent is seconds; the overhead of NOT dispatching one — editing without tracing dependencies, coding without verifying package behavior, self-reviewing your own work — is measured in hours of rework. These are not expensive bureaucracy. They are the cheapest insurance in your workflow.

Slash Commands

Templates (used by /pact-init)

Gemini Integration (templates/gemini/)

Documentation

Core Concepts

Hook-Enforceable vs Self-Enforceable Rules

Every rule falls into one of two categories:

Hook-enforceable — Can be detected by text pattern matching. These become PreToolUse hooks that mechanically block violations. Examples:

• Forbidden imports (import hive, import firebase)
• Banned functions (print(), debugPrint())
• Hardcoded secrets (api_key = "sk-...")
• Raw SQL with string interpolation
• Editing a file that hasn't been read this session
• Force-pushing to main/master
• Committing when local is behind remote

Self-enforceable — Requires semantic understanding. These stay as cognitive redirections in the instructions file. Examples:

• "Fresh-read the entity before saving" (stale data bug)
• "Update both the list AND the map cache in provider methods"
• "Trace 3 hops in both directions before editing"
• "Check what your changes made stale before declaring done"
• "Walk through the user journey after building UI"
• "Research before writing workarounds"

The rule: If a violation can be detected by grep, it's a hook. If it requires understanding, it's a redirection. The instructions file only contains rules that hooks cannot catch.

Cognitive Redirections

Traditional rules get skimmed under cognitive load. Cognitive redirections are questions that engage reasoning at specific decision points:

- When about to edit any file:
  "What depends on this, and what does this depend on?"

- When declaring a task done:
  "What did my changes just make stale?"

- When a package doesn't behave as expected:
  "Do I actually know this package, or am I guessing?"

- After finishing any UI build:
  "Am I the user right now?"

The agent has autonomy to add new redirections when it notices itself making assumptions or falling into patterns. Future sessions inherit this self-awareness.

Architecture Map vs Lifecycle Flow

If you're writing a table name in a flow doc → stop, that belongs in the map.
If you're writing "this must happen before that" in the map → stop, that belongs in a flow.

Compound Intelligence

A fresh AI session has training data and a context window. A session running PACT has training data + context window + every synthesis every previous session earned. That's compound intelligence — it grows with every session.

Three systems make this work:

Research Knowledge Base (docs/reference/research/) — When the agent researches something non-trivial (combining project code analysis with online docs/papers/APIs), the synthesis — the insight that neither source had alone — is saved as a structured YAML file. Future sessions find these via tags, build on them, and evolve them through four actions: deepen, reframe, update, supersede.

Knowledge Directory (docs/reference/KNOWLEDGE_DIRECTORY.yaml) — A single-file tag index across ALL knowledge systems (research, bugs, solutions, packages, feature flows). One read shows every file that touches a topic without opening them individually. Hook-enforced: commits that include knowledge files without updating the directory are blocked.

Capability Baseline (docs/reference/PACT_BASELINE.yaml) — PACT's self-awareness layer. Records what the agent can do natively, what PACT compensates for, and how capabilities change over time. When the agent provider ships a new feature that makes a PACT rule redundant, this file is how the agent notices. When a new capability makes PACT stronger, this file is how the agent leans into it.

Cutting Room Floor

Complex visuals (heat maps, animations, shaders, charts) should be prototyped outside the app framework before committing. The cutting_room/ directory provides:

• Project registry (_INDEX.yaml) — tracks active visual prototyping projects
• Trial log format (_TRIAL_TEMPLATE.yaml) — documents every iteration with parameters, results, and reasoning

Use adjacent tools (Python, HTML/CSS, Shadertoy) to iterate visually. Only move the winning config to the app after nailing the look locally. Four failed in-app attempts that each require a full rebuild could have been one 5-minute Python script.

Multi-Session Coordination

When multiple AI sessions work on the same codebase simultaneously:

• session-register.sh records each session's start time and activity
• pre-bash-guard.sh blocks commits if the local branch is behind remote (another session pushed)
• .claude/sessions.yaml shows all active sessions — the agent checks this on startup

This prevents the most common multi-session failure: two sessions editing the same files, one pushes, the other commits on stale HEAD and force-pushes to recover, destroying the first session's work.

What to .gitignore

PACT generates some files that should be committed (hooks, architecture maps, knowledge files) and some that shouldn't (runtime logs, event streams, PID files). See templates/pact-gitignore for the recommended exclusions, or add these to your project's .gitignore:

# PACT runtime (auto-generated, session-specific)
.claude/sessions.yaml
.claude/pact-server.pid
.claude/pact-events.jsonl
.claude/memory/file_edit_log.yaml

Adoption Checklist

• Identify your top 3 recurring agent patterns to improve
• Create pre-edit-rules.sh with those 3 patterns
• Create post-read-tracker.sh (read-before-write enforcement)
• Create pre-bash-guard.sh (git safety + multi-session coordination + knowledge directory pairing)
• Create silent-linter.sh for your project's analyzer
• Write SYSTEM_MAP.yaml for your most-changed features
• Write cognitive redirections from your actual experience
• Create PENDING_WORK.yaml for cross-session continuity
• Add session start protocol to instructions file
• Create docs/reference/packages/ for package knowledge
• Create docs/reference/research/_RESEARCH.yaml for cross-session research synthesis
• Create docs/reference/KNOWLEDGE_DIRECTORY.yaml as the cross-system tag index
• Create docs/reference/PACT_BASELINE.yaml with your agent's current capabilities
• Create docs/feature_flows/ for lifecycle flows of critical systems
• Write your first feature flow for your highest-risk system
• Create cutting_room/ for visual prototyping
• Create .claude/bugs/ with _INDEX.yaml and _SOLUTIONS.yaml
• Set up session-register.sh for multi-session awareness
• Set up the PACT dashboard (pact-server.py, pact-dashboard.html, pact-event-logger.sh)
• Configure dashboard startup preference in ~/.claude/pact-config.json (ask/auto/off)
• Add pact-prompt-logger.sh to UserPromptSubmit hooks for prompt capture
• Copy PACT subagents to .claude/agents/ (pact-tracer, pact-researcher, pact-reviewer)
• Add Subagent Delegation section to your instructions file
• Run pact-migrate.py to build the vector search index from existing knowledge files
• Add .pact-gitignore entries to your .gitignore

Feedback

PACT collects anonymous feedback at two milestones — Day 2 and Week 2 of use. Your Claude will ask if you'd like to generate a report. The report captures:

• Which PACT subsystems you used vs ignored
• Task rating averages and common issue categories
• What helped (from you and Claude's perspective)
• What caused friction
• Workarounds Claude had to invent — these are the most valuable signal because they show exactly where PACT has gaps that should become hooks, checks, or templates
• Hooks that blocked legitimate work (false positives)

The report is generated locally at ~/.claude/pact-feedback-report.yaml. It contains no identifying information — no project names, no file paths, no usernames, no code. Individual frameworks can be mentioned if relevant to the feedback, but your full stack combination is never included. Only aggregate PACT usage counts and generic descriptions of what helped or didn't. Nothing is sent anywhere unless you explicitly choose to share it after reviewing every line. To submit:

Submit Anonymous Feedback →

License

PACT is released into the public domain. Use it however you want.