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, and delivers the right slice of memories, rules, and skills before the assistant takes its first action.

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 cares about two events.

• PreToolUse. Fires before the assistant uses a tool. The hook returns text that the client treats as system context for that call.
• UserPromptSubmit. Fires when the user sends a new prompt. The hook returns text that scopes the upcoming turn.

When you attach a workspace, the Pathrule runtime registers these hooks with your AI client. Claude Code, Cursor, and Codex CLI each get the config they expect.

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.

The whole flow is local. There is no network round trip in the hot path.

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.
• The matching rules with their priority.
• The memories and skills 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 attached to this scope.

If the hook had nothing relevant for the current path, it returns a small empty marker so the assistant knows Pathrule was consulted and chose silence.

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 the main reason teams report large drops in context tokens after moving from a global CLAUDE.md style file to Pathrule.

When nothing appears

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

pathrule doctor

It checks:

• The workspace attachment for the current directory.
• The local cache freshness.
• The MCP server status.
• The hook registration in your AI client config.

The output reports any step that needs attention with a one line fix suggestion.

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.