How hooks work

The hook supervisor is the part of Pathrule that makes AI sessions feel like the assistant already knew about your team's conventions. It runs locally, reads from a cache, delivers relevant memories and rules, and offers skills by name before the assistant takes its first action. A skill's instructions arrive when you invoke it.

This page is a user facing model of the mechanics. It is not a deep dive into the runtime internals.

What is a hook

A hook is a small script your AI client invokes at well defined moments in a turn. Pathrule uses the delivery and enforcement events Claude Code and Codex expose.

• SessionStart hands the assistant the workspace it is in, the Pathrule protocol and your team context, once per session.
• UserPromptSubmit scopes the upcoming turn.
• PreToolUse supplies path-scoped context and the strict-rule decision before an action.
• PostToolUse records outcomes, including failed tool calls.
• Stop and session-end events close out the turn. On Claude Code and Codex, a required check that a person has approved can hold the turn open here until its command has passed.

pathrule setup and pathrule sync, or the VS Code extension, register these hooks for Claude Code, and for Codex when the repository already has Codex files: an AGENTS.md, .codex/hooks.json or .codex/config.toml. Cursor, Windsurf and GitHub Copilot get no Pathrule hooks. They reach the same knowledge through the local MCP server when the agent calls its tools.

Client delivery profiles

A strict rule is one that carries a block pattern a person has approved. See Rules as guardrails for what blocks and what only informs.

What the hook does

The hook supervisor does four things in order.

1. Resolve the path. It maps the working directory to a workspace node.
2. Read the cache. The local cache holds a precomputed index of memories, rules, and skills for that path.
3. Shape the slice. It picks a depth that fits the intent. A UI tweak gets a minimal payload. A bug fix or refactor gets a focused one. Discovery prompts unlock a deeper one.
4. Return the payload. The text comes back to the client as system context for the upcoming action.

In local mode the whole flow runs on your machine. On a Cloud workspace, the prompt hook also sends the start of your prompt (roughly the first 1,000 characters) to Pathrule Cloud so knowledge can be ranked by meaning. If that call is slow or fails, the hook falls back to matching against this machine's cached index of the same workspace, so a network problem does not leave the turn without context. A Cloud folder is never served from a Local workspace.

What you see

The assistant's context surface (the one your editor exposes) gains a Pathrule section. It lists:

• The path the hook resolved to, plus the paths the work is most likely in, a route the assistant is asked to open before it searches. Pathrule records whether it did.
• The matching rules with their priority.
• The memories most relevant to your prompt, delivered as full bodies the assistant can act on directly. Less certain matches still come through as titles with ids you can read in full if you want.
• The skills that fit this scope, by name, ready to invoke with ::skill-name.

If the hook has nothing new and relevant for the current path, it adds nothing, so a quiet turn costs no context.

Two delivery channels

Knowledge reaches the assistant through two hook channels with different jobs.

• The per-prompt channel runs once when you submit a prompt, on clients with a prompt-submit hook (Claude Code and Codex). It is where the depth lives: the rules that fit the prompt, the strongest matching memories as full bodies the assistant can act on directly, and the skills that look relevant, offered by name. A skill is a procedure, so it is never pushed as an instruction; its full body arrives when you invoke it with ::skill-name.
• The per-tool-call channel runs before or after each file or shell action, many times per turn. It stays deliberately light: the names and one-line summaries of the rules and memories that apply to the path being touched, so the assistant knows what exists there and can read a body with one call if it needs it.

On Claude Code and Codex the prompt channel and the pre-tool channel both reach the assistant.

Neither channel repeats itself. A body already delivered in the session stays silent, and an edited one comes through again the next time it matters.

What stays on disk

When the Pathrule hook is installed, Claude Code and Codex get the protocol and team context from the session-start hook instead of from an instruction file. On Claude Code the session-start context joins the system prompt, so it survives conversation compaction, and the knowledge Claude Code loads by path sits in .claude/rules/pathrule/, one file per area. Codex's AGENTS.md keeps only a short Pathrule note. Pathrule removes the protocol copies and per-directory knowledge files it wrote in earlier versions. Your own content in those files stays.

Two cases keep the compiled files:

• Claude Code or Codex without its Pathrule hook installed keeps the full protocol and the path knowledge files, because nothing else would deliver them.
• If an earlier Pathrule version moved your own instruction file into a backup that has not been restored yet, Pathrule keeps the full file until that backup is dealt with, so you never look at a short note while your own instructions sit elsewhere.

To keep the compiled files even with the hook installed, set PATHRULE_SIGNATURE_MODE=off in the environment of the Pathrule runtime.

When the hook is not enough

Hooks are designed for the common case. The assistant can always reach for the MCP tools when it needs more.

• For discovery prompts ("list everything we know about billing"), the assistant calls pathrule_get_context directly.
• For full memory bodies, the assistant calls pathrule_read_memory with the id surfaced in the hook.
• For writes (the user asks to save a convention or a rule), the assistant uses the corresponding write tool.

The hook is the fast path. MCP is the deep path. Both share the same source of truth.

Path scope keeps it small

The hook returns a slice that is shaped by the working directory.

• A change in apps/web/dashboard does not pull in rules about database migrations.
• A change in services/billing/webhooks pulls in the billing rules and the webhook replay skill, not the marketing site conventions.
• A discovery prompt at the repo root pulls in a workspace overview, not every body.

Path scope is what keeps the delivered context small compared with a single global instruction file that every session loads in full.

When nothing appears

If you open a session and the Pathrule section is empty, run the doctor.

pathrule doctor

It is read-only and checks:

• Which edition serves the folder and why, the device default and the workspace.
• In a Cloud folder, your sign-in and whether the current folder is attached to its workspace.
• Whether the Pathrule MCP entry is installed for each AI client.
• Which Pathrule-managed files are in the folder, and which Pathrule surface and version wrote them.

In a Cloud folder, the output ends with the next command to run when something needs attention. Add --json for the full report, which also covers the Node version and flags an MCP entry that points at a runtime that no longer exists.

To put the local pieces back in place, run:

pathrule sync

Sync keeps the hook script current, writes Claude Code's hook entry and files again, and Codex's in a repository with Codex files, and refreshes the local cache the hook reads. pathrule install <client> rewrites a stale MCP entry, and an agent connected with pathrule integrations gets its hooks and MCP entry back with pathrule integrations repair.

If you ever want every Pathrule hook off at once, create ~/.pathrule/kill-hooks. The next hook call passes straight through; remove the file to turn hooks back on.

What to read next

• MCP overview for the tool surface that backs the deep path.
• Core concepts for the data model the hook reads from.
• CLI install for installing the runtime that hosts the hook supervisor.