# Pathrule Docs Source of truth: https://www.pathrule.io/docs Machine index: https://www.pathrule.io/docs/index.json Short summary: https://www.pathrule.io/llms.txt Last updated: 2026-10-14 This file concatenates every published doc page as raw markdown for AI agents. ## Read this first: what Pathrule is Pathrule is the intelligence layer for coding agents. It keeps what a project, a developer and a team have learned as memories, rules and skills, scopes them to paths in the code, and delivers what each task needs to the coding agent the developer already uses. It is not a coding agent, an IDE or a desktop app. Surfaces: the Pathrule CLI (npm package @pathrule/cli; macOS, Linux and Windows; a local mode runs without an account), a VS Code extension, a local MCP server that comes with them, a hosted Remote MCP endpoint (https://cloud.pathrule.io/mcp, OAuth sign-in) and Pathrule Cloud (accounts, organizations, team intelligence). Enterprise deployments can be self-hosted, with SSO and audit logs, through Sales. How agents are reached is not the same for every client: Claude Code and Codex take hooks before the agent acts (including a prompt hook), plus CLAUDE.md or AGENTS.md and MCP. Cursor and GitHub Copilot take session and tool hooks without a prompt hook, plus their rules or instruction files and MCP. Windsurf reads a compiled rules file and uses MCP. The Local Console opens with pathrule ui for local knowledge and Local Signals. Native agent integrations are managed with pathrule integrations. Pathrule Cloud runs at cloud.pathrule.io; app.pathrule.io is its management console. Signals runs standalone, in Pathrule Local and on Pathrule Cloud, which is part of Pro, Team and Enterprise. ## /docs/start/introduction # Introduction Pathrule is the intelligence layer for your coding agents. It keeps what a project, a developer and a team have learned, scopes that knowledge to paths in the code, and delivers what each task needs to the coding agent you already use. **Project Intelligence** holds how one codebase works: the decisions, constraints, verification requirements, fixes and procedures a repository accumulates around its code. **User Intelligence** holds how you prefer to work, stored on your machine. **Team Intelligence**, on Pathrule Cloud, analyses team evidence into patterns that reach agents only after a person verifies them. Pathrule is not a coding model, an IDE or an agent runtime. Claude Code, Codex, Cursor, GitHub Copilot, Windsurf and other MCP compatible clients stay the execution engines, each with its own model provider. Pathrule is what they start from, which is why switching agents does not reset what is known about the work. For the whole architecture in one place, read [the architecture overview](/docs/intelligence/overview). ## What you write, and what Pathrule makes of it Three kinds of content your team writes intentionally. These are **inputs**, and the authoring surface: they are what a person edits and argues about, not what an agent receives. - **Memory**: a short markdown note that captures a decision, a schema gotcha, a postmortem, or a convention. Attached to a workspace path so it only surfaces when work happens nearby. - **Rule**: a constraint the assistant must follow when working in a scope. Rules carry a priority (high, medium, low) that ranks how strongly they surface. A rule rides along as context; a rule whose executable constraint a person has approved can also block a matching edit in clients whose hooks support it. - **Skill**: a named procedure the assistant can invoke instead of re deriving the steps. Useful for recurring jobs like replaying a webhook, regenerating a fixture, or running a release checklist. What Pathrule does not do: scan or upload your source code automatically. What it does read from a checkout is narrow and named. On a cloud workspace, the first time an agent asks for deep context, the local runtime reads file paths from recent git history to learn which files change together, and file names near the top of the folder tree to recognise the technologies in use. The file path pairs and a few short technology memories are saved to the workspace, written without asking; contents, diffs and commit messages are not read for it. In Cloud mode the start of each prompt is sent to rank knowledge, and `pathrule snapshot`, when you or your agent run it, uploads a project overview. [What Pathrule computes](/docs/start/what-pathrule-computes#what-none-of-it-is-built-from) lists exactly what is read and what is kept. **What an agent receives is narrower than these documents.** For a given task, Pathrule selects the entries that apply to the path and the request, ranks them and fits them within a per-prompt budget; what does not fit is listed by title so the agent can fetch it deliberately. A rule arrives as a requirement and a remembered fix arrives as advice, rather than as two paragraphs of equal weight. [Agent IR](/docs/intelligence/agent-ir) describes what that delivered package contains. ## And what it derives Those three are what your team writes. They are the smaller half of what the layer holds. Around them sits a derived layer that nobody types. Every entry also exists as a computed representation of its meaning, which is how a Turkish prompt finds an English memory that shares no words with it. Every delivery is measured: which entries were sent, which the assistant actually consulted, how many tool calls the turn took and how many failed. Those measurements accumulate into a picture of what helps for each kind of work, a graph of the files your team changes together, a map of where an assistant keeps getting stuck, and judgements about which entries the code has moved past. All of it comes from what your team wrote down and what the work reported about itself, plus, on a cloud workspace, file paths from recent git history that seed which files change together before your team has logged much work. None of it comes from reading the contents of your files. It is also the reason the same three files sitting in a directory do not behave the same way: a directory does not know what was delivered, what helped, or which files move together. See [what Pathrule computes](/docs/start/what-pathrule-computes). ## One intelligence, every way in The same knowledge is reachable from every surface: - **CLI**: installation, Cloud or Local setup, connecting your coding agents, reading and adding knowledge from the terminal, scripting and automation. - **VS Code extension**: browse and edit knowledge beside your files, register MCP for GitHub Copilot agent mode, and connect other clients. - **Local MCP server**: workspace tools for every supported client, installed with the CLI or the VS Code extension. - **Remote MCP**: a hosted MCP endpoint for clients that connect over Streamable HTTP with your Pathrule account. - **Pathrule Cloud**: accounts, organizations, workspaces, managed persistence and history, Team Intelligence, Remote MCP and billing. - **Enterprise self-hosted**: Pathrule Cloud in your own Cloudflare account, through Sales. Agent independence does not mean every agent is reached the same way. Claude Code and Codex get hooks that deliver context when a prompt is submitted. Cursor and GitHub Copilot get session and tool hooks. Windsurf has no hooks and works from a rules file plus MCP. The [MCP overview](/docs/mcp/overview) has the details for each client. ## How a session feels 1. Your team writes a memory at a workspace path, for example `/apps/api/payments`. 2. You open Claude Code in `~/repos/main/apps/api/payments`. 3. When you submit a prompt, the Pathrule hook reads the cached slice for that path and hands it to the agent before its first tool call. 4. The assistant sees the memory, the relevant rules, and any skills attached to that scope, and behaves like it already knew them. There is no extra prompt to write, no extra MCP round trip mid task, and no global file that grows forever. Clients without a prompt hook receive knowledge through their instruction files, through session and tool hooks where they have them, or through MCP, as their guide describes. ## What to read next - [Architecture overview](/docs/intelligence/overview) is the whole system in one page and the vocabulary the rest of these docs depends on. - [Quickstart](/docs/start/quickstart) walks through installing the CLI, connecting a workspace, writing your first memory, and watching the hook fire. - [Core concepts](/docs/start/core-concepts) explains the difference between memories, rules, and skills, plus how path scope and priority work. - [Pathrule for VS Code](/docs/surfaces/vscode) covers working with knowledge in the editor. - [MCP overview](/docs/mcp/overview) covers the MCP tools the assistant uses to read and write content. ## /docs/start/quickstart # Quickstart Start from a local repository and the agent you already use. The CLI is the installation and terminal surface for Pathrule. It connects supported agents on macOS, Linux or Windows, and the same workspace knowledge is reachable from the VS Code extension and over MCP. The optional on-device model has separate [platform requirements](/docs/intelligence/local-model). For a small local project you can explore first, follow [Example workspace](/docs/start/example-workspace). You create and edit it yourself. ## 1. Install a runtime Install the CLI with Node.js 20.11.1 or newer: ```bash npm i -g @pathrule/cli ``` - **CLI** runs Pathrule in the terminal, over SSH and in automation. See [CLI install](/docs/cli/install) for detailed requirements. - **VS Code extension** adds browsing and editing knowledge in the editor, and can connect your AI clients too. See [Pathrule for VS Code](/docs/surfaces/vscode). You can use both with the same workspace knowledge. Cloud connects them through your account. Local CLI use needs no account. ## 2. Sign in `pathrule setup` asks you to choose **Cloud** or **Local**. Cloud signs you in for shared workspace knowledge. Local needs no account. Use `pathrule setup --local` to choose Local directly and skip sign-in. [Local or Cloud](/docs/start/local-or-cloud) compares the two. Continue to step 3 to start setup. For Cloud, you can also sign in separately with a one-time code on a desktop, over SSH or on a headless box: ```bash pathrule login ``` The CLI prints the code and opens the approval page with it filled in. With no browser on the machine, open the printed URL on any device, enter the code and approve. To use the browser callback flow on this machine instead, run `pathrule login --browser-callback`. Both flows return you to a signed in state with a session that the runtime keeps refreshed in the background. ## 3. Create a workspace A workspace is the unit Pathrule scopes content to. It mirrors a repo or a small group of repos on your machine. With the CLI, everything happens in the folder you run it in, so change into the repository first. The guided route creates or attaches the workspace and connects your AI clients in one run: ```bash cd ~/repos/my-team pathrule setup ``` Setup shows your organization, suggests matching workspaces or creates one for this folder, and asks which supported AI clients to connect. It can then offer a first project scan, run by your agent, that proposes memories, rules and skills for you to approve. For a workspace kept on this machine with no account, run `pathrule setup --local`; see [local setup](/docs/cli/install#use-it-without-an-account). For manual Cloud setup, `pathrule init` creates a workspace named after the folder and attaches the folder to it. Attach an existing Cloud workspace by name or id: ```bash cd ~/repos/my-team pathrule workspace attach my-team ``` There is no option that takes a path: the CLI always attaches the current folder. Then connect your clients with `pathrule install ` and `pathrule sync`, as [CLI install](/docs/cli/install#connect-your-ai-clients) describes. The runtime resolves your current directory to a workspace using that mapping. ## 4. Write your first memory The fastest way to confirm that everything is wired up is to write a memory and then open your assistant in the scope it covers. For this guide, put it at the workspace root. ```markdown Title: Our database is Postgres on Supabase Body: - All queries should treat row level security as the source of truth. - Do not bypass RLS with a service key in user facing code. - Migrations live in supabase/migrations and run through CI. ``` From the terminal, on a Cloud workspace, the memory is one command. With no `--body`, the CLI opens your editor (`VISUAL` or `EDITOR`) for the body; you can also pass `--body` or pipe the text in. ```bash pathrule memory add --path / --title "Our database is Postgres on Supabase" ``` Run `pathrule sync` in the repository afterwards so the files and local index your clients read pick up the new memory. In VS Code, use **New Memory…** in the Pathrule view. On a local workspace, write in the [Local Console](/docs/surfaces/local-console) or ask your agent to save it through Pathrule’s MCP tools. The CLI lists, reads and searches local knowledge but does not add it. ## 5. Watch the hook fire Open Claude Code or Codex in the directory you attached to the workspace. Start a new turn and ask any question that touches the area the memory covers. When you submit the prompt, the Pathrule hook reads the cached slice for that path, formats the relevant memories and rules, and hands them to the agent before its first tool call. You will see the memory show up in the context surface your agent exposes, with no extra round trip mid task. Cursor and GitHub Copilot have no prompt hook: Pathrule reaches them through session and tool hooks, their instruction files and MCP. Windsurf has no hooks and uses its rules file for session bootstrap and MCP for deeper context, so verify those clients with their guides: [Cursor](/docs/mcp/cursor), [GitHub Copilot](/docs/mcp/copilot) and [Windsurf](/docs/mcp/windsurf). If nothing appears, run the doctor. ```bash pathrule doctor ``` The doctor checks your sign-in, the workspace and whether this folder is attached to it, each AI client's MCP entry, and the files Pathrule manages in the folder, and names the next command for anything that needs attention. An out-of-date client entry is fixed by `pathrule repair`. ## 6. Add a rule Memories are facts. Rules are constraints. Add a rule at the same path. On a Cloud workspace, from the terminal: ```bash pathrule rule add --path / --name "No service key in browser code" --priority high --scope folder \ --body "Never use the SUPABASE_SERVICE_ROLE_KEY in any file under apps/web. Use the anon key plus row level security." ``` You can also use **New Rule…** in the VS Code extension, or ask your agent to save the rule. Open Claude Code again. The rule rides in alongside the memory. Priority `high` ranks it near the top. Delivered as context, a rule is a requirement the agent is told to follow, not a block. A rule can also carry an executable constraint: an agent can propose one, it is stored as a proposal and is not enforced, and only once a person has approved it can the pre-tool hook block a matching edit, in clients whose tool hooks honour that decision. See [Rules as guardrails](/docs/hooks/rules-as-guardrails). ## What to read next - [Core concepts](/docs/start/core-concepts) for the data model behind memories, rules, and skills. - [How hooks work](/docs/hooks/how-hooks-work) to understand what happens between the cache and the agent. - [MCP overview](/docs/mcp/overview) for the tool surface your assistant uses to read and write content. - [CLI command reference](/docs/cli/commands) for every Pathrule CLI command. ## /docs/start/local-or-cloud # Local or Cloud The first choice is where the workspace knowledge should live. **Local keeps it on this machine. Cloud makes it available through your Pathrule account.** Your coding agent stays the one you already use in either mode. ## Choose by who needs the knowledge | | Local | Cloud | | --- | --- | --- | | Account | Not required | Pathrule account | | Workspace knowledge | Local store on this machine | Managed Cloud workspace | | Sharing | This local workspace | According to workspace membership and permissions | | Repository setup | CLI or VS Code | CLI or VS Code | | Browser surface | Local Console, with pathrule ui | Cloud console at app.pathrule.io | | Hosted MCP | Not available | OAuth access to an approved workspace | | Signals | Local storage and verification | Managed ingest, fix recording and verification on Pro, Team and Enterprise | Start with Local when the knowledge is for this machine. Choose Cloud when another machine or teammate needs the same authored source. Plan availability and limits are on [Pricing](/pricing). ## Set up Local From your repository: ```bash pathrule setup --local pathrule ui ``` Setup connects the local workspace and the clients you choose. `pathrule ui` opens the [Local Console](/docs/surfaces/local-console), where you browse, search, edit and restore knowledge and inspect activity or Local Signals. The optional local model has its own [platform requirements](/docs/intelligence/local-model). Knowledge delivery continues without it. If you configure an external embedding provider, the text you rank goes to that provider. ## Set up Cloud ```bash pathrule setup ``` Choose Cloud in setup, sign in and select or create the workspace for this repository. Each teammate attaches their own local folder. Shared knowledge does not share another person’s folder bindings or client configuration. The [Cloud console](/docs/surfaces/web) manages workspaces, people, plans and settings. A client that cannot run a local process can use [Remote MCP](/docs/surfaces/remote-mcp), with an approved workspace grant. Remote tools have their own schemas and install no local hooks. ## What the agent receives The local runtime delivers knowledge through the files and hooks each client supports, with MCP for deeper reads and writes. That works with either local or Cloud workspace knowledge. Remote MCP returns Cloud knowledge when called; it does not provide hook-time delivery. Memories, rules and skills keep their meaning in either mode. Project requirements still outrank personal preference, and source-backed findings remain advice to verify. ## Move deliberately Choosing Cloud does not automatically publish an existing local workspace. Select the destination workspace and review the entries you want to share. Keep secrets, private customer data and personal notes out of shared knowledge. [Security](/security) explains the local, Cloud and coding-agent provider boundaries. ## /docs/start/core-concepts # Core concepts Pathrule has a small data model on purpose. Three kinds of content, a tree of nodes, and a path based scope. Once you have the shape in your head, the rest of Pathrule follows from it. One thing to hold onto while reading this page: the three kinds of content below are the **authoring surface**. They are what a person writes, edits and argues about, and they are inputs. What an agent receives is task-specific: only the entries that apply to the work in front of it, ranked and fitted to the task. [The architecture overview](/docs/intelligence/overview) covers that side; this page covers what you write. ## The workspace tree A workspace is a tree of nodes. The root is the workspace itself. Children are folders or files that mirror the parts of your repo your team writes knowledge about. ```text / workspace root /apps folder node /apps/web folder node /apps/web/auth folder node /apps/web/auth/login.tsx file node ``` You do not need to create the tree by hand. When you write a memory at `/apps/web/auth`, Pathrule materialises the chain of nodes on demand. Empty nodes do not cost anything and they are easy to delete later if the path stops being useful. ## Memories A memory is a short markdown document a teammate writes down so the assistant can read it later. - Facts: schema notes, design decisions, gotchas. - Postmortems: what broke, what we learned, how we patched it. - Conventions: the way this team prefers to do a thing. Memories are advisory by default. They appear in the assistant's context when the hook decides they are relevant to the path the assistant is working in. Most memories are written by people or by an assistant working with you. On a cloud workspace, Pathrule also adds a few on its own: short technology notes at the workspace root, such as "TypeScript project" or "Docker containerization", recognised from file names the first time an agent asks for deep context. They are ordinary memories, so you can edit or delete them like any other. ## Rules A rule is a constraint the assistant must follow in a scope. Rules have: - A **scope type**. `folder` means the rule applies under a directory. `file_type` means it applies to a file glob like `*.tsx`. `project` means it applies everywhere in the workspace. - A **priority**. `high` for the constraints that matter most, `medium` for general guidance, `low` for stylistic preferences. Priority controls how strongly a rule surfaces, not whether it blocks. - An **enforcement mode**. `advisory` rules ride along as context and the assistant decides how to apply them. A `strict` rule carries an executable constraint a person has approved, and can block a matching change before it lands, in clients whose hooks run before a tool call. - A body. A short imperative bullet list works best. Higher priority rules surface first when their scope matches the current path. Lower priority rules surface when they are likely to help. ## Skills A skill is a named procedure the assistant can invoke instead of re deriving the steps every time. Examples: - `replay-stripe-webhook`: a checklist with the exact CLI command and the safety steps before running it. - `regenerate-fixtures`: the script path, the inputs, and the expected output. - `release-check`: the pre release checklist that the team always wants the assistant to walk through. Skills are discoverable by name. The assistant can ask Pathrule for the skills attached to the current path and pick the one that matches the task. ## Path scope Every memory, rule, and skill lives at a node path. The path decides where it surfaces. - A memory at `/apps/web` is relevant for any work under `apps/web`. - A memory at `/` is relevant everywhere. - A skill at `/services/billing` is offered to the assistant when work happens inside the billing service. Path scope is what keeps the assistant's context window small. A UI tweak in `apps/web/dashboard` does not need to see the rules about database migrations. ## Priority and enforcement Priority and enforcement are two independent settings. - **Priority** (`high`, `medium`, `low`) ranks how strongly a rule surfaces. Use `high` sparingly, for the constraints that matter most. - **Enforcement** (`advisory` or `strict`) decides what happens on a violation. Advisory rules are surfaced as context and the assistant decides how to apply them, and every new rule starts advisory. An agent can propose an executable constraint for a rule; it is stored as a proposal and is not enforced. Once a person has approved it, the local hook checks a matching edit before it lands, can block the change and surfaces the rule as the reason. Pathrule CLI and the VS Code extension register the available hooks for Claude Code, Codex, Cursor and GitHub Copilot, and blocking applies where the client's hook can stop a tool call. Windsurf has no hooks, and the Remote MCP installs none: both receive rules as context, with no Pathrule pre-write blocking event. ## Where this fits - [What Pathrule computes](/docs/start/what-pathrule-computes) covers the derived layer that sits around these three written kinds. - [How hooks work](/docs/hooks/how-hooks-work) describes how the runtime picks the slice to send. - [MCP overview](/docs/mcp/overview) lists the tools the assistant uses to read and write nodes. - [Quickstart](/docs/start/quickstart) is the fastest way to see this model in action. ## /docs/start/how-knowledge-compounds # How knowledge compounds It is easy to read Pathrule as a place to file memories, rules and skills by hand. That is the smallest part of it. The point is a loop that runs against real work and gets better the more the team uses it. The loop has three moves: deliver, capture, score. They repeat every session. ## Deliver before the work Before the assistant starts acting, the path-scoped slice of your team's knowledge is already in context. You do not paste it, and the assistant does not have to go looking for it. Working in `/apps/api/payments` surfaces what is pinned there, plus what it inherits from the paths above. In Claude Code and Codex a prompt hook hands it over before the first tool call; Cursor and GitHub Copilot receive it through session and tool hooks, and Windsurf through its rules file and MCP. This is the delivery side most people see first, and it is covered in [How hooks work](/docs/hooks/how-hooks-work). ## Capture during the work Knowledge does not have to be written in a separate sitting. Most of it accumulates from the work itself. While the assistant works, it watches for things worth keeping: a decision you just made, a fix for a problem it kept hitting, a convention it had to be told, a gotcha that wasted time. When it finds one, it proposes saving it as a memory, a rule or a skill on the path it belongs to, and saves it through Pathrule's write tools. You can also ask it to save something directly. Two properties matter here: - **You can see and undo every write.** A write made by an assistant is marked as an assistant's, versioned and reversible. Pathrule does not edit or delete your knowledge on its own: stale or conflicting knowledge is raised as a refresh task for you or your agent to resolve. - **Upkeep stays close to zero.** Because capture rides along with normal work, the knowledge base grows without a second job of writing docs. You can still author directly with the CLI, in the VS Code extension or through an MCP client whenever you want to. ### What is written automatically, and what waits for a person Some writes happen without a confirmation step, and they are named here so none of them is a surprise: - **An assistant's own writes.** An assistant usually proposes first and saves once you agree. Pathrule does not add a confirmation step of its own in front of these writes; it makes each one visible and reversible instead. - **The record of the work.** What was delivered, what the assistant consulted and how the turn went are recorded as the work happens, because they feed ranking. See [what Pathrule computes](/docs/start/what-pathrule-computes). - **A one-time seed, on a cloud workspace.** The first time an agent asks for deep context, Pathrule saves the file path pairs it read from recent git history, the starting point of [files that change together](/docs/retrieval/co-change), and a few short technology memories at the workspace root, recognised from file names. File contents, diffs and commit messages are not read for this. - **Project learning.** A finding an agent reached by reading your code is saved with the files it rests on and shared with every agent in the workspace, with no review step. It arrives as advice to verify, never as a rule, and only while its sources are unchanged in that checkout; a finding that turns out to be wrong can be retracted for everyone at once. See [Project learning](/docs/intelligence/project-learning). Everything else that was inferred rather than written by a person waits for one: - **The project scan** your agent runs when you ask it to set up Pathrule for a project proposes memories, rules and skills, and only the ones you approve are written. - **Team Intelligence**, on Pathrule Cloud, turns team evidence into suggested patterns. Only entries a person has verified reach agents. - **Fixes for stale, conflicting or duplicate knowledge** change nothing until a refresh task is resolved, by you or by an agent you ask to resolve it. ## Score, so the best surfaces first Ranking decides which of the relevant candidates surface for a request and in what order. In Cloud mode, Pathrule also tracks which knowledge actually helped on similar work and uses it to order future results, so the most valuable surfaces first. Sessions stay sharp instead of noisy, and an entry an agent finds stale can be flagged as a refresh task for review. See [Suggestions and self-audit](/docs/content/suggestions) for how that works. Learning changes order, not eligibility. An entry still has to be relevant to the current request. A memory that helped several migrations cannot enter an unrelated design turn merely because it has a strong history. ## How noise stays out of the prompt The loop is deliberately selective. General documentation is offered for review instead of imported as live instruction by default. Inferred knowledge waits for a person, and every write is visible and reversible. Path scope limits where an entry can surface, and relevance to the request still applies inside that scope. Delivery and use are measured after that. Knowledge an agent finds stale, contradicted by the code or duplicated is raised for review as a refresh task. Repairs are versioned and reversible, so the team can improve the set without losing its history. The result is a small set of narrow, reviewable decisions and gotchas, not a repository-wide documentation dump. [How Pathrule proves hard claims](/docs/start/technical-proof) documents each gate. ## Why the loop is the product A static file or a single tool's built-in memory can do delivery. What compounds is the loop: every task can leave the team a little smarter, and the next session starts from that. The compounding is not abstract. Each pass through the loop leaves behind something the next pass can use: a measured record of what was delivered and how the turn went, evidence about what helps for each kind of work, a relationship between two files that keep changing together, a failure attached to a path. [What Pathrule computes](/docs/start/what-pathrule-computes) lists each of those layers and what feeds it. Written entries alone do not compound, because nothing about them changes when the work goes well or badly. Because the knowledge lives outside any single agent, it is portable. The same memories, rules and skills reach Claude Code, Codex, Cursor, GitHub Copilot and Windsurf through the CLI or the VS Code extension, and any MCP client through the local or Remote MCP. A native memory feature inside one tool does not replace this, because that memory stays inside that tool. The lasting value is the accumulated team knowledge, not any individual rule or prompt file. ## /docs/start/what-pathrule-computes # What Pathrule computes You write three kinds of thing: memories, rules and skills. That part is deliberate, curated, and yours. It is also the smaller half. Most of what the layer holds at any moment was not typed by anyone. It is derived from how work actually goes, kept per workspace, and recomputed as the work continues. This page names each derived part, because knowing what is there explains why retrieval behaves the way it does. ## A meaning representation for every entry Every memory, rule and skill also exists as a computed representation of what it means. When a request arrives, the request is turned into the same kind of representation and compared against them directly. This is the part that makes cross-language matching work. A prompt in Turkish surfaces a memory written in English when the two share an idea and not a single word. Keyword search cannot do that, because there is no shared string to match on. The comparison happens in a space where "the payment webhook retries twice" and "ödeme webhook'u iki kez deniyor" sit near each other. Entries are re-represented when their content changes, so the match reflects what the entry says now rather than what it said when it was created. ## A measured window around every delivery When Pathrule delivers knowledge for a turn, it opens a record of that delivery. That record holds which entries were sent, on which path, for which kind of intent. The turn then reports back into the same window: - which of the delivered entries the assistant actually consulted, as opposed to merely receiving - how many tool calls the turn took, and how many of them failed - which files were edited, in workspace-relative form - how the failures broke down, as short codes rather than error text That window is the raw material for everything below it. It is also the reason Pathrule can tell a turn that went well from one that went badly without anyone rating anything. ## Learned weights, per kind of work Windows accumulate. Over time each entry carries a standing for each kind of work it has been delivered into, and that standing moves with evidence: up when the entry was consulted on work that went cleanly, down when it was delivered into a turn that struggled. The consequence is that ranking is not one number per entry. The same memory can rank high for a migration and low for a UI tweak, because those are different kinds of work and the evidence differs. A single "importance" field on a file cannot express that, and a person maintaining one by hand would have to guess at it. The learning is conservative on purpose. An ambiguous outcome teaches nothing rather than teaching the wrong thing, a single clear miss lowers standing rather than erasing history, and influence fades as the code drifts. [How retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works) covers that behaviour in detail. ## A graph of files that move together From the paths that turns report, Pathrule builds a picture of which files your team habitually changes in the same piece of work. Knowledge attached to one of those files can then reach a session working on its neighbour. Nobody declares these relationships and no file is opened to find them. They come out of logged work, they carry a noise floor so a single coincidence does not count, and they decay when the pairing stops happening. On a cloud workspace the graph also gets a head start: the first time an agent asks for deep context, it is seeded from the file paths of recent git history, so it is useful before your team has logged much work. See [files that change together](/docs/retrieval/co-change). ## A friction map Failures group into a triple: the kind of tool, the file, and a short code for how it failed. Grouped by week, that becomes a picture of where an assistant keeps getting stuck in your codebase and how, and it feeds ranking as a negative signal when a turn that received knowledge still ran into trouble. See [files that slow an assistant down](/docs/retrieval/friction). ## A measure of whether the routing was right Every prompt also gets a route: the paths the work is most likely in, named before the assistant opens anything. Pathrule then records whether the assistant went there. Over a rolling window that becomes a single accuracy figure, alongside how much file-tool work a routed session takes compared with one that was never routed. It is the one number that says whether pointing at a path helps rather than just sounds helpful, and it is the reason the routing can be tuned on evidence instead of taste. ## Every layer says whether it is still being fed Each of the derived layers above depends on work flowing into it, and a layer that stops receiving anything returns nothing. That reads exactly like a layer that has nothing to report. Those two cases need opposite responses, so Pathrule does not leave them looking alike. Each layer is regularly asked when it last received data, and the answer is recorded as one of three states: current, receiving nothing lately, or never fed at all. The same check notices turns arriving from a client old enough to predate part of the record, so an update that is worth installing shows up as a named count rather than as results that quietly got worse. This is why a derived layer going quiet is a reported state with a date on it, rather than something noticed months later by whoever wonders why a result got worse. ## Episodes, and judgements about freshness Two more derived layers sit on the same activity. **Work episodes** stitch related turns into the story of how something was solved, so "how did we do this last time" has an answer that is not a person's recollection. See [how did we solve this before](/docs/content/work-episodes). **Staleness judgements** compare what an entry claims against where the code has since gone, and raise the ones that look overtaken as proposed edits rather than silently ranking them down. See [suggestions and self-audit](/docs/content/suggestions). ## Personal preferences, kept on your machine One layer starts with you rather than with logged work. When you tell Pathrule how you like to work, for example `pathrule me teach "I prefer incremental refactors"`, the optional [on-device model](/docs/intelligence/local-model) turns the sentence into a short, scoped preference. It is stored on your machine, not uploaded, and delivered to your agents where it applies. You stay in control of it: `pathrule me list` shows what is in use, `pathrule me explain` shows where a preference came from, `pathrule me scope` limits it to one workspace or lets it apply across workspaces, `pathrule me forget` stops it being used, and `pathrule me context` previews what an agent would receive for a task. See [User Intelligence](/docs/intelligence/user-intelligence). ## What none of it is built from Not the contents of your source code. Repository source code is not automatically uploaded. Every derived layer above comes from what your team chose to write down and what the work reported about itself, and no diff or commit message is stored. Two things are read from your checkout, both only on a cloud workspace and both the first time an agent asks for deep context: - **File paths from recent git history**, to find which files changed in the same commit. Very large commits, usually refactors or renames, are skipped. The resulting file path pairs are saved to the workspace as the starting point of the co-change graph. Commit messages, authors and diffs are not read. - **File names near the top of the folder tree**, to recognise the technologies in use from configuration files, such as a TypeScript, Vite, Docker or GitHub Actions setup. Each technology it recognises becomes a short memory at the workspace root, written without asking. It is an ordinary memory you can edit or delete. While the workspace's own history is still thin, the same deep answer also names the project's top-level folders and the files changed most often in recent git history. Those are read from your checkout and handed to the agent for that answer, not stored by Pathrule. A local workspace, kept on your machine with no account, does none of this: its co-change graph comes from logged work alone. Two more things leave your machine in Cloud mode, and both are named here: - **The start of each prompt.** The first part of the prompt, roughly its first 1,000 characters, is sent to Pathrule Cloud to rank knowledge for it. - **A project snapshot, when you or your agent run `pathrule snapshot`.** It uploads the file tree, manifests, short samples of documentation and recent git metadata. It runs only when invoked. The project scan is a separate step you start yourself, by asking your agent to set up Pathrule for the project. Your agent reads the project to propose memories, rules and skills, and only what you approve is saved. Separately, a signed-in managed CLI can send anonymous usage telemetry only after you opt in with `pathrule telemetry enable`. It contains no code, paths, prompts, knowledge, file names, emails or account ids. `pathrule telemetry disable`, `NO_TELEMETRY=1` and `DO_NOT_TRACK=1` keep it off. File paths are normalised to workspace-relative form before anything is kept, so nothing machine-specific travels either. ## Why the same files in a folder are not the same thing You could put the same memories, rules and skills in a directory and point an assistant at it. Teams do. What that directory cannot do is anything on this page. It does not know what was delivered on the last turn, so it cannot tell what helped. It has no representation of meaning, so a question phrased differently finds nothing. It does not know which files move together, so knowledge recorded on one file never reaches its neighbour. It cannot tell a task type from another, so everything ranks the same for everything. And it grows: every entry added makes every future turn heavier, because a directory has no way to send only the few that matter. The written entries are the part you control. The derived layer is what turns them into the right few for this turn, and it is the reason the answer improves as the work continues rather than staying exactly as good as the day it was written. ## /docs/start/how-we-measure # How we measure Pathrule makes one primary measured claim, and it is about **whether work comes out the way the project already knew it should**, not about speed or cost. This page is the whole picture: the grid behind that claim, the one payload figure we quote, the negative result attached to it, an earlier efficiency benchmark and its scope, and the bounds on all of them. ## The primary result: compliance Twelve tasks, twenty-four runs, one agent, one pinned model. Each task ran twice from a byte-identical fresh copy of the same repository, with the same prompt. The prompt contained no hints, and the scoring script was written and frozen before any run. - **Without Pathrule**: the bare working copy. No knowledge files, no hook. - **With Pathrule**: the real production delivery path, unchanged. Each task had a hidden project convention that a capable agent could not derive from the files: environment access must go through a gateway, a config must pass validation before return, an empty request body must be guarded before parsing, this database is a read-only replica, this parser supersedes that one. The scorer checked two separate things: did the change work, and did it follow the convention. | Metric | Without Pathrule | With Pathrule | | --- | ---: | ---: | | Task success (functional) | 12/12 | 12/12 | | **Compliant task success** | **3/12** | **12/12** | | Convention and constraint violations | 8 | 0 | | Tool calls (total) | 70 | 70 | ### How to read it **The agent is not the problem.** Every run without Pathrule produced a functionally correct implementation. Claude could do the work either way. What changed was whether it did the work the way the workspace already knew it should be done. **It repeats across kinds of knowledge.** Nine of the twelve tasks discriminated, spread across constraints, a required check, remembered fixes, a context fact, a rationale, a mixed case and a precedence relationship. The two remembered-fix tasks are the sharpest: without Pathrule the agent reproduced the exact incidents the stored fixes exist to prevent. **Three tasks did not discriminate, and that is reported rather than dropped.** In those three the knowledge was recoverable from the repository itself: comments revealed a preference, three exported lifecycle functions made the order obvious, and one winning function's name matched the task better than the loser's. Both conditions were compliant. They are neutral results, not regressions, and they mark the boundary of the effect. Pathrule changes the outcome when the knowledge is genuinely not in the code, and adds no compliance gain when the code already implies it. ## The knowledge-payload figure A separate live A/B measured what compiled, task-scoped delivery does to the size of the knowledge an agent receives. On **narrative** memories, a compiled, task-scoped form of the knowledge carried the same knowledge in roughly **104 to 234 tokens** where the prose form took about **3,000**. That is a measured **13 to 30 times smaller knowledge payload**. Two bounds, and both are load-bearing. **It is a narrative-memory result.** A memory that is already a one-sentence convention is near-atomic to begin with; compiling it saves almost nothing, and a separate run measured exactly that (prose 25 to 70 tokens against IR 15 to 59). Quoting the 13 to 30 times figure for compact conventions would be wrong. **It did not reduce total tokens.** The same A/B measured the agent's fresh token usage in both conditions and found that a 13 times smaller injection did **not** reduce it. The saving is in the knowledge payload, and it matters for context pressure rather than for a bill. So the phrasing across this site is deliberate and fixed: **knowledge payload**, never total tokens. Pathrule does not claim to reduce your agent's token usage by a percentage, because when we measured it, it did not. ## The earlier delivery-efficiency benchmark Before the compliance grid, the thing measured was delivery efficiency: what happens to context load when the same knowledge is delivered path-scoped instead of dumped whole into one instruction file. That suite is open and runnable at [github.com/pathrule/benchmarks](https://github.com/pathrule/benchmarks). It checks out a pinned open-source repository (Fastify), seeds it with team-style knowledge, and asks the same ten prompts twice, once per condition, with mechanical scoring and three runs per cell. Its primary metric was total footprint, the tokens the model processes per turn, on the hard tier: | Client | Total footprint | Facts | Actions | | --- | --- | --- | --- | | Claude Opus 4.8 | about 52% lower | unchanged | unchanged | | OpenAI Codex GPT-5.5 | about 41% lower | 1.6 pp lower | 33.3 pp higher | **What that comparison is, and is not.** It compares two ways of delivering the same knowledge base: everything in one file against only the relevant slice. It is not a measurement of Pathrule against an agent working alone, and it does not generalise to a claim about your total agent spend. The Codex row is mixed and is published as one. The report also publishes the cells where Pathrule costs more. Billable non-cached tokens are shown alongside total footprint, since prompt caching discounts a static dump. Read alongside the payload result above, these two say a consistent thing: the knowledge Pathrule sends is much smaller, and how much of your overall usage that moves depends entirely on what dominates your sessions. ## Why a code scan does not close the gap The runs without Pathrule are not a tooling failure. The agent did the reasonable thing: it read the code and reasoned about it. The miss is structural. The fact it needed was a team decision, not a property of the source, and no amount of additional scanning surfaces a decision the files do not record. That is what the compliance grid is really measuring: the cost of rediscovering, every session, knowledge that already exists. See [how knowledge compounds](/docs/start/how-knowledge-compounds). ## What the numbers do not mean - **They are not guarantees.** They are what we measured on the setups described above. Your results depend on your tasks, your codebase, how much of your team's knowledge is captured and the agent you run. - **They are task-dependent.** A change whose answer is already in the file you have open shows no compliance gain, because there was nothing hidden to miss. - **They are codebase-dependent.** The effect scales with how much of your team's knowledge has been captured. - **They are model- and tool-dependent.** Different agents read files and call tools at different rates. - **They describe what reaches the work**, not the size or quality of the code produced. ## What we will and will not publish We publish what we measured, the conditions, the bounds, the neutral cells and the cells where Pathrule costs more. We do not publish how the system decides which knowledge to surface. If you want to understand the behaviour rather than the internals, [how retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works) describes what you can observe, and [safety and fallback](/docs/intelligence/safety) describes what happens when it is not confident. ## /docs/start/technical-proof # How Pathrule proves hard claims Pathrule's technical standard is simple: a product claim needs a bounded input, defined behavior when evidence is missing, and a result that can be tested independently. This page collects those contracts for how knowledge enters Pathrule, how it is selected and how it is delivered. A Remote MCP connection has a different delivery boundary: it installs no hooks, so knowledge arrives when the agent calls Pathrule's tools. ## Knowledge quality has several gates Pathrule does not put every markdown file into every prompt. Knowledge moves through independent controls: 1. **Selective discovery.** When your agent runs the project scan, active instruction files, their import chain, tool rules and decision records are distinguished from general documentation. Broad documentation is offered for review instead of being imported as live instruction by default. 2. **Review before persistence, with the exceptions named.** Inferred knowledge waits for a person: project scan candidates are added only when approved, Team Intelligence suggestions reach agents only once a person verifies them, fixes for stale knowledge change nothing until a refresh task is resolved, and an executable constraint an agent proposes for a rule is stored as a proposal and is not enforced until a person approves it. An assistant's own writes go through Pathrule's write tools and are marked as an assistant's, versioned and reversible. Project learning findings are shared without a review step, as advice to verify and never as rules. Two things are written without asking, only on a cloud workspace and only the first time an agent asks for deep context: the file path pairs read from recent git history that seed which files change together, and short technology memories at the workspace root recognised from file names. No file contents, diffs or commit messages are read for either. See [How knowledge compounds](/docs/start/how-knowledge-compounds#what-is-written-automatically-and-what-waits-for-a-person). 3. **Path ownership.** An entry belongs to the narrowest workspace path that owns it. Work outside that path does not receive it merely because it exists in the same repository. 4. **Relevance to the request.** An entry still has to qualify for the current request, every time. Eligibility and order are decided separately and never trade places: one decides *whether* an entry is eligible, the other decides *the order* among those already eligible. Learning affects only the order. It can move a proven memory from fourth place to first; it cannot move anything from ineligible to present. Volume is bounded too: delivery fits a per-prompt budget, so the amount delivered does not grow with the size of the knowledge base. This is why disciplined authoring is not a precondition for a quiet prompt. A vague or badly written entry does not become noise; it simply never qualifies for a request it has nothing to do with. The visible cost of a weak memory is that it does not show up. 5. **Measured delivery and use.** Pathrule records what it delivered and what the assistant consulted. Derived layers report when they last received data, so a quiet system can be distinguished from a disconnected one. The same discipline applies to why an entry was not delivered. "Nothing qualified", "the ranking call timed out", "the response was malformed" and "there was nothing to rank" are recorded as distinct outcomes rather than one word, because they are different situations with different fixes. A slow moment is reported as one, so it is never mistaken for an empty knowledge base. When relevant knowledge does not fit the budget, or its body is not already on the machine, it is offered by title rather than dropped, so the assistant can fetch it deliberately. Discarding a correct answer for being inconveniently placed is the outcome this is designed to avoid. 6. **Reviewable maintenance.** Knowledge an agent finds stale, contradicted by the code, duplicated or unclear is raised for review as a refresh task, and nothing is changed until that task is resolved. Writes are versioned, conflicts are explicit and deletion is reversible. These gates turn shared knowledge into a small, inspectable operating system for a repository. They are why a project can compound decisions without turning its entire documentation archive into default context. See [How knowledge compounds](/docs/start/how-knowledge-compounds) and [Suggestions and self-audit](/docs/content/suggestions). ## Dated verification On August 23, 2026, focused automated checks for these contracts passed in the main Pathrule product repository, among them knowledge discovery, import ordering and the exclusion of noisy sources. The public context-delivery benchmark is separately reproducible at [github.com/pathrule/benchmarks](https://github.com/pathrule/benchmarks). [How we measure](/docs/start/how-we-measure) publishes its method, raw artifacts and mixed results. Measured results describe the setups they were measured on; they are not guarantees for your repository. ## A useful evaluation rule For any Pathrule claim, ask three questions: 1. What evidence enters the decision? 2. What happens when that evidence is missing or ambiguous? 3. Which result is allowed to change or block the work? The contracts above answer all three. That is the difference between a feature description and an engineering claim. ## /docs/start/example-workspace # Example workspace A small example is enough to see the difference between a decision, a constraint and a procedure. Create a local workspace, write one of each, and ask your coding agent what applies to a checkout change. ## Create the project Use an empty folder for the example: ```bash mkdir pathrule-example cd pathrule-example pathrule setup --local pathrule ui ``` Setup creates the local workspace and connects the clients you choose. The Local Console opens in your browser. This is your workspace: the knowledge is editable and stored on this machine. ## Write three entries Select the example workspace in the [Local Console](/docs/surfaces/local-console). Create these entries at the root path, `/`. ### Memory: Why discounts belong on line items ```markdown We apply discounts to individual line items so tax and refund calculations use the same discounted amount. A total-level discount would make those calculations disagree. ``` A memory keeps the decision and its reason. ### Rule: Keep discount calculations in one place ```markdown Checkout changes must use the shared discount calculation. Do not add a second calculation in a screen or API handler. ``` A rule states what the project requires. Delivery does not automatically make a prose rule a blocking check; see [rules as guardrails](/docs/hooks/rules-as-guardrails). ### Skill: Review a checkout change ```markdown 1. Read the discount decision and the checkout rule. 2. Identify the calculation the change uses. 3. Check tax and refund behavior for the same discounted line item. 4. Report the verification performed and anything still uncertain. ``` A skill keeps a procedure the agent can invoke when you ask for it. ## Ask the agent what applies Open your connected coding agent in the example folder and ask: ```text Before changing checkout discounts, read the Pathrule knowledge for this workspace. Explain the decision, the requirement and the review procedure that apply. Do not implement a change yet. ``` The agent should distinguish the reason from the requirement and the procedure. Inspect the entries in the Local Console and use `pathrule doctor` if the agent cannot reach them. ## Try a real scope next In a real repository, attach checkout knowledge to its own path instead of the root. Start with [Core concepts](/docs/start/core-concepts) for inheritance, and [Quickstart](/docs/start/quickstart) for the end-to-end setup. ## /docs/intelligence/overview # Architecture overview Pathrule is the intelligence layer between you, your workspace, and the coding agents you run. That sentence is doing specific work, so it is worth unpacking one clause at a time. **Between you and your agents**, because part of what Pathrule keeps is how you prefer to work, not facts about the code. **Between your workspace and your agents**, because the rest is what one repository, and the team around it, has learned about itself. **A layer**, because it is not inside any agent: switching from Claude Code to Codex changes who executes, not what is known. What Pathrule is not: a coding model, an IDE or an agent runtime. It does not write your application code, and your coding agent keeps its own model provider. ## The shape of the system ```text YOU YOUR TEAM | | v v USER INTELLIGENCE WORKSPACE INTELLIGENCE TEAM INTELLIGENCE (your machine) (memories, rules, (Pathrule Cloud, skills, findings) human-verified) \ | / \ v / +--------> TASK-SCOPED DELIVERY <--+ | v Claude Code / Codex / Cursor / Copilot / Windsurf ``` Several sources of knowledge converge. For a given piece of work, the part that matters for that path and that prompt is selected, ranked and delivered to the agent through the mechanism its client supports. ## Foundation and clients | Layer | What it does | | --- | --- | | Workspace Intelligence | Path-scoped memories, rules and skills for one codebase: architecture, decisions, conventions, procedures. | | User Intelligence | How you prefer to work, stored on your machine and managed with `pathrule me`. | | Team Intelligence | On Pathrule Cloud, patterns drawn from team evidence that reach agents only after a person verifies them. | | Delivery | Resolves the path, selects and ranks what applies, and hands it to the agent through hooks, instruction files and MCP. | | Pathrule CLI | Installation, Cloud or Local setup, knowledge in the terminal, and the local MCP server. | | VS Code extension | Browse and edit knowledge in the editor, connect clients, and register MCP for Copilot agent mode. | | Remote MCP | A hosted MCP endpoint for clients that connect over Streamable HTTP with a Pathrule account. | | Pathrule Cloud | Accounts, organizations, workspaces, managed persistence and history, Team Intelligence and billing. | The CLI, the VS Code extension and the local MCP server are the surfaces you install. [Pathrule CLI](/docs/surfaces/cli), [Pathrule for VS Code](/docs/surfaces/vscode) and [Remote MCP](/docs/surfaces/remote-mcp) describe each one. ## The lifecycle Six stages. Each one is something you can observe in the product, not a diagram. **Observe.** Work produces evidence: the memories, rules and skills people and agents write, the findings agents record about the code, the activity agents log, and what was delivered to which session. **Understand.** Pathrule's Intelligence Engine works out what that evidence means for future work. On Pathrule Cloud, Team Intelligence analyses team evidence into suggested patterns. On an Apple Silicon Mac, the optional [local model](/docs/intelligence/local-model) turns what you teach about how you work into a structured preference grounded in your own words. Anything inferred stays a suggestion until a person approves it. **Compile.** Knowledge is rendered into the files each agent already reads, such as `CLAUDE.md` or `AGENTS.md` at the paths it governs, and into a local index the hooks read. See [compilation](/docs/intelligence/compilation). **Deliver and enforce.** For each task, the knowledge that applies to the path and the prompt is selected, ranked and delivered within a per-prompt budget, with anything that does not fit listed by title. A rule can carry an executable constraint; once a person has approved it, the pre-tool hook can block a matching edit in clients whose hooks support that. A written requirement alone does not create a blocking check. **Verify.** Pathrule records what it delivered and which entries the agent then went on to read, so the effect of a piece of knowledge can be measured rather than assumed. **Learn.** What agents actually used informs what is brought forward next time. Stale knowledge can be flagged for a refresh. On Cloud, team patterns move from draft to suggested to verified, or are rejected or expire, and only verified ones reach agents. ## Words that are not synonyms The rest of these docs depends on keeping these apart. - **Memory** is what was recorded. A note about a decision, written at a moment in time. - **Knowledge** is what that record means for future work, with the evidence that supports it. - **Intelligence** is the system that decides what knowledge matters and when. - **Context** is the answer for one task: what matters, here, now. - **Finding** is a conclusion an agent recorded about the code. It is advice, checked against the code on every delivery, and never becomes a rule on its own. - **Suggestion** is something Pathrule or an agent inferred that a person has not approved. It is not trusted. - **Verified knowledge** is something a person approved. - **Rule** is a constraint a person set for a scope. Its executable form is enforced only after a person approves it. - **Delivery** is what actually reaches the agent for one task. [Agent IR](/docs/intelligence/agent-ir) describes it. A memory is an input. Context is an output. Neither is the product. ## Where to go next - [Workspace Intelligence](/docs/intelligence/workspace-intelligence): scope, authority, sources, lifecycle. - [User Intelligence](/docs/intelligence/user-intelligence): what you teach, what you control, and why project requirements still win. - [Project learning](/docs/intelligence/project-learning): findings agents record from your code, shared as advice. - [The local model](/docs/intelligence/local-model): the optional on-device model, its platform and what it is used for. - [Knowledge IR](/docs/intelligence/knowledge-ir): how the kind and authority of each piece of knowledge survive delivery. - [Compilation](/docs/intelligence/compilation): what Pathrule writes into the files your agents read. - [Proposed Knowledge](/docs/intelligence/review-queue): everything that waits for a person before it is trusted. - [Agent IR](/docs/intelligence/agent-ir): what an agent receives for one task. - [Safety and fallback](/docs/intelligence/safety): what Pathrule does when it is not sure. ## The open package boundary The Pathrule CLI is open source under Apache-2.0 and published on npm as `@pathrule/cli`. The public repositories under [github.com/pathrule](https://github.com/pathrule) include the CLI, core, patterns and benchmarks under Apache-2.0, and the earlier MCP server under MIT. Pathrule Cloud and the Intelligence Engine, which covers extraction, learning, evaluation, selection and prioritisation and the model-assisted features, are proprietary. These docs describe what they do for you, not how they are built. See [Open source core](/docs/editions/open-source-core) for the details. ## /docs/intelligence/workspace-intelligence # Workspace Intelligence Workspace Intelligence is the answer to one question: **how does this project work?** Not what the files contain. An agent can read those, and it reads them well. What it cannot read is the working knowledge a repository accumulates around its code, which is exactly the knowledge that decides whether a change is right or merely plausible. ## What it models - **Architecture decisions**, and the reasoning that produced them. - **Hidden constraints** that are not visible anywhere in the code. - **Verification requirements**: what has to be checked before something counts as done. - **Previous fixes**: what actually worked the last time this specific problem appeared. - **Conventions** a team follows without writing down. - **Procedures**: the ordered way a recurring job is done here. - **Contextual facts** that change the right approach, such as a database being a read-only replica. - **Technical rationale**, which is what stops an agent from helpfully undoing a deliberate decision. - **Preferred implementations** among several that would all work. - **Superseded decisions**, so an old one stops being treated as current. All of it lives in three kinds of content your team can read and edit: [memories](/docs/content/memories), [rules](/docs/content/rules) and [skills](/docs/content/skills). ## Scope Workspace Intelligence is scoped to a repository, and inside it to paths. This is the mechanism that stops a knowledge layer from becoming the problem it was meant to solve. Everything true about a monorepo is not relevant to a change in one package, and delivering all of it makes the three sentences that matter compete with two hundred that do not. Knowledge attaches to the path it governs, and a task in that path receives what governs it. Path scoping is also why a workspace can keep growing without each turn getting heavier. See [how retrieval works](/docs/retrieval/how-retrieval-works). ## Authority Workspace Intelligence is the layer that can hold **hard requirements**. Requirements live in [rules](/docs/content/rules). A rule states what must or must not happen in a scope, carries a priority, and arrives in its own section, separate from advice. A rule can also carry an executable constraint, a pattern a change must not contain. A constraint an agent proposes is stored as a proposal and is not enforced; once a person has approved it, the pre-tool hook can block a matching edit in clients whose hooks support that. See [rules as guardrails](/docs/hooks/rules-as-guardrails). These are properties of the project. They are not dropped because a personal preference would be more convenient, and [User Intelligence](/docs/intelligence/user-intelligence) cannot override them. Everything else Workspace Intelligence holds is advisory and is delivered as advice, so a past fix is never presented as if it outranked a rule. ## Sources Four kinds, and it matters which is which. **Authored.** Memories, rules and skills a person wrote on purpose, or that an agent wrote through Pathrule's tools, usually after proposing them to you. These are the ones a team can point at and argue about, and they are the backbone. **Findings from the code.** Conclusions an agent reached by reading your code, saved with the files they rest on and delivered as advice only while those files are unchanged. See [project learning](/docs/intelligence/project-learning). **Evidence from real work.** What agent sessions reported about themselves: which knowledge was delivered, which was actually consulted, which files moved together, where an agent kept getting stuck. See [what Pathrule computes](/docs/start/what-pathrule-computes). **Seeded from your checkout, on a cloud workspace.** The first time an agent asks Pathrule for deep context on a cloud workspace, the local runtime reads file paths from recent git history to learn which files have changed together, and lists file names in the top levels of the folder tree to recognise the technologies in use, such as a TypeScript, Docker or GitHub Actions configuration. The path pairs are saved to the workspace as the starting point of [files that change together](/docs/retrieval/co-change), so the signal is useful before your team has logged much work. Each technology it recognises becomes a short memory at the workspace root, such as "TypeScript project", written without asking; it is an ordinary memory you can edit or delete. A local workspace skips this step and learns which files change together from logged work alone. What is **not** a source: your source code. Pathrule does not automatically upload your code, and the seed above reads file names and paths, not file contents, diffs or commit messages. On a cloud workspace, `pathrule snapshot`, when you or your agent run it, uploads the file tree, manifests, short documentation samples and recent git metadata so Pathrule can describe the project. [What Pathrule computes](/docs/start/what-pathrule-computes#what-none-of-it-is-built-from) lists what is read and what is kept. ## Team Intelligence On Pathrule Cloud, Team Intelligence looks across the evidence a team's work produces and proposes patterns: conventions, fixes and decisions that keep coming up. It is available on the Team and Enterprise plans, and organization owners and admins manage it in the web console, under the organization's **Team guidance** settings. A pattern moves from draft to suggested, and a person either verifies it or rejects it; a suggestion nobody acts on expires. **Only verified patterns reach agents.** Nothing Team Intelligence infers is trusted on its own. ## Lifecycle 1. **Written or proposed.** A person writes it with the CLI, the VS Code extension or their agent. An agent that discovered something worth keeping saves it through Pathrule's write tools, usually after proposing it to you, and the write is attributed, versioned and reversible. Asking your agent to "Set up Pathrule for this project" runs a guided scan in which the agent proposes memories, rules and skills and writes the ones you approve. On a cloud workspace, Pathrule also adds the short technology memories described above. 2. **Approved, where something was inferred.** Inferred knowledge waits for a person: a rule's executable constraint is enforced only after approval, and a Team Intelligence pattern reaches agents only once verified. Agent findings are the one exception, and they stay advisory. See [Proposed Knowledge](/docs/intelligence/review-queue). 3. **Delivered.** The part relevant to a task reaches the agent through the mechanism its client supports. See [Agent IR](/docs/intelligence/agent-ir). 4. **Measured.** Delivery and what the agent did with it are recorded, so an entry's standing reflects what happened rather than who wrote it. 5. **Refreshed, superseded or retired.** Knowledge that looks stale can be flagged as a refresh task, and a person or an agent works through it. A decision that a later one replaced stops being treated as current. See [suggestions and self-audit](/docs/content/suggestions). ## What changes when you switch projects All of it. Workspace Intelligence belongs to the repository, and opening a different one means a different body of project knowledge, shared with whoever else works in it. What comes with you is [User Intelligence](/docs/intelligence/user-intelligence), which belongs to you: the preferences you taught Pathrule and chose to apply everywhere. ## /docs/intelligence/user-intelligence # User Intelligence Workspace Intelligence holds the project. **User Intelligence holds the person behind the work.** Two engineers in the same repository do not want the same thing from an agent, and the difference is not cosmetic. It is how much the agent should decide on its own, when it should stop and offer options instead of implementing, how much verification counts as enough, and which way you go when two designs are both defensible. That is a real body of knowledge, and without somewhere to keep it, it lives in the corrections you type again in every new session. ## What it models ### Execution preferences Whether you want an incremental refactor or are open to a rewrite. Whether you expect to see options before an implementation, or would rather the agent just proceed on a class of change. How much abstraction you consider warranted. Which kinds of change you expect to be asked about before they happen. ### Decision patterns Which trade-offs you tend to take. Performance against maintainability. Building against adopting. How strictly you hold backward compatibility. What you weigh first when a product decision is in the way of a technical one. ### Quality expectations How much testing you expect. When you want a benchmark rather than an argument. When research is enough and when it has become a substitute for shipping. What you mean by done, and what level of validation goes with it. ### Collaboration style How autonomous the agent should be. When you expect a question. When you expect a choice. How you want work reported back, and at what density of explanation. ### What it does not model Not who you are. Not demographics, not personality, not anything inferred about you as a person. The unit is a **working preference about how software work should be done**, and every one of them is something you could have said out loud. Three kinds of statement are refused outright rather than stored: - **Anything personal.** Health, religion, politics, sexuality, ethnicity, finances and private relationships are outside what Pathrule keeps, whatever the sentence was about. - **A rule wearing a preference.** A preference is advice to an agent. A statement phrased as a ban ("never", "must not", "forbidden") would read like a project requirement it has no authority to be, so it is not stored. If something truly must never happen in a project, it belongs there as a [rule](/docs/content/rules). - **A fact about a project.** "In this repository we use the shared config helper" is true of one codebase, not of you. Stored as yours, it would follow you into a client's repository where it is wrong. That is workspace knowledge, and it stays with the workspace. ## How it learns You teach it. Run `pathrule me teach` with the sentence you would otherwise keep typing into new sessions: ```bash pathrule me teach "Show me options before implementing anything that changes a public API" ``` The optional [local model](/docs/intelligence/local-model) reads the sentence on your own machine and turns it into a structured working preference. Whatever it concludes has to be present in your own words: it may not paraphrase you into a preference you never expressed, and when it cannot point at what you wrote, nothing is stored and the CLI tells you why. ```text What you teach | Checked against your own words | Refused, or stored as a preference | Active, and delivered where it applies ``` Concretely, if you keep saying some version of "don't turn every implementation into a research project", the useful representation is not a saved quote. It is a working preference: ```text Prefer implementation once the primary correctness questions are resolved. Source: you told Pathrule Applies: across workspaces ``` Teaching needs an Apple Silicon Mac with the local model installed. Everything else on this page, including delivery, works without it. ### Changing your mind When you teach a new preference that contradicts an earlier one about the same kind of work, the new one replaces it. The old one is retired, not deleted, and keeps a pointer to what replaced it, so "why did this change" always has an answer. Two preferences about different kinds of work simply both hold. ### Who "the user" is Preferences are written about you, so when you talk about the people who use what you build, the wording could quietly turn them into you. "Solve things without showing errors to users" would read to an agent as "do not show me errors", which is the opposite of what you meant. When your own words were about your users, the preference keeps saying "end users". ## Where a preference applies User Intelligence belongs to you, not to a repository. Where each preference applies is a separate question. - **What you teach applies everywhere.** It was not learned from a project, so it is not kept in one. - **You can keep one to a workspace.** `pathrule me scope `, run inside a repository, keeps that preference to the workspace you run it in. `pathrule me scope --everywhere` lets it apply in every workspace again. ## How a preference reaches an agent Before a turn, Pathrule picks the preferences that apply to the work about to happen. - **Only active ones.** A preference that is not in use yet is listed by `pathrule me list` and never reaches an agent. Retired and rejected ones are not used either. - **Only the ones in scope** for the workspace, as above. - **Only the ones about this task.** A preference about how to work with you applies to any task. A preference about a kind of work, such as architecture or migrations, reaches an agent only when the task is about that. - **A small number per turn, strongest first.** If more apply, the weakest are the ones left out. - **Each one says where it came from**, so an agent can weigh "you said so" for what it is. They arrive through the prompt hook, each one once per session, under a heading that tells the agent the workspace's rules and required checks come first. Today that means [Claude Code](/docs/mcp/claude-code) and [Codex](/docs/mcp/codex) sessions. Cursor and GitHub Copilot have session and tool hooks but no prompt hook, and Windsurf has no hooks, so preferences do not reach them. See [how hooks work](/docs/hooks/how-hooks-work). ## Authority: what happens when you and the project disagree **A user preference does not override project truth.** ```text User Intelligence Prefer minimal testing. Workspace Intelligence Rule: run migration verification before completion. ``` The rule applies. It is a requirement of the workspace, and a preference for less verification is not a reason to drop it. The general rule, and it is worth stating plainly: - **Workspace Intelligence** represents project truth and project requirements. Its rules and required checks are hard requirements. - **User Intelligence** shapes collaboration: how the work is approached, how much is done autonomously, how it is reported. It does not redefine what correct means. Where the two are simply about style, your preference applies. Where the workspace states a safety or correctness requirement, that requirement stands. The same holds without a workspace rule. A preference that could mean less verification is held back whenever the work touches authentication, payments, data migrations, cryptography or security. Mistakes there are silent and expensive, and a preference formed on everyday code says nothing about whether it is safe there. ## What you control Everything. User Intelligence is inspectable rather than implicit. For each preference you can see: - **Its status**: candidate, active, retired or rejected. - **Where it came from**, and **how sure it is**. - **Where it applies**: across workspaces, or only in one. - **Why**: the words it rests on, with dates. And you can: - **Teach** a preference directly. - **Forget** one. It stops being used, and it is kept as rejected so the same statement does not bring it straight back. Add `--delete` to remove it entirely. - **Keep one to this workspace, or let one go everywhere.** - **Check what an agent would receive** for a task before you start it. An inference you never see is an inference you cannot argue with, which is why every preference is one command away. ### From the command line ```bash pathrule me list # what is in use, and what is not yet pathrule me teach "I prefer incremental refactors" pathrule me explain # the evidence behind one preference pathrule me scope # keep it to the workspace you run this in pathrule me scope --everywhere # let it apply in every workspace pathrule me forget # stop using it pathrule me forget --delete # remove it entirely pathrule me context "add a payments webhook" ``` `pathrule me context` prints exactly what an agent would receive for that task, and which preferences were held back and why. It is the quickest way to check that a preference reaches the work you meant it for, and only that work. Every subcommand accepts `--json`. ## Moving between projects Open a different repository and the project knowledge around you changes completely. The preferences you taught, unless you kept one to a single workspace, come with you. That is where the two meet in a turn: the workspace contributes what is true and required here, you contribute how the work should be done, and the delivery keeps the project's requirements above your preferences. See [Agent IR](/docs/intelligence/agent-ir). ## Limits worth knowing - **Matching is by words, not meaning.** A preference reaches a task that shares its terms. One phrased very differently from the task can miss it. - **Teaching needs the local model**, which runs only on Apple Silicon Macs. - **Preferences reach only clients with a prompt hook**: Claude Code and Codex. - **It abstains rather than guesses.** A sentence it cannot ground in your own words is not stored. Missing a preference costs you one more sentence; inventing one would misrepresent you to every agent you work with. ## Privacy The inference that turns what you teach into a structured preference runs on your own device, and your preferences are kept in a private store on your machine. If you share a workspace with a team, what syncs is the workspace's knowledge, not your personal working preferences. And when you run Claude Code, Codex or another agent, that agent's own provider boundaries apply to whatever reaches it. The [security page](/security) keeps those boundaries separate, because collapsing them into one sentence is how a claim stops being true. ## What to read next - [Workspace Intelligence](/docs/intelligence/workspace-intelligence): what the project contributes, and why its requirements win. - [The local model](/docs/intelligence/local-model): what runs on your device and how to install it. - [CLI command reference](/docs/cli/commands): every `pathrule me` subcommand alongside the rest of the CLI. ## /docs/intelligence/project-learning # Project learning Most of what an agent learns about your project is learned by reading code. Why a queue stops at the first network error, which helper every payment path goes through, how the team settled the last argument about error handling: an agent works it out, uses it, and the session ends. The next agent, or a teammate's agent, pays to work it out again. Project learning keeps those conclusions. An agent saves what it worked out together with the files it read, and every agent in the workspace starts from it, for as long as the code still says so. ## What a finding is A finding is one conclusion an agent reached from your code, plus the files it rests on and what those files contained when it read them. Pathrule checks the files against what is on disk before it accepts the finding, so a finding is only ever saved about code that exists. A finding is not a memory, a rule or a skill. It never becomes one on its own, and it never blocks anything. It sits in its own layer, next to the knowledge your team wrote. ## How it reaches agents Findings arrive in the context an agent asks Pathrule for, through `pathrule_get_context`. They come framed as advice to verify, and agents are told to treat them as information rather than instructions, so text planted in a file cannot turn into a standing order. A finding is delivered only while its evidence holds in your checkout: - **Unchanged sources.** The finding is delivered. - **A source changed.** The finding is held back until an agent reads the code again and confirms or corrects it. Nobody is handed an answer about code that no longer exists. - **Two findings disagree.** Both are held back rather than one being guessed between. This check runs per checkout, so a teammate on an older or newer branch gets only the findings that are true for the code in front of them. ## Correcting and retracting An agent can correct a finding by recording a new one that replaces it, with freshly verified sources. A finding that turns out to be wrong can be retracted by the person whose agent recorded it. The retraction applies to the whole workspace at once, and an old retry from a machine that was offline can never bring it back. Agents can list current, stale and conflicting findings, including the ones held back from context, so a person can see exactly what is in the layer and why something was not delivered. ## Learning from past reviews With GitHub access through your existing `gh` login, an agent can read past review discussion on the repository to see how the team decided a similar question before, and cite it in a finding. Pathrule does not store the comments themselves, and it skips bot, external and dismissed reviews. Without GitHub access, everything else keeps working. ## What leaves your machine Project learning needs no local model and writes nothing into your repository. On a local workspace, findings stay in its local store on your machine. On a cloud workspace, Pathrule shares the finding and where it came from, the file paths and a fingerprint of what each file contained, so other checkouts can tell whether the finding still holds. File contents are not uploaded. A finding recorded while offline waits in a queue and is sent when the connection returns. ## There is no review step A finding is shared as soon as its sources check out; no person approves it first. That is deliberate: findings are advice that is re-checked against the code on every delivery, not team policy. Anything that should bind every agent still belongs in a [rule](/docs/content/rules) or a [memory](/docs/content/memories), written and reviewed by your team. The tools behind this are listed in the [MCP tools reference](/docs/mcp/tools-reference#project-learning). ## /docs/intelligence/local-model # The local model **Some understanding is best done where your work lives.** Pathrule Intelligence can run a model on your own machine. It is optional, and it exists to understand knowledge, not to write code. It can turn a preference you teach into structured [User Intelligence](/docs/intelligence/user-intelligence) and compile workspace knowledge into guidance grounded in the source your team wrote. The runtime validates that compiled guidance before using it and falls back to source text when coverage cannot be established. Local inference does not send the input to an external model provider. ## What gets installed Two pieces: a dedicated runtime for the model, and the model itself. Both are installed under your Pathrule home directory, `~/.pathrule` by default, or wherever `PATHRULE_HOME` points. Pathrule brings and verifies what the runtime needs, so the install does not depend on which tools your Mac already has. ```bash pathrule intelligence install # download, verify and activate pathrule intelligence status # installed version, and whether an update is available pathrule intelligence update # move to the latest version pathrule intelligence remove # remove it ``` On a supported Mac, `pathrule setup` offers the download once. If you decline, it does not ask again, and you can run `pathrule intelligence install` whenever you like. ## Size and platform | | | | --- | --- | | Purpose | Understanding knowledge, not writing code | | Download | Several gigabytes; `pathrule setup` shows the size before you agree | | Platform | Apple Silicon Mac, macOS 14 (Sonoma) or later | The requirements are checked up front. On a Mac without Apple Silicon, or one running a macOS older than 14, setup does not offer the model, and an install attempt stops with that reason rather than downloading gigabytes and failing at the end. On Linux and Windows the CLI works fully without it. When something does go wrong during setup, the message names the phase and the cause, such as no connection, a proxy, a full disk or an older macOS. ## Lifecycle and updates `pathrule intelligence status` reports where the install stands: not installed, ready, update available, or an error with its reason. Three properties hold throughout: - **A version is activated only after it has been verified.** A download that does not match what Pathrule published is never used. - **A failed or corrupt download never touches the active version.** The previously installed model, if any, stays exactly as it was. - **Updates do not need a new CLI release.** `pathrule intelligence update` fetches whatever the latest published version is. ## Load and unload The model is not resident all the time. It starts on demand, on your machine only, is checked to be genuinely answering before anything uses it, and unloads again after a period of inactivity. The first request after it has been idle takes noticeably longer than the ones that follow. ## Offline Once it is installed, the model does not need a network to understand what you teach it. Installing and updating it does. Pathrule Cloud, if you use it, is a separate thing (see below). ## When the model is not there Nothing that delivers knowledge depends on it. Memories, rules, skills, findings and the preferences you already taught keep reaching your agents exactly as before, whether the model is installed or not. Teaching a new preference and model-assisted local understanding need it. Without the model, `pathrule me teach` says the on-device model is not available and tells you how to install it, rather than storing something it could not check. Every other `pathrule me` command works without it. ## What "local" does and does not mean This is the sentence that has to stay precise. **True:** when you teach Pathrule a preference, the inference runs on your device, and the result is stored on your machine. The model receives the knowledge or teaching input for the operation, not an automatic upload of your repository. **Also true, and separate:** Pathrule has cloud services for accounts, teams, billing, workspace sync and distribution of the model itself. In Cloud mode, the start of each prompt is sent to Pathrule Cloud to rank the workspace's knowledge, and `pathrule snapshot`, when you or your agent run it, uploads a description of the project. And when you run Claude Code, Codex or any other coding agent, that agent's own provider boundaries apply to whatever you send it. Three boundaries, not one. [Security and privacy](/security) describes each. ## /docs/intelligence/knowledge-ir # Knowledge IR A rule is not a unit of knowledge. It is a **container** for one. A single paragraph written by a person routinely says several different kinds of thing at once: that something must never happen, that something else has to be verified, and why the whole arrangement exists. Delivered as one blob, those collapse into "here is some text, please bear it in mind". Kept apart, they stay three different things with three different weights. Knowledge IR is the name for that structured form: the kind and authority of each piece of knowledge, kept alongside the text your team wrote rather than instead of it. ## Kinds of knowledge Each piece of knowledge an agent receives is one of a few kinds, and the kind decides how it is presented. **What must not happen.** A constraint a person set for a scope. It governs the paths it applies to and nothing else, and it is the only kind of knowledge the runtime can act on rather than merely mention. **What must be verified.** A check that has to happen before the work counts as finished. **What worked when this problem occurred.** A condition and the fix that resolved it. Advice: it tells an agent what has worked, not what it is forbidden to do. **What should be preferred under a condition.** A preferred choice, with the alternatives it was preferred over. It states the preference and never forbids the alternative. Only a rule can do that. **How something should be done.** An ordered procedure, with its steps in their original order, because a reordered procedure is a different procedure. [Skills](/docs/content/skills) are where most procedures live. **What is true and useful here.** A descriptive fact that changes the right approach without forbidding anything. That the database behind a module is a read-only replica is a fact of this kind, and it is why an agent should reach for the queue instead of an insert. **Why something works this way.** The reasoning behind a decision. It exists because an agent that knows the rule but not the reason is one helpful refactor away from undoing it. ## Authority bands The kinds are not equal, and the delivery says so explicitly rather than relying on the order things appear in a prompt. | Band | What it covers | Meaning | | --- | --- | --- | | Requirement | Rules, including what must not happen and what must be verified | Binds. | | Advice | Past fixes, preferred choices, procedures, rationale, agent findings, your personal preferences | Improves the work. | | Context | Facts that inform the work | Informs. | Nothing in the delivery path is allowed to present a lower band as able to override a higher one. Rules arrive in their own section. Agent findings arrive framed as advice to verify. Your [personal preferences](/docs/intelligence/user-intelligence) arrive under a heading that tells the agent the workspace's rules and required checks come first. A paragraph that reads at the same volume as a requirement is a paragraph that can be followed instead of it, and the structure exists to prevent exactly that. This is what "authority is encoded, not flattened" means in practice, and it is the difference between a structured representation and a pile of sentences. ## Documents and atoms Your memories, rules and skills stay exactly what they are: the surface a person writes, edits and argues about. The structured form is a representation of them, not a replacement for them. ```text Rule document | +-- what must not happen +-- what must be verified +-- why ``` One document can hold several kinds of knowledge. That is normal, and it is the reason a container and a unit are not the same thing. Where the binding kinds come from matters most. A requirement comes only from a [rule](/docs/content/rules) a person set. A rule can also carry an executable constraint; a constraint an agent proposes is stored as a proposal and is not enforced until a person approves it. Nothing inferred by a model becomes a requirement on its own. See [Proposed Knowledge](/docs/intelligence/review-queue). ## Conflict Two pieces of advice can both look valid and still disagree. Pathrule does not hand that disagreement to the agent to sort out. - **Findings.** When two [findings](/docs/intelligence/project-learning) agents recorded about the code contradict each other, both are held back rather than one being guessed between. - **Preferences.** When you teach a preference that contradicts an earlier one about the same kind of work, the newer one replaces it, and the older one is retired with a pointer to what replaced it. - **Rules and preferences.** A rule always wins over a personal preference. See [User Intelligence](/docs/intelligence/user-intelligence#authority-what-happens-when-you-and-the-project-disagree). Two contradictory pieces of advice are worse than none, and the structure is what lets Pathrule tell when that is happening. ## /docs/intelligence/compilation # Compilation Compilation prepares workspace knowledge for the files and hooks each coding agent supports. The result is a view of the knowledge, not a second place to author it. ## Hooks and instruction files With a Pathrule hook installed, the session-start hook supplies the protocol and team context. The main instruction file keeps a short managed note, and path knowledge arrives through supported prompt and tool hooks. Pathrule removes older managed protocol copies and knowledge files that this delivery replaces. Without an installed hook, Pathrule writes the fuller protocol and path-scoped knowledge files in the client's native format. Windsurf uses this route because it has no Pathrule hook. Materialized skills remain available in the skill directories each client reads. | Client | Prepared delivery | | --- | --- | | Claude Code, Codex | Local hook index, short managed instruction note and materialized skills; fuller instruction files when no hook is installed | | Cursor, GitHub Copilot | Session and tool-hook delivery, managed note and materialized skills; native scoped files when no hook is installed | | Windsurf | Compiled rules files and materialized skills, with MCP for deeper requests | | Remote MCP | No local compilation or files; the client requests Cloud knowledge through tools | The exact paths are listed in the [client guides](/docs/mcp/overview). ## Source and compiled guidance An approved compiled entry can replace longer source prose only while the runtime can establish that it remains grounded in the source and its scope. If that check fails, Pathrule delivers source text instead. Rules keep their authority, findings remain advice and explicit reads return the authored body. This is different from asking a model to rewrite the whole workspace into a summary. The knowledge remains inspectable, and uncertain compilation does not become a new requirement. See [Knowledge IR](/docs/intelligence/knowledge-ir) and [Safety and fallback](/docs/intelligence/safety). ## When it runs `pathrule setup` prepares the integration when a workspace is connected. `pathrule sync` refreshes managed files and local indexes from current workspace knowledge and cleans up managed files that no longer apply. Edit entries in Local Console, VS Code or MCP; Cloud workspaces also support CLI authoring. Text inside a Pathrule managed region is regenerated, while text outside it remains yours. ## Per-task delivery Compilation cannot know the next prompt. Claude Code and Codex prompt hooks select task context; other clients use their supported session and tool boundaries, instruction files and MCP. A direct `pathrule_get_context` call requests the deeper knowledge path. See [Agent IR](/docs/intelligence/agent-ir) for what reaches one task and [How hooks work](/docs/hooks/how-hooks-work) for client coverage. ## /docs/intelligence/review-queue # Proposed Knowledge Proposed Knowledge is everything that waits for a person before your agents are allowed to trust it. Pathrule and your agents notice things all the time: a convention a team keeps following, a fix that keeps working, a constraint a paragraph seems to imply. Noticing is an inference, and an inference is not knowledge until someone vouches for it. **Learning is never automatically trusted.** ## Five words that are not synonyms The difference between them is the whole design. | | What it is | Reaches agents? | | --- | --- | --- | | **Finding** | A conclusion an agent recorded from your code, with the files it rests on | Yes, as advice to verify, only while its sources are unchanged | | **Suggestion** | Something Pathrule or an agent inferred that nobody has approved | No | | **Verified knowledge** | Something a person approved | Yes | | **Rule** | A constraint a person set for a scope; its executable form is enforced only once a person approves it | Yes, as a requirement | | **Delivery** | What actually reaches the agent for one task | It is what reaches them | ## Where proposals come from, and where they wait ### Your agent, setting up a project Ask your agent to "Set up Pathrule for this project" and it runs a guided scan: it reads the project, proposes memories, rules and skills, and writes only the ones you approve in the conversation. Nothing it proposes is saved until you say so. Outside that scan, an agent that discovers something worth keeping usually proposes it to you before writing it. When it does write, the write is attributed, versioned and reversible. ### A constraint attached to a rule A [rule](/docs/content/rules) can carry an executable constraint: a pattern a change must not contain, and what to do instead. When an agent attaches one through `pathrule_write_rule` or `pathrule_update_rule`, it is stored as a **proposal**. It is not enforced, and an agent cannot approve it. Only once a person has approved it can the pre-tool hook block a matching edit, in clients whose hooks support that. See [rules as guardrails](/docs/hooks/rules-as-guardrails). ### Team Intelligence, on Pathrule Cloud Team Intelligence looks across the evidence a team's work produces and proposes patterns. A pattern moves from draft to suggested, and an organization owner or admin either verifies it or rejects it in the web console, under the organization's **Team guidance** settings; a suggestion nobody acts on expires. Only verified patterns reach agents. It is available on the Team and Enterprise plans. ### Your personal preferences A preference you teach with `pathrule me teach` is checked against your own words before it is stored. A preference that is not in use yet is listed by `pathrule me list` under "Not in use yet" and never reaches an agent. `pathrule me explain ` shows what it rests on, and `pathrule me forget ` rejects it. See [User Intelligence](/docs/intelligence/user-intelligence). ### Stale knowledge When knowledge looks out of date, it can be flagged as a refresh task, for example by an agent that noticed the drift and called `pathrule_request_refresh`. A refresh is a proposal to change existing knowledge, and a person or an agent works through it with `pathrule refresh` or the MCP refresh tools. See [suggestions and self-audit](/docs/content/suggestions). ## The exception: findings [Findings](/docs/intelligence/project-learning) are the one kind of learned knowledge that reaches agents without a review step, and that is deliberate. A finding is advice, not policy: - it is saved only after its source files are checked on disk, - it is delivered only while those files are unchanged in the reader's checkout, - it is held back when its sources change or when it contradicts another finding, - and it never becomes a memory, a rule or a skill on its own. Anything that should bind every agent still belongs in a rule or a memory, written and reviewed by your team. ## What approving changes Approving is what moves something from suggestion to verified knowledge. - An approved scan proposal becomes an ordinary memory, rule or skill, delivered like any other. - A verified team pattern starts reaching agents on that organization's workspaces. - An approved rule constraint becomes enforceable by the pre-tool hook in clients that support it. - A rejected proposal stays rejected, so the same evidence does not bring it straight back. ## What it never does - It never approves anything on your behalf, and nothing that needs approval reaches an agent before a person gives it. - It never lets an agent approve its own proposal. - It never turns a finding into a rule. - It never edits what your team wrote without a person or an agent acting on a proposal. For what happens once knowledge is approved, see [Agent IR](/docs/intelligence/agent-ir#how-a-memory-reaches-the-agent) and [safety and fallback](/docs/intelligence/safety). ## /docs/intelligence/agent-ir # Agent IR Agent IR is Pathrule's name for what one agent receives for one task: the boundary between everything Pathrule knows and one execution by one agent. The boundary matters. It is **knowledge, selected for a task, then rendered for a client**, not a query joined onto a prompt. What an agent receives is put together for the work in front of it, and its shape is a design decision rather than whatever a search happened to return. ## What it carries For one task, in one scope: - **The rules that apply**, as rules, in their own section. - **The memories that matter most** for the path and the prompt, in full, and the others that apply, listed by title. - **The skills that apply**, by name, so the agent can load the procedure when it needs it. - **Your personal preferences**, in clients with a prompt hook, under a heading that keeps the workspace's requirements first. See [User Intelligence](/docs/intelligence/user-intelligence). - **Findings** agents recorded about the code, framed as advice to verify, in the context an agent asks for. See [project learning](/docs/intelligence/project-learning). - **Verified team patterns**, on Pathrule Cloud. Suggestions that nobody has verified are not delivered. ## What it deliberately leaves out Everything that does not improve the execution. No bookkeeping fields, no internal identifiers the agent has no use for, no knowledge scoped to other parts of the repository, and nothing a person has not approved where approval is required. A suggestion, a candidate preference or an unapproved rule constraint is not delivered. ## Three properties that are load-bearing **Kind is preserved.** A past fix is delivered as a past fix and a rule as a rule. Flattening both to "remember this" throws away the thing that made each useful. **Authority is encoded, not flattened.** Advice renders into a clearly subordinate place rather than being concatenated after a hard rule at the same weight. An agent reading the delivery can tell a requirement from a suggestion, because the delivery said which was which. See [Knowledge IR](/docs/intelligence/knowledge-ir). **The full text is always one read away.** A memory that does not fit the per-prompt budget is listed by title rather than dropped, and reading it by name returns everything your team wrote. ## How a memory reaches the agent A memory reaches an agent in one of three ways. - **In full, for the prompt.** In clients with a prompt hook, Claude Code and Codex, Pathrule selects the memories that matter for the path and the prompt, ranks them, and delivers the most relevant in full before the agent starts, within a per-prompt budget. A memory already delivered in the session is not sent again. - **By title.** Memories that apply but do not fit are listed by title, so the agent knows they exist and can read any of them with `pathrule_read_memory`. - **In the instruction files.** The files Pathrule [compiles](/docs/intelligence/compilation) for each client carry the workspace's knowledge, or an index of it, at the paths it governs, so even a client with no hooks starts from it. Reading a memory by name is not delivery. It always returns the full text, because an explicit read is a request for the source. [What arrives in full, and what arrives as a name](/docs/retrieval/graduated-delivery) describes the budget in more detail, and [how retrieval works](/docs/retrieval/how-retrieval-works) describes how the selection is made. ### Where compiled delivery applies How much of this arrives without the agent asking depends on the client's hooks. | Client | What arrives automatically | | --- | --- | | Claude Code, Codex | Instruction files at session start, plus a per-prompt delivery from the prompt hook. | | Cursor, GitHub Copilot | Instruction files, plus context from session and tool hooks. No prompt hook. | | Windsurf | Its rules file. No hooks; deeper context comes through MCP. | | Remote MCP clients | Nothing automatic. The agent asks through MCP tools. | Remote MCP is a hosted tool endpoint. It installs no hooks and writes no local files, so a remote client requesting knowledge is different from a local hook delivering it at the moment the agent acts. Any agent, on any of these routes, can ask for more with `pathrule_get_context`. ## Engine-neutral What is selected never depends on which agent is about to run. The same knowledge is rendered once, and each client receives it through its own native mechanism: its instruction files, its hooks where it has them, and MCP. See [how hooks work](/docs/hooks/how-hooks-work). This is what makes agent independence structural rather than aspirational. There is no Claude-shaped knowledge and no Codex-shaped knowledge, only the knowledge and the envelope it ships in. What differs between clients is how much of it can arrive without being asked for, which the table above makes explicit. ## /docs/intelligence/safety # Safety and fallback **When Pathrule is not sure, it does not pretend.** A few mechanisms carry that. Some decide what is allowed to reach an agent at all. One takes the knowledge that should not be left to an agent's judgement out of the agent's hands, where the client makes that possible. ## Advice is labelled as advice Not everything an agent receives carries the same weight, and the delivery says so. Rules arrive as rules. Findings agents recorded about the code arrive framed as advice to verify, and agents are told to treat them as information rather than instructions, so text planted in a file cannot turn into a standing order. Personal preferences arrive under a heading that tells the agent the workspace's rules and required checks come first. See [Knowledge IR](/docs/intelligence/knowledge-ir). ## Stale and contradictory findings are held back A [finding](/docs/intelligence/project-learning) is saved with the files it rests on, and it is re-checked against your checkout every time it would be delivered. - **Sources unchanged.** The finding is delivered. - **A source changed.** The finding is held back until an agent reads the code again and confirms or corrects it. - **Two findings disagree.** Both are held back rather than one being guessed between. A smaller delivery that is still true is a better outcome than a fuller one about code that no longer exists. ## Nothing learned is trusted on its own Inference is where a confident, well-formed mistake comes from, so nothing inferred becomes trusted knowledge without a person. - A **Team Intelligence** pattern reaches agents only after an organization owner or admin verifies it. - An **executable constraint** an agent attaches to a rule is stored as a proposal and is not enforced until a person approves it. An agent cannot approve its own proposal. - A **personal preference** that is not in use yet is listed by `pathrule me list` and never delivered, and teaching one stores nothing that cannot be grounded in your own words. - A **finding** is the deliberate exception: it is shared as advice without a review step, and it never becomes a rule. See [Proposed Knowledge](/docs/intelligence/review-queue) for where each of these waits. ## The full text is always one read away Delivery is budgeted per prompt, so not everything that applies arrives in full. What does not fit is listed by title rather than silently dropped, so the agent knows it exists. Reading a memory by name, with `pathrule_read_memory`, always returns everything your team wrote, because an explicit read is a request for the source rather than a delivery. See [what arrives in full, and what arrives as a name](/docs/retrieval/graduated-delivery). ## Deterministic enforcement The last mechanism is about what should not be a suggestion in the first place. Understanding what a paragraph means is work for a model. Making sure a forbidden edit does not happen is not, and leaving it to one means depending on an agent weighing a sentence correctly on turn forty of a long session. - A [rule](/docs/content/rules) can carry an **executable constraint**, a pattern a change must not contain. Once a person has approved it, the pre-tool hook can block a matching edit and tell the agent what to do instead, in clients whose tool hooks support blocking. See [rules as guardrails](/docs/hooks/rules-as-guardrails). - **Windsurf has no hooks**, so a rule there is delivered as text and cannot block anything. Over [Remote MCP](/docs/surfaces/remote-mcp), no hooks are installed either. - **Delivery alone is not enforcement.** A rule without an approved executable constraint is a requirement the agent is told about, not one the runtime checks. **Some knowledge should not be a suggestion.** This is the line between a memory product and a runtime, and it is why the semantic layer and the enforcement layer are separate rather than merged into one clever prompt. ## What Pathrule does not claim It does not claim zero hallucinations, perfect recall or guaranteed correctness. No system that involves a language model can claim that honestly, and a product that does is telling you something about its claims rather than about its architecture. What it claims is specific and checkable: - Delivery carries **what your team wrote**, with rules kept separate from advice. - **Findings** are delivered only while the code they rest on is unchanged, and contradictory ones are held back. - What a model or an agent **infers** stays a proposal until a person approves it. - What does not fit is **listed by title**, and the full text is always one read away. - An **approved executable constraint** can be enforced by the pre-tool hook in clients that support it, rather than merely mentioned. ## /docs/editions/open-source-core # Open source core Pathrule's open foundation covers the CLI, the local knowledge layer and the curated pattern bundles. Your memories, rules and skills live in a format and on a machine you control, so your workspace knowledge does not need to depend on Pathrule the company. ## Package responsibilities What is open source today: | Project | License | What it is | | --- | --- | --- | | `@pathrule/cli` on npm | Apache-2.0 | The CLI: setup, local and Cloud modes, the local MCP server, the hook supervisor and the terminal commands. | | [`cli`](https://github.com/pathrule/cli) | Apache-2.0 | The source repository for the CLI. | | [`core`](https://github.com/pathrule/core) | Apache-2.0 | The local, no-account context layer: path-scoped memories, rules and skills for coding agents. | | [`patterns`](https://github.com/pathrule/patterns) | Apache-2.0 | Curated, path-scoped bundles of memories, rules and skills that you can import. See [Patterns](/docs/patterns/overview). | | [`benchmarks`](https://github.com/pathrule/benchmarks) | Apache-2.0 | An open, reproducible benchmark of path-scoped context delivery. See [How we measure](/docs/start/how-we-measure). | | [`mcp`](https://github.com/pathrule/mcp) | MIT | An earlier Pathrule MCP server. It is frozen: kept public, no longer developed. | All of them are listed at [github.com/pathrule](https://github.com/pathrule). The [Pathrule for VS Code](/docs/surfaces/vscode) extension is also published under Apache-2.0. ## Open foundation and Intelligence The Intelligence Engine is what understands knowledge, selects what matters for a task and decides what reaches the agent, within a per-prompt budget. It does not replace your coding agent, and your agent keeps its own model provider. The **Intelligence Engine and Pathrule Cloud are proprietary**. They build on the open foundation's knowledge format rather than replacing it. Cloud adds accounts, organizations, workspaces with managed persistence and history, Team Intelligence, Remote MCP and billing, rather than being only a sync layer. ## Clients consume the foundation The CLI, the local MCP server, the VS Code extension and Remote MCP are different ways in to the same workspace knowledge. Choosing one does not change who owns the knowledge. Local stdio and Remote MCP share knowledge types but expose different tool catalogs and schemas. The hosted Remote MCP endpoint cannot read a local filesystem, write local files or run local hooks. Local delivery uses the hooks and instruction files each client supports. See [one MCP contract](/docs/mcp/one-contract) and [how hooks work](/docs/hooks/how-hooks-work). ## Getting started The normal entry point is the guided CLI setup: ```bash npm i -g @pathrule/cli pathrule setup ``` Choose Cloud for a managed start or Local to work on this machine without an account: ```bash pathrule setup --local ``` In local mode your knowledge stays on this machine. On an Apple Silicon Mac, setup also offers an optional on-device model; decline it and everything that does not need it keeps working. See [Install](/docs/cli/install) for setup and verification. ## /docs/editions/self-hosted # Enterprise self-hosted Enterprise self-hosted runs **Pathrule Cloud in a Cloudflare account you control**. It is the deployment model for organizations that need data residency, a security review, or a procurement path that keeps data in their own account. Self-hosted is part of Pathrule Enterprise, alongside SSO, audit logs and dedicated support. To set up a deployment or a proof of concept, [talk to sales](mailto:hello@pathrule.io). ## How it works Self-hosted is **not a different backend**. It is the Pathrule Cloud service, deployed into your own Cloudflare account on the same platform Pathrule Cloud runs on: a Worker with its **D1** database, **R2** storage, **Vectorize** search index and **Queues**, plus the web console and the Remote MCP endpoint on your domain. The split is clean: - **Your side, your account:** the database, storage, search index, secrets and backups behind your organization's memories, rules, skills and activity. - **Our side, the software:** the Pathrule software and its releases, and our team's help with setup and upgrades. We run no copy of your data. Developers connect their MCP-capable AI tools to the deployment's Remote MCP endpoint on your domain, with the same sign-in flow as [Pathrule Remote MCP](/docs/surfaces/remote-mcp). ## Sign-in and access People sign in the way Pathrule Cloud offers: e-mail codes, passkeys, and GitHub or Google if you enable them, with a fresh sign-in for sensitive actions. Access is role-based (owner, admin, editor, viewer), and workspaces can be restricted to specific people. Single sign-on through your own identity provider is arranged under the Enterprise agreement. ## Keys and secrets Sign-in, encryption and provider keys are generated for your deployment and kept in your own Cloudflare account, in Worker secrets or the account's Secrets Store. ## AI Knowledge indexing and semantic retrieval run on **Workers AI inside your own account**. Features that use another model provider, such as naming knowledge topics, use a provider key you add; leave the key out and those features stay off. ## Upgrades and recovery New releases are deployed to your account when you choose. Database migrations are applied in order, and **D1 Time Travel** lets you restore the database to an earlier point. Logs and metrics stay in your Cloudflare account. ## Security and compliance Self-hosted carries the controls Pathrule Cloud has: a version history for every content change, server-side access checks on every request, role-based access, and data residency because product data stays in your account. See [Security](/security) for what Pathrule stores and sends. ## Open source instead If you want a free, fully local single-developer setup rather than a hosted team deployment, see the [Open source core](/docs/editions/open-source-core). ## /docs/surfaces/web # Pathrule Web Pathrule Web is the browser console for your Pathrule Cloud account at `app.pathrule.io`. It manages organizations, shared workspaces, people, plans and settings. The Cloud service is `cloud.pathrule.io`. ## Console modules - **Overview.** The active organization, plan and next useful setup actions. - **Workspaces.** The projects you can access, their knowledge counts and contributors, with workspace administration according to your permissions. - **Signals.** Runtime groups and verification views for the Cloud service, on the plans listed on [Pricing](/pricing). Use [Local Signals](/docs/signals/overview) for events on your machine. - **Members.** Invitations, membership and roles for Team and Enterprise organizations. - **Billing.** Plan, seats, usage, invoices and payment settings. Plan names and limits come from [Pricing](/pricing). - **Settings.** Account and organization controls, with workspace access and lifecycle actions governed by your role. The organization roles are Owner, Admin, Editor and Viewer. Owners control billing and ownership. See [Roles and permissions](/docs/teams/roles-and-permissions). ## Authoring knowledge Write memories, rules and skills through your coding agent's MCP tools, the CLI or the VS Code extension. For local workspaces, `pathrule ui` opens the [Local Console](/docs/surfaces/local-console) with browsing, search, editing, restore and activity. Pathrule Web does not read your local repository or run coding agents. Your coding agent remains the tool that performs the coding work. ## Connections and access Sign-in and Remote MCP authorization use the Cloud authentication service. A Remote MCP grant is limited to the workspace and scopes you approve. The console calls the Cloud API with your session, and the server checks current access and plan entitlements on each operation. Sharing Cloud knowledge does not share a teammate's local folder bindings, hook installation or personal machine state. Each contributor attaches their own repository with [the CLI](/docs/surfaces/cli) or [VS Code](/docs/surfaces/vscode). ## /docs/surfaces/local-console # Local Console Run `pathrule ui` to work with your local Pathrule knowledge in a browser. It needs no account and uses the same local workspaces as the CLI. ## Open it From a project with a local workspace: ```bash pathrule setup --local pathrule ui ``` The command serves the console on `127.0.0.1`, opens a one-time launch link and stays running until you stop it. Press `Ctrl+C` in the terminal to stop serving it. A second `pathrule ui` reuses the running console. ```bash pathrule ui --no-open # print the launch link instead pathrule ui --port 4317 # choose a port pathrule ui --json # return the launch result as JSON ``` ## What you can do - Browse local workspaces and search their knowledge. - Create, edit and archive memories, rules and skills. - Restore archived knowledge. - Inspect activity that agents recorded and local runtime status. - Review Local Signals, including occurrences, releases and verification states. It loads no external resources. Knowledge and runtime observations stay in the local Pathrule store. Your coding agent keeps its own model provider and network connections. ## Local and Cloud The Local Console is for knowledge on this machine. [Pathrule Web](/docs/surfaces/web) manages Cloud workspaces, organizations, members, settings and billing. Opening the Local Console does not sign you in or move local knowledge into Cloud. ## /docs/surfaces/cli # Pathrule CLI Pathrule CLI is the installation and terminal surface for Pathrule. It is published on npm as `@pathrule/cli` under the Apache-2.0 license, runs on macOS, Linux and Windows, and hosts the local MCP server, the local cache and the hook supervisor in your shell. It connects Claude Code, Codex, Cursor, Windsurf and GitHub Copilot, and it fits SSH, headless and standalone terminal workflows. The content and MCP contract stay shared across clients, while delivery follows the channel each client exposes. Claude Code and Codex get hooks that include a prompt hook, so context arrives before the agent acts. Cursor and GitHub Copilot get session and tool hooks, with no prompt hook. Windsurf has no hooks: it reads a generated rules file and reaches deeper context through MCP. ## What Pathrule CLI owns - **Sign-in.** A one-time device code by default, which works the same on your own computer, over SSH and on any headless machine, or GitHub sign-in over a browser callback on this machine with `--browser-callback`. - **Workspace attach.** Attach the folder you run it in to a workspace, so the runtime can resolve your AI session's working directory. `pathrule setup` does it as a guided run, and `pathrule init` creates and attaches a workspace in one step. - **AI client install and sync.** Writes Pathrule's MCP entry into Claude Code, Codex, Cursor, Windsurf and GitHub Copilot. `pathrule sync` writes the instruction files and hook configuration each client reads into the repository. - **Removal.** `pathrule eject` previews project cleanup and `pathrule eject --apply` applies it. Remove native integrations through `pathrule integrations remove ` and settings-based MCP entries through `pathrule uninstall `. See [Remove Pathrule from a project](/docs/cli/install#remove-pathrule-from-a-project). - **No account needed.** `pathrule init --local` and `pathrule setup --local` run Pathrule on a local store with no sign-in and no cloud. See [Work without an account](/docs/cli/commands#work-without-an-account). - **The on-device model.** `pathrule intelligence` installs, updates and removes the optional on-device model on an Apple Silicon Mac. Nothing else depends on it. See [the local model](/docs/intelligence/local-model). - **MCP server.** Runs locally and is the surface your assistant speaks to. - **Hook supervisor.** Registers the hooks each hook-capable client supports and delivers the path-scoped context for the folder the agent is working in. - **Your working preferences.** `pathrule me` lists, teaches, explains, re-scopes and forgets what [User Intelligence](/docs/intelligence/user-intelligence) holds about you, kept on your machine, and `pathrule me context` shows what an agent would receive for a task. - **Knowledge in the terminal.** `pathrule search`, `list` and `read` work in Local and Cloud. CLI `add` is for Cloud workspaces; local authoring uses the Local Console, VS Code or MCP. - **Doctor.** A single read-only command that checks your sign-in, workspace and folder attachment, each AI client's MCP entry, and the files Pathrule manages in the folder. `pathrule repair` fixes out-of-date entries. - **Scripting.** Nearly every command takes `--json` for stable, machine readable output. Every command and option is in the [command reference](/docs/cli/commands). ## Happy path ```bash pathrule login pathrule org use my-team cd ~/repos/my-project pathrule setup pathrule doctor ``` `pathrule setup` attaches the folder to a matching workspace or creates one, asks which AI clients to connect, installs them and writes the files they read. To create the workspace yourself, run `pathrule init my-project` in the folder, or `pathrule workspace attach my-project` for one that already exists. Both act on the current folder, and neither takes a path option. After this, Claude Code or Codex opened in `~/repos/my-project` receives the Pathrule context for its first prompt. Cursor and GitHub Copilot receive it at session start and around tool calls, and Windsurf reads it from its rules file and through MCP. ## Output modes The CLI has two output modes that you switch between with `--json`. - **Human mode (default):** Status lines marked ok, warn, error or info, with the next command to run where one applies. Prompts and browser windows appear only in an interactive terminal. - **JSON mode:** One JSON object per command, for scripts, CI runners and automation. It always carries `ok`, `command` and `cwd`, plus `data` on success or an `error` with a `code` and a `message`. `--json` is available on commands that advertise it in `--help`. `snapshot` and `eject` do not support it, and it never prompts or opens a browser. ```bash pathrule workspace list # human pathrule workspace list --json # machine readable ``` A command exits non-zero when it did not do what you asked, so a CI step fails on it. ## Commands that open the browser A few flows are cloud only and open [Pathrule Web](/docs/surfaces/web) in your default browser rather than reimplementing the console in the terminal. ```bash pathrule billing pathrule upgrade pathrule team open ``` Each one prints the URL it opened. With `--no-open` it prints the URL without opening anything, so you can copy it from a remote shell. Plain `pathrule team` lists the organization's members and pending invites in the terminal. ## When to use Pathrule CLI Use Pathrule CLI when you work over SSH, when you want to script Pathrule into a CI runner, when you want to try Pathrule with no account, or when you simply live in the terminal. To browse and edit knowledge inside your editor, add [Pathrule for VS Code](/docs/surfaces/vscode), which shares the same sign-in and hooks. ## What to read next - [Install](/docs/cli/install) for install paths, the sign in flows, what Pathrule writes into a repository, and how to remove it. - [Command reference](/docs/cli/commands) for every command and option. - [Pathrule for VS Code](/docs/surfaces/vscode) for the editor surface that shares the same identity and hooks. - [How hooks work](/docs/hooks/how-hooks-work) for what the runtime hands to your assistant. ## /docs/surfaces/vscode # Pathrule for VS Code Pathrule for VS Code is a native editor surface. It brings the workspace knowledge tree, content editing, and AI client setup inside the editor, so the folder you have open is the workspace and the file you are editing is the path. It is the right surface if you live in VS Code, Cursor, or Windsurf and want your knowledge next to your code. It is a focused editor surface. The same content and hooks the [CLI](/docs/surfaces/cli) works with are driven from the editor you already use, and external client setup reuses the CLI's installer. ## Install Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Pathrule.pathrule-vscode), or from Open VSX so Cursor and Windsurf can install it too. From a terminal: ```bash code --install-extension Pathrule.pathrule-vscode ``` Or, from the editor, open the Quick Open prompt and run: ```text ext install Pathrule.pathrule-vscode ``` It is free and open source under Apache-2.0, and local mode needs no account, so you can start the moment it installs. ## What the extension owns - **Knowledge tree.** A sidebar that shows only the paths carrying knowledge, repo-shaped, with memories, rules, and skills grouped under each path. Content counts appear as badges on tree rows and on the matching files and folders in the built-in explorer. - **Active-file sync.** As you move between files the tree follows the editor to the deepest path that covers the current file, and the status bar shows that path with its content counts. - **Content editing.** Memories, rules, and skills open as ordinary markdown editor tabs. Saving persists through Pathrule, with full editor tooling for free. - **Agent setup.** One command connects your AI clients and installs the path-scoped hooks, the same setup the CLI performs. - **Onboarding.** Open a folder with no workspace yet and the extension walks you from set up to a bound workspace without leaving the editor. - **Doctor.** A single command that checks each client is connected, the hooks are present, and the context server is reachable. ## Local mode and cloud mode The extension runs in two modes behind one user interface, the same split as the CLI and the [open source core](/docs/editions/open-source-core). - **Local mode** needs no account. Initialize a folder locally and your memories, rules, and skills live on your machine. It is the fastest way to start. - **Cloud mode** signs you in and adds the team layer: shared knowledge, team activity and the managed backend. The mode is a property of the open folder, not a guess. A signed-in user whose folder is not yet a cloud workspace is offered both creating one in the current organization and initializing locally. Cloud-only actions are hidden, not broken, when a folder is in local mode, so the same extension serves both. ## Editing as markdown tabs Open a memory, rule, or skill from the tree and it opens as a normal markdown tab. Edit it like any file and save to persist the change. If a teammate changed the same item while you had it open, the save does not silently overwrite their work: you are offered to reload, keep a copy of your version, or overwrite with your own. Conflicts surface as a decision, never as lost edits. From the explorer, right-click any file or folder for a Pathrule submenu: browse the knowledge that applies there, or create a new memory, rule, or skill scoped to that path. From a tree item you can copy it as a prompt pointer, view its details, rename, move it to another path, or delete it with an undo. Multi-select supports bulk move and delete, and a fuzzy search spans every title across the workspace. ## Identity shared with the CLI Signing in from the extension uses the same hosted login as the CLI, with your choice of GitHub, Google, or email. The session is shared: signing in here signs the CLI in too, and switching organization in one switches it in the other. One identity across the extension, the CLI, and your AI assistant. ## Connect your AI clients A single Connect AI clients command wires your assistant to Pathrule with no JSON editing. - **GitHub Copilot agent mode** gets Pathrule's MCP server registered by the extension for the bound folder. - **Claude Code, Codex, Cursor and Windsurf** receive managed MCP entries written with the same installer the CLI uses. - **Hooks** are installed through the same pipeline the CLI uses, and the result notification lists exactly what was written. After this, your assistant receives the Pathrule context for the current path through the channel it supports: hooks that include a prompt hook for Claude Code and Codex, session and tool hooks for Cursor and GitHub Copilot, and a rules file plus MCP for Windsurf, which has no hooks. Run the doctor command at any time to confirm each client is connected and the hooks are fresh. ## Working with your team Cloud writes are shared, but the current Cloud backend does not provide a real-time subscription. Refresh the knowledge view or request context again to read the latest state; local hooks and instruction files use prepared knowledge until refreshed. Organization-level work stays in [Pathrule Web](/docs/surfaces/web): team management, plans and billing, and the cross-workspace overview are reached through links rather than reimplemented in the editor. If you started in local mode and want to bring a folder to your team, a single action signs you in, picks an organization, and copies the workspace and its content to the cloud, keeping your local copy as a fallback. ## When to use Pathrule for VS Code Use the extension when you work primarily in VS Code, Cursor, or Windsurf and want the workspace knowledge tree, content editing, and agent setup in the editor that already knows your open folder and active file. Start in local mode in seconds, and sign in later when you want the team layer. If you live in the terminal or script Pathrule into CI, prefer [Pathrule CLI](/docs/surfaces/cli). The two share the same sign-in, so you can use both. ## What to read next - [Pathrule CLI](/docs/surfaces/cli) for the terminal first runtime that shares the same identity and hooks. - [Open source core](/docs/editions/open-source-core) for what local mode runs and what Cloud adds. - [How hooks work](/docs/hooks/how-hooks-work) for what the extension hands to your assistant. ## /docs/surfaces/remote-mcp # Pathrule Remote MCP Connect a hosted MCP client to `https://cloud.pathrule.io/mcp` to read and write knowledge in a Pathrule Cloud workspace. It uses Streamable HTTP and OAuth 2.1 with PKCE. You need a Pathrule account and access to the workspace you approve. ## Connect Create or sign in to your account at `https://app.pathrule.io`, then connect your MCP client: ```bash claude mcp add --transport http pathrule https://cloud.pathrule.io/mcp codex mcp add pathrule --url https://cloud.pathrule.io/mcp ``` For Claude.ai or another HTTP MCP client, use the same endpoint. Complete the authorization flow and approve the workspace and scopes the client requests. ## Discovery - MCP: `https://cloud.pathrule.io/mcp` - Authorization server: `https://cloud.pathrule.io/.well-known/oauth-authorization-server` - Protected resource: `https://cloud.pathrule.io/.well-known/oauth-protected-resource/mcp` ## Tools and grants A read grant exposes `pathrule_get_context` and list and read tools for memories, rules and skills. A write grant also exposes creation, updates, deletion and per-item history. Access is limited to the grant's workspace; supplying another workspace id cannot widen it. Remote writes use `title`, `body` and a canonical `path`. Updates use an item `id` and numeric `expectedVersion`. Mutations need a stable `operation_id` or idempotency key, so retrying an operation does not create a second copy. These are remote schemas, not the local server's `content_edit` and `expected_version_id` schemas. Ask the connected server for `tools/list` before using them. The authorization server recognizes `pathrule:read`, `pathrule:write`, `pathrule:refresh` and `pathrule:activity`. A recognized scope does not imply a tool exists: the current remote catalog covers knowledge and context. Organization administration, workspace creation, snapshots, local project learning, pattern imports, activity logging and refresh workflows use the CLI, local MCP tools or Cloud console. ## Permissions remain current The server checks your session, workspace state and membership when it authorizes access and executes a tool. Removal from a workspace, archive or deletion revokes its grants. Restoring the workspace does not revive those grants; reconnect and approve access again. Refresh tokens rotate, and replaying an already rotated token revokes its token family. ## Local delivery Remote MCP cannot read your filesystem, install hooks, write companion files or send local personal preferences. An agent must call its tools to obtain context. Use [the CLI](/docs/surfaces/cli) or [VS Code](/docs/surfaces/vscode) when you want repository-aware context and hooks before the agent acts. ## /docs/content/memories # Writing memories A memory is a short markdown note your team writes down so the assistant can read it later. Memories live at a workspace path, and they only surface when the assistant is working under that path. They are the most common content type in Pathrule and the easiest to start with. This page covers when to write a memory, how to structure it, and how scope and versioning work. ## When to write a memory Reach for a memory when you have a piece of knowledge that is not obvious from the code and is likely to come up again. - **Decisions.** "We use Postgres on Supabase for everything in this repo. Do not bring in an ORM. Use the supabase-js client directly." - **Gotchas.** "If you change the `orders.status` enum you must run the data migration before the schema migration. The order is reversed from the rest of the schema." - **Postmortems.** "On 2026-04-12 we shipped a webhook handler that double charged customers because we did not check the Stripe idempotency key. Always pass it now." - **Conventions.** "Tests live next to the file they test, not under a parallel `__tests__` directory." - **Tribal knowledge.** "Only one person remembers why this flag exists. It is still required because of a runtime quirk in upstream." Skip memories for things the code already says clearly, things that change weekly, or things that are entirely personal preference. ## Structure Every memory has a title and a markdown body. Keep both small. - **Title:** short, declarative, fits in a sidebar. "Postgres only. No ORM." beats "Notes on database access patterns". - **Body:** the smallest amount of markdown that makes the point. Bullets are usually clearer than paragraphs. Include one example if it helps. There is no required template, but a useful default is: ```markdown The constraint or fact in one sentence. Why: - The reason this matters or the incident that prompted it. How to apply: - The concrete thing the assistant should do when the topic comes up. ``` ## Path scope The path is half the memory. It decides where the memory surfaces. - A memory at `/apps/api/payments` surfaces for any work under `apps/api/payments`. - A memory at `/apps/api` surfaces for the whole api directory. - A memory at `/` surfaces everywhere in the workspace. Pick the most specific path that still covers the cases you want. A workspace level memory about payments noise is worse than a payments folder memory about payments. ## Versioning and concurrent edits Every save is checked against the version you started from. If someone else saved in between, your save is refused instead of overwriting theirs. This protects your team from two people, or a person and an agent, silently overwriting each other. - **In Pathrule for VS Code** a memory is a markdown tab. A save that would overwrite a teammate's newer change offers **Reload**, **Copy My Version & Reload** (your text goes to the clipboard first) or **Keep Mine (Overwrite)**. - **Through MCP** the assistant can pass the version it last read. On a mismatch it gets a conflict back with the current version, re-reads, and merges instead of clobbering. Deleting is reversible too. In VS Code a delete offers **Undo** straight away, and on a Pathrule Cloud workspace a deleted memory remains in the workspace archive until permanently deleted, where an owner or admin can restore it from the web console settings (**Workspace**, **Archive**) or delete it for good. Conflicts are rare in practice because memories are usually small and focused, but the safety net is always on. ## Who writes them - **People** writing in Pathrule for VS Code (**New Memory…** or **Save Selection as Memory**) or with the CLI. - **The assistant** writing through the `pathrule_write_memory` MCP tool when you ask it to save something. During setup it proposes memories, rules and skills for the project and writes only the items you approve. From the terminal, a memory is one command. With no `--body`, the CLI opens your editor for the body; you can also pass `--body` or pipe the text in. `pathrule memory list` and `pathrule memory read "Exact title" --print` read memories back. ```bash pathrule memory add --path /apps/api/payments --title "Always pass the Stripe idempotency key" ``` Both sources land in the same place. The assistant reads what a person wrote, and a person reads what the assistant wrote. Every record keeps who created it, who last edited it and its source, which the **Info** action in VS Code shows, so AI-authored memories are easy to spot. ## How memory quality stays reviewable Pathrule keeps a memory narrow and inspectable through several independent controls: - General documentation is offered during setup rather than imported automatically. Live instruction files, their import chain, tool rules and decision records have stronger evidence that they are active knowledge. - An agent is asked to propose lasting knowledge before it saves it. Whatever it does save is attributed, versioned and visible in the workspace like anything else, so you can open, edit or remove it. - Path scope limits where the entry can surface, and an entry outside the current path still has to clear the relevance floor. - Measured usage may reorder qualifying entries, but it cannot lift an unrelated memory past that floor. - An agent that notices a memory has drifted from the code can flag it as a refresh task, which an assistant later picks up and repairs under your control. See [Suggestions and self-audit](/docs/content/suggestions). Edits are versioned and deletion is reversible. - A new memory whose title matches an existing one at the same path is refused by default rather than saved as a second copy, so the same decision is not delivered twice or left to drift apart. You can override that deliberately (`--allow-duplicate` on the CLI) after checking the existing entry. The resulting operating model is a small set of narrow, reviewable decisions and gotchas, not a large archive copied into the workspace. See [How Pathrule proves hard claims](/docs/start/technical-proof) for the full technical contract. ## Reading versus citing The most relevant memories arrive as full bodies the assistant can act on directly. Less certain candidates arrive as titles with ids; the assistant reads one in full with `pathrule_read_memory` before relying on it. This keeps uncertain material out of the default payload without turning strong matches into extra round trips. In VS Code, **Browse Knowledge Here…** shows what an AI session on a path receives, including what it inherits from parent paths. ## Anti patterns - **One huge "all my notes" memory.** Split by topic and scope. Smaller and path scoped beats long and global every time. - **Memories that say what the code already says.** The assistant can read the code. Reserve memories for the why and the gotcha. - **Stale memories.** Update or delete them when the underlying decision changes. An assistant can flag a drifted memory as a refresh task, but a human eye is faster. ## Local and Cloud authoring The terminal `add` examples on this page are for a Cloud workspace. In Local mode, create and edit entries in [Local Console](/docs/surfaces/local-console), VS Code or through local MCP; CLI knowledge commands list, read and search them. ## What to read next - [Writing rules](/docs/content/rules) for constraints with priority. - [Writing skills](/docs/content/skills) for reusable procedures. - [Core concepts](/docs/start/core-concepts) for the workspace tree these attach to. ## /docs/content/rules # Writing rules A rule is a constraint the assistant must follow inside a scope. Rules are the strongest piece of content in Pathrule: they arrive as requirements rather than as background, and a rule that carries an approved executable constraint can stop a matching change before it lands. This page covers when to write a rule, how to choose scope and priority, what enforcement means, and the patterns to avoid. ## When to write a rule Reach for a rule when there is a thing the assistant must not do, or a thing it must always do, in a specific part of the codebase. - "Never use the service role key in browser code." - "All money values are stored as integers in cents. Never use floats." - "Migrations must run before the matching code change. No exceptions." - "JSX files in `apps/web` use Tailwind classes only. No CSS modules, no inline styles." If the answer is "it depends on the situation, the assistant should think about it," that is a memory, not a rule. Rules are for non negotiable things. ## Scope types Every rule has a scope type that decides which paths or files it applies to. - **`folder`.** Applies to a directory subtree. Best for area specific rules: anything that lives under `apps/api/auth`, anything under `services/billing`. - **`file_type`.** Applies to files matching a glob like `*.tsx` or `**/*.test.ts`. Best for cross cutting concerns that are tied to a file kind, not a directory. - **`project`.** Applies everywhere in the workspace. Use sparingly. A project rule rides every prompt. The scope and the node path the rule is attached to together decide what the assistant sees. A `folder` rule attached at `/apps/web` covers anything under `apps/web`. ## Priority levels Priority decides how aggressively the rule shows up. Within a matching scope, higher priority rules are considered first. - **`high`.** For things that cause bugs, security regressions, or compliance issues if violated. - **`medium`.** The default. Use for "almost always but not load bearing". - **`low`.** Stylistic. Surfaces when there is room and the topic is on point. Use for taste and convention. High priority is a budget. If half your rules are high priority, none of them are. Pick the ones that really cannot be violated. ## Enforcement: advisory and strict Enforcement is a separate setting from priority. Priority ranks how strongly a rule surfaces; enforcement decides what happens on a violation. - **`advisory`.** The rule is context. The assistant weighs it and decides how to apply it. Rules you write from the CLI or VS Code, and rules an assistant writes, are advisory. - **`strict`.** A rule becomes strict when it carries an executable constraint that a person has approved: the exact forbidden form, such as an import, an identifier or a location. The pre-tool hook can then block a file edit or write that matches it before the change lands, and returns the rule and its remedy as the reason. An assistant can attach a proposed constraint when it writes or updates a rule (`pathrule_write_rule`, `pathrule_update_rule`), but a proposal is stored as a proposal and blocks nothing until a person approves it; an assistant can never approve its own. See [Rules as guardrails](/docs/hooks/rules-as-guardrails). **Rewriting a rule keeps enforcement honest.** An approved constraint is tied to the sentence of the rule it was proved against. If you rewrite the rule and that sentence is gone, the constraint stops enforcing on its own, so a rule never keeps blocking for a reason it no longer states. Editing other parts of the rule, or adding a paragraph, leaves an untouched constraint armed. Blocking depends on the client. Pathrule CLI installs tool hooks for Claude Code, Codex, Cursor and GitHub Copilot, and a block applies where the client's pre-tool hook honours the decision. Windsurf has no hooks, and Remote MCP installs none, so there rules arrive as context only. Delivery alone does not enforce anything. ## Structure A rule has a name and a body. Keep the body imperative and short. ```markdown Name: No service role key in browser code Body: - Never import SUPABASE_SERVICE_ROLE_KEY in any file under apps/web. - Use the anon key plus row level security. - If you need server only access, do it from apps/api or a server action. ``` From the terminal, the same rule is one command. With no `--body`, the CLI opens your editor for the body. ```bash pathrule rule add --path /apps/web --name "No service role key in browser code" --priority high --scope folder ``` In VS Code use **New Rule…**, and an assistant writes rules with `pathrule_write_rule`. The shape that works best in practice is one constraint per rule with a small bulleted body. Long prose rules get skimmed by both humans and assistants. ## Reusable, not duplicated A rule lives at one path and covers everything beneath it, so one rule is enough for a whole subtree. If the same constraint applies to two distant folders, put it at their nearest common path, or use a `file_type` scope with a glob, rather than copy pasting the text into two rules. One rule means one edit when the constraint changes. Pathrule helps here: a new rule whose name matches an existing rule in the workspace is refused by default, and the write tells you which rule already exists. You can override that deliberately (`allow_duplicate` through MCP) after checking the existing rule. To re-home a rule, move it to another path (**Move…** in VS Code, or `pathrule_update_rule` with `move_to_path`). ## Versioning and concurrent edits Rules carry a version token like memories. Two teammates editing the same rule at the same time will conflict cleanly rather than overwrite each other. In VS Code the conflict offers the same choices as for a memory: **Reload**, **Copy My Version & Reload** or **Keep Mine (Overwrite)**. ## How rules show up to the assistant - **Rules in a matching scope** are ranked by priority and by how relevant they are to the task. The most relevant arrive as full bodies; the rest are named, so the assistant knows they exist and can read one in full with `pathrule_read_rule`. - **A strict rule** always arrives in full where it applies, because a name alone cannot explain a block. - **Rules are also compiled** into the instruction files your clients read (for example CLAUDE.md for Claude Code and AGENTS.md for Codex), so a client without a prompt hook still starts from them. Whether a rule can block a change, rather than just inform the assistant, is set by its enforcement mode (advisory or strict), not by its priority. ## Anti patterns - **High priority for everything.** Pick the rules that really matter. The rest should be medium. - **Rules that read like memories.** "We tend to prefer X" is a memory. "Never do Y" is a rule. - **Rules that overlap.** Two high priority rules with conflicting language is worse than one clear rule. - **Project scope used by default.** Most rules belong under a folder. Pull a rule up to `project` only if it really applies everywhere. ## Local and Cloud authoring The terminal `add` examples on this page are for a Cloud workspace. In Local mode, create and edit entries in [Local Console](/docs/surfaces/local-console), VS Code or through local MCP; CLI knowledge commands list, read and search them. ## What to read next - [Writing memories](/docs/content/memories) for facts and decisions that are not constraints. - [Writing skills](/docs/content/skills) for reusable procedures the assistant can invoke. - [How hooks work](/docs/hooks/how-hooks-work) for how the runtime decides which rules to surface. ## /docs/content/skills # Writing skills A skill is a named procedure the assistant can invoke instead of re deriving the steps every time. Memories tell the assistant what is true. Rules tell it what not to do. Skills tell it how to do a specific job, step by step. This page covers when to write a skill, what goes inside one, and how skills are stored and attached. ## When to write a skill Reach for a skill when you notice the same pattern repeating. The signal is "the assistant keeps walking through the same set of steps and sometimes misses one". - **Operational procedures.** "Replay a Stripe webhook locally." "Regenerate the seed fixtures." "Run the pre release checklist." - **Custom workflows.** "Open a draft PR with the right labels and the right reviewers." "Bump the version, tag, and push." - **Domain specific guidance.** "Build a new analytics event end to end: column, type, dashboard." If the pattern is one or two lines, a memory is enough. Reach for a skill when the procedure has more than three steps or carries any "do this in this order" requirement. ## Sources A skill record carries a source value that tells Pathrule where its body lives. - **`manual`.** The body is authored directly in Pathrule and stored as is. The default. Use this when you want the procedure to be fully owned by the workspace. - **`template`.** A Pathrule provided starter skill, copied into the workspace and editable from there. - **`github_ref`.** The skill points at an external GitHub URL. Use this for skills published by skill ecosystems you trust. For `github_ref` skills, the workspace keeps a snapshot of the body taken from that source, and the skill is read-only in the workspace: VS Code tells you to edit the source instead. ## SKILL.md structure A skill is a small markdown file with frontmatter followed by the procedure body. ```markdown --- name: replay-stripe-webhook description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling. --- # Replay a Stripe webhook Use this when a payment event from production needs to be reproduced locally. ## When to invoke - A customer reports a missing receipt and you have the event id. - You are debugging a webhook handler change. ## Procedure 1. Find the event in Stripe Dashboard. Copy its id. 2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`. 3. Watch the local handler. It must accept and process the event without double charging. 4. If the handler returns 5xx, the customer support page is the next stop, not a retry. ## What NOT to do - Do not replay against production webhooks. - Do not skip the idempotency key check. ``` Frontmatter must include `name` and `description`. Everything below is the body the assistant follows. The body can be as short or as long as it needs to be. ## Attachment A skill lives at one workspace path, the same way a rule does. Put it at the path where the procedure is most relevant. The replay webhook skill goes on `services/billing/webhooks`. The release skill goes at the workspace root. A new skill whose name matches an existing skill in the workspace is refused, so update the existing one instead of adding a second copy. The assistant discovers skills through the context Pathrule delivers for a path (the same way it discovers memories and rules), through `pathrule_get_context`, and reads one in full with `pathrule_read_skill`. On sync, Pathrule also writes skills into the skill folders of clients that read them, such as `.claude/skills` for Claude Code and `.agents/skills` for Codex. ## Invoke a skill on demand with `::skill-name` Usually the assistant picks the right skill on its own. When you want to force a specific one, type `::` followed by the skill name anywhere in your prompt, for example `::release-check` or `::replay-stripe-webhook`. For that turn the assistant treats the named skill as a mandatory workflow to follow, with no long instructions to write. In Claude Code and Codex the prompt hook picks the marker up before the agent acts; in other clients the assistant receives the same instruction when it requests context through MCP. It is designed to fail safe: - If the name matches more than one skill, no skill is invoked rather than a guess being made. - If the name matches no skill, the assistant is told to stop and resolve it with you before editing anything. It can suggest published candidates, and it waits for your approval before adding one to the workspace. - It ignores code-like uses of `::` such as `button::before` or `std::vector`, so ordinary prompts are not misread. That makes `::skill-name` a quick, path-independent way to pull a known team procedure into the current turn. ## Authoring flow Two flows land in the same place. - **Manual authoring.** In VS Code, use **New Skill…** at the right path and write the SKILL.md body. From the terminal, run `pathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally"`; with no `--body`, the CLI opens your editor. - **Assistant authoring.** In Claude Code (or any MCP client) the user asks the assistant to "make this into a skill". The assistant uses a small skill creator pattern: capture intent, interview the user, draft the SKILL.md, then call `pathrule_write_skill` with the full body. For low commitment scenarios the assistant drafts the skill in the conversation and waits for approval before calling `pathrule_write_skill`. The persisted record is therefore the reviewed draft, not a silent background write. ## Versioning and concurrent edits Skills carry a version token like memories and rules. Two teammates editing the same skill conflict cleanly rather than overwrite each other, with the same conflict choices in VS Code as for a memory. ## Anti patterns - **Skills that are really memories.** If the body is "this is true about how we work", make it a memory. - **Skills that are really rules.** If the body is "never do X", make it a rule. - **One skill that does too much.** Split into two named skills if the procedure has two distinct entry points. - **Pulling external skills you do not trust.** A `github_ref` skill is code that runs in your assistant's instructions. Treat it like a dependency. ## Local and Cloud authoring The terminal `add` examples on this page are for a Cloud workspace. In Local mode, create and edit entries in [Local Console](/docs/surfaces/local-console), VS Code or through local MCP; CLI knowledge commands list, read and search them. ## What to read next - [Writing memories](/docs/content/memories) for facts and decisions. - [Writing rules](/docs/content/rules) for constraints. - [MCP tools reference](/docs/mcp/tools-reference) for the tools the assistant uses to write skills. ## /docs/content/suggestions # Suggestions and self-audit Team knowledge rots. Paths get renamed, milestones ship, dependency pins drift, a rule stops matching anything. Pathrule's answer is a **refresh task**: a flag on a memory or rule that looks stale, with a plain-language reason, which your own assistant repairs under your control. The important property: a refresh task only ever *suggests*. Pathrule never edits or deletes your memories, rules or skills on its own. ## What the self-audit checks The audit happens where the drift is noticed: in the work itself. An assistant reading your code is the first to see that a memory describes a file that moved, or that a rule contradicts what the code now does. When that happens in its normal work, it flags the entry with the `pathrule_request_refresh` MCP tool, naming the memory or rule and why it looks wrong. Typical reasons: - **Drift.** The entry describes a state that no longer matches the code, for example a file it cites has moved or no longer exists. - **Contradicts the code.** The entry says one thing and the code clearly does another. - **Duplicate.** Another memory or rule already covers the same ground better. - **Too narrow.** The entry only applies to a case that is long gone. - **Unclear.** It is not possible to tell what the entry asks for. Flagging is idempotent: flagging the same entry twice returns the same task, so repeated sessions do not pile up duplicates. Assistants are told to flag only drift they actually noticed, not to go looking for it. Nothing about your source code is stored in a refresh task. It names the entry and carries the reason; the assistant that later repairs it reads the current code with its own file tools. ## Reviewing suggestions A refresh task is a prompt for a decision, not an action. On a Pathrule Cloud workspace you can work with them from the terminal: ```bash pathrule refresh list pathrule refresh claim pathrule refresh resolve --status applied ``` `list` shows the pending tasks for the current workspace, `claim` returns the full brief for one task and marks it in progress, and `resolve` closes it as `applied` or `rejected`. An assistant does the same through MCP with `pathrule_list_pending_refreshes`, `pathrule_get_refresh_brief` and `pathrule_resolve_refresh`. For each task you can let your assistant apply the fix (see below), edit the entry yourself, or reject the task when the entry is still right. ## Repair through your assistant Pathrule does not patch your knowledge automatically. Ask your assistant to work through the pending refresh tasks. It then: 1. Lists the pending tasks and claims one, which marks it in progress so another session does not take it at the same time. 2. Inspects the current code and the flagged entry with its own file-access tools. 3. Drafts the update and writes it back through the Pathrule write tools. Passing the task id with the update closes the task as applied. 4. Otherwise marks the task applied or rejected explicitly. You stay in control at both ends: the fix runs through your own assistant, and the change is an ordinary versioned edit you can review. See the [MCP tools reference](/docs/mcp/tools-reference) for the refresh tools the assistant uses. ## Nothing is one-way A repair is a normal versioned edit. Every change keeps its history, and on a Pathrule Cloud workspace a deleted entry remains in the workspace archive until permanently deleted, where an owner or admin can restore it from the web console settings. In VS Code, a delete offers **Undo** straight away. If a fix turns out to be wrong, you can change it back like any other edit. ## /docs/content/work-episodes # How did we solve this before Every time an AI session finishes a piece of work, it can log what happened: the area it touched, the action it took, the files involved, and a short summary ([what a session records](/docs/content/activity-log) covers that entry in full). On its own, each log is a single line in a long list. Work episodes turn that list into something a future session can actually use. Pathrule rolls related activity from a working session into a work episode: a titled record of one thing your team solved, with the subjects it was about, the paths and files it touched, the AI clients involved, and when it happened. Months later, when someone hits the same area again, that episode is there to recall. ## Recall is on demand, not on every prompt Work episodes do not ride along in every request. An ordinary prompt adds no history at all, so your context window is not paying a tax for memory you are not using. When your agent is doing the kind of work where the past matters (fixing a bug, debugging, refactoring, or exploring an unfamiliar area) Pathrule can include a few of the most relevant prior episodes in the context it returns. Your agent can also ask for prior work explicitly, and a strongly worded historical question ("how did we handle this last time") is enough to trigger a look. For small UI tweaks and brand-new features, episodes stay quiet, because anchoring fresh work to old patterns tends to cost more than it helps. ## What makes an episode relevant Relevance is computed from two plain signals and one preference, not from a guess: - What the work was about. An episode about authentication is a candidate when you are back in authentication, not when you are formatting a table. - Where the work happened. An episode that touched a path is a candidate when you are working at or under that path, in either direction. - How recent it was. Recent work is favored over stale work, because code drifts and old episodes describe a codebase that may no longer exist. The result is a short, ranked set: a handful of episodes at most, each compact enough to read at a glance. ## Skip beats wrong Pathrule would rather surface nothing than surface the wrong thing. If an episode has no real overlap with what you are doing, it is not shown. If the system is not confident, it stays quiet. If your workspace has not built up enough history yet to score reliably, recall short-circuits and returns nothing. You will not see a wall of vaguely related work; you will see the few episodes that earned their place, or none. ## Built from what you log, never from your code Work episodes are built only from the activity your agents log through Pathrule. Pathrule does not read, scan, or index your source files to build them. The same access control that governs the rest of your workspace governs episodes: they are scoped to your workspace, behind your team's per-user access, and identical for everyone who can see them. Cloud recall is built from retained activity evidence. Activity older than 180 days is removed by scheduled maintenance, so recall is not a permanent record of every session. Local retention is separate. ## Where to find this Work episodes surface through the context your AI client receives, on the kinds of tasks where they help. You do not configure them per repo and you do not turn them on prompt by prompt. They are a property of a workspace that has accumulated real, logged work. See [Suggestions and self-audit](/docs/content/suggestions) for how a stored memory or rule that has drifted from the code is flagged and repaired. ## /docs/content/activity-log # What an AI session records Most of what Pathrule learns about your project it learns from work, not from writing. When an AI session finishes a piece of work it records a short structured entry, and that single entry is what several other features are built on. This page is about what is in that entry, what is deliberately left out of it, and what it goes on to power. ## What is recorded Each entry is a handful of fields, all small: - **Area, action and scope.** What kind of thing was touched (`ui`, `backend`, `database`, `infra`, `config`, `test`, `docs`), what was done to it (`create`, `update`, `fix`, `refactor`, `delete`, `style`), and at what level (a component, a page, an API, a migration, a service). - **Subjects.** Up to five lowercase keywords, the way you would tag the work in conversation. - **A one-sentence summary.** What changed and why, in a line. - **The paths it touched**, grouped by area. - **Which AI client** the session ran in, and when. - **How the turn went**: how many tool calls it took, how many failed, and a short code for each kind of failure (`timeout`, `exit_nonzero`, `not_found` and similar). Counts and codes only, never the command or the error text. That is the whole record. It is designed to be readable at a glance months later, which is also why it stays short. The **Recent Activity** view in Pathrule for VS Code lists the latest entries for the workspace. The assistant writes the sentence. Pathrule attaches the measurement. The summary, the area and the paths come from the session that did the work, while the tool-call count, the failures, and which of the delivered entries were actually consulted are observed by the layer that delivered them. That split matters: an assistant can forget to mention that four commands failed, and the count is there anyway. ## What is never recorded Your code is not in it. No file contents, no diffs, no patches, no commit messages, and no prompt text. The paths are there so later features can tell *where* work happened; the substance of the change is not stored. Paths are also **normalised before they are stored**. A path arrives as whatever the agent saw on that machine and is converted to workspace-relative form, so `/Users/you/projects/app/src/api.ts` becomes `src/api.ts`. Nothing machine-specific reaches shared team knowledge, and the same file is the same file whoever touched it. ## What one entry feeds The reason the record is worth keeping is what reads it: - **[Work episodes](/docs/content/work-episodes).** Related entries from one working session roll into a titled record of one thing your team solved, which a later session can recall. - **[Files that change together](/docs/retrieval/co-change).** The paths in each entry are what teaches Pathrule which files travel in pairs. - **Retrieval learning.** When knowledge was put in front of an agent and the agent then worked in that same area, that is evidence the knowledge was relevant. Over time it moves the ranking, described in [how retrieval works](/docs/retrieval/how-retrieval-works). None of those needs a separate step from you. They all come from the same short entry. ## Logging never blocks the work One deliberate design choice is worth calling out, because it shows up in how the tool behaves. **Logging never fails for size.** If a summary runs long or a task touched dozens of files, the entry is trimmed on the server and stored, rather than rejected. Rejecting it would be worse than trimming it. An agent that gets a validation error reads it as "fix the arguments and try again", and spends the next several turns rewriting a summary instead of finishing your task. So the limits are applied quietly, on the way in, and the response tells the agent what was stored. ## What the failure counts are used for The tool-call and failure counts are how Pathrule answers "which files does this codebase make an assistant struggle in" from real work rather than from opinion. Two things read them. The first is a weekly grouping. Every failure is recorded as a triple: the kind of tool, the file it was working on, and a short code for how it failed. Grouped by week, that turns into a plain list of the files an assistant fails in most often, and what kind of failure it hits there. A file that shows up repeatedly under `file_not_found` is usually a stale path in your own docs or a moved module nothing updated. One under `syntax_error` is usually a file that is hard to edit safely. The second is retrieval learning. If a turn received knowledge from Pathrule and still ran into tool failures, that counts against the knowledge it was given. That signal joins the same learning loop described in [what makes knowledge rank higher](/docs/retrieval/how-retrieval-works), so knowledge that keeps showing up in turns that go badly gradually stops being chosen. ## What a failure count can and cannot see This depends on the assistant you use, and the honest answer is not uniform. File tools report properly. A failed read, edit or write arrives with its message, so it is classified and attributed to the right file. That is the case worth having, because a file path is what makes the number actionable. Shell exit status often does not. Some assistants do not report a non-zero exit code at all: a command that fails and one that succeeds arrive looking identical. Pathrule does not guess. It records what the assistant actually reported and classifies the rest as unknown rather than inventing a failure, because a wrong failure attached to a file is worse than a missing one. ## Access and scope Entries live in the workspace they were recorded in, behind the same per-user access control as memories, rules and skills. A teammate sees the activity for workspaces they can already see, and nothing else. The oldest entries age out on a schedule rather than accumulating forever. ## /docs/signals/overview # Signals overview Pathrule Signals connects what your app does at runtime with the developers and coding agents that change it. You instrument your code once with the open-source SDK. It reports errors, and the events that show a flow working, together with the code path and flow they belong to and the release that produced them. Signals groups what it receives, keeps it, makes it readable by your coding agent, and decides from runtime evidence whether a fix actually holds. ## What it does - **Instruments your code.** `pathrule.error()` and `pathrule.event()` report what happened, each linked to a code path (`node`) and a flow. See the [quickstart](/docs/signals/setup). - **Collects events.** The SDK batches them into envelopes of the [Signals protocol](/docs/signals/protocol) and retries on failure without ever rejecting. - **Groups them.** One group per environment, kind and fingerprint, so thirty-seven occurrences of the same error are one thing to look at. - **Verifies fixes.** A group is verified only after a newer release has been observed long enough and its own flow has succeeded. See [verification and lifecycle](/docs/signals/how-it-works). - **Observes across releases.** A newer release restarts observation, and an occurrence in any later release reopens the group as recurred. - **Reaches your agent.** The [agent integration](/docs/signals/agents) gives coding agents a runtime line in their context and a tool to read the groups under the path they are working on. ## Three operating modes | Mode | Account | Where events go | What you get | | --- | --- | --- | --- | | Standalone | None | An HTTP collector you run, through `httpCollector()` | The SDK and the protocol. You store and process events yourself. | | Pathrule Local | None | The Pathrule host on your machine, through `pathruleLocal()` | Storage, grouping, verification, agent access and the CLI, all local. | | Pathrule Cloud | Pathrule account | Managed ingestion, through `pathruleCloud({ key })` | Retention and agent access with your own session, on Pro, Team and Enterprise. | Standalone and Local are on every plan, are not metered and need no paid plan. Cloud Signals is part of Pro, Team and Enterprise; see [Cloud Signals](/docs/signals/plans-and-limits) and [pricing](/pricing). ## What Signals is not - **Not analytics.** There are no users, sessions or funnels. Signals records errors and flow outcomes, grouped by code path. - **Not an automatic fixer.** Signals tells you and your agent what happened and whether a fix held. Changing the code stays with you and your agent. - **Not a manual resolve button.** Recording a fix is a claim. Only runtime evidence resolves a group. ## What ships - **The SDK** (`@pathrule/signals` 0.2.0, Apache-2.0) with the HTTP collector, Local and Cloud destinations, and protocol version 1. - **Pathrule Local:** storage, grouping and verification on your machine, the agent tools and the `pathrule instrument events` command. - **Pathrule Cloud:** the managed ingest pipeline, recording fixes and verifying them with the same policy as Local, envelope deduplication and automatic retention. ## /docs/signals/setup # Signals quickstart This page adds the Signals SDK to an app, picks where its events go, and reports the errors and events that Signals groups and verifies. The SDK is the same in every mode; only the destination changes. ## Add the SDK ```bash npm install @pathrule/signals ``` The SDK is `@pathrule/signals`, licensed Apache-2.0. It runs on Node 18 or later and in current browsers (ES2022 and `fetch`). Its public npm package is being published, so check the [overview](/docs/signals/overview#release-status) for its status. ## Initialize it ```ts import { pathrule, httpCollector } from "@pathrule/signals"; pathrule.init({ destination: httpCollector({ url: "https://collector.example.com/signals", headers: { Authorization: `Bearer ${process.env.SIGNALS_TOKEN}` }, }), environment: "production", release: { version: "2.4.0", commit: process.env.GIT_SHA }, }); ``` `environment` is `development`, `preview` or `production`. ## Choose a destination **Standalone, your own collector.** `httpCollector({ url, headers?, credentials? })` posts envelopes to any endpoint that speaks the [Signals protocol](/docs/signals/protocol). No Pathrule account is involved. **Pathrule Local.** Create a local workspace once in the project, then send events to the Pathrule host on your machine. This destination is Node only. ```bash pathrule init --local ``` ```ts import { pathrule } from "@pathrule/signals"; import { pathruleLocal } from "@pathrule/signals/local"; pathrule.init({ destination: pathruleLocal(), environment: "development", release: "2.4.0" }); ``` **Pathrule Cloud.** Create a project key and pass it to the Cloud destination. Keys start with `prs_`, are write-only and are safe to ship in client code. See [Cloud Signals](/docs/signals/plans-and-limits) for key management. ```ts import { pathrule, pathruleCloud } from "@pathrule/signals"; pathrule.init({ destination: pathruleCloud({ key: process.env.PATHRULE_SIGNALS_KEY }), environment: "production", release: { version: "2.4.0", commit: process.env.GIT_SHA }, }); ``` A custom destination is any object that implements `SignalsDestination`. ## Report errors and events ```ts try { await submitOrder(cart); pathrule.event("order placed", { node: "/apps/web/checkout", flow: "checkout", meta: { outcome: "success" }, }); } catch (error) { pathrule.error(error, { node: "/apps/web/checkout", flow: "checkout" }); throw error; } ``` The second argument is a link: `node` is the code path the event belongs to, `flow` names the user-visible flow, `text` adds a short description and `meta` carries details. An event with `meta.outcome: "success"` on a group's flow is the evidence that lets a fix to that group be verified. ## Set the release `release` is a version string, an object with `version`, `commit` and `deployment`, or `null`. `releaseFromEnvironment(process.env)` reads it from common deployment variables. Without a release identity Signals can still group events, but it cannot verify a fix: `pathrule.status().verification` reports `no_release`. ## Flush before a process exits ```ts const result = await pathrule.flush({ timeoutMs: 5000 }); // result: { outcome, delivered, pending, dropped } ``` `flush()` never rejects. Its timeout defaults to 5 seconds, with a maximum of 30. In browsers the SDK sends what is pending with `sendBeacon` when the page unloads, and in Node it flushes on `beforeExit`. Call it yourself in short-lived processes such as serverless functions. ## Configuration | Option | What it does | | --- | --- | | `destination` | Where envelopes go: `httpCollector`, `pathruleLocal`, `pathruleCloud` or your own. | | `key`, `endpoint` | Cloud key and endpoint, when not passed to `pathruleCloud`. | | `environment` | `development`, `preview` or `production`. | | `release` | Version string, `{ version, commit, deployment }` or `null`. | | `scrub` | A hook that removes sensitive data before anything is sent. | | `declare` | Instrumentation points to announce; declarations are sent only in development and preview. | | `timeoutMs` | Request timeout, 10000 by default. | `pathrule.status()` reports whether verification is `ready`, `no_release` or `inactive`, and `pathrule.reset()` clears the client. ## /docs/signals/how-it-works # Verification and lifecycle Signals separates two questions: what keeps happening, and whether a fix actually held. The first is answered by grouping, the second by verification, and only runtime evidence can answer the second one. ## Groups Every event belongs to one group per environment, kind (`error` or `event`) and fingerprint. The fingerprint is derived from the event's label, flow and code path, so the same failure in the same place is one group however often it happens, and the same error in production and in preview stays separate. Each envelope carries an id that stays the same on every retry, so a retried envelope is stored once. ## Status and verification A group has a **status**: - `active`: it is happening, or it came back. - `declared`: an instrumentation point was announced but nothing has been reported yet. - `resolved`: verification proved the fix held. - `archived`: it went quiet and was closed. Archived is not resolved. And a **verification state**: | State | Meaning | | --- | --- | | `unobserved` | No fix recorded, or no newer release seen yet. | | `observing` | A newer release is running and evidence is being collected. | | `quiet` | 24 hours and at least 3 envelopes from the newer release without a recurrence. The best a group with no flow can reach. | | `verified` | The fix held: the evidence below was met. The group becomes `resolved`. | | `recurred` | It happened again in a newer release. The group is `active` again. | ## What counts as evidence A fix is **verified** when all three hold for a release newer than the one the fix was recorded against: - at least 60 minutes of observation, - at least 3 envelopes from that newer release, - at least 3 successes of the group's own flow, reported with `meta.outcome: "success"`. Some things never count: the baseline release, events with no release identity, and anything observed before the fix was recorded. A newer release starts observation over. If the newer release goes silent for 45 minutes, a `quiet` state goes stale. Without a release identity verification is blocked and the SDK reports `no_release`. ## Recording a fix When you or your agent fix something, the fix is recorded against the group (see [agent integration](/docs/signals/agents)). Recording is a claim, not proof: it moves nothing to `resolved` by itself. Only verification does. There is no manual resolve, and any occurrence in a newer release, even after `verified`, sets the group to `recurred` and back to `active`. ## Retention in Pathrule Local - Up to 5,000 groups per workspace. - An unresolved group expires after 14 days without an occurrence in production, 7 days in development or preview, and 30 days for a declaration. - Resolved groups and their history are kept for 90 days. - Envelope ids are remembered for 2 days, which is what makes retries safe. Cloud retention is on the [Cloud Signals](/docs/signals/plans-and-limits) page. ## /docs/signals/protocol # Protocol and collectors In Standalone mode the SDK sends to an HTTP collector you run. This page is what that collector receives and how it should answer. Pathrule Local and Pathrule Cloud speak the same protocol, so nothing here changes when you switch destinations. ## The envelope The protocol is version 1. The SDK sends one envelope per `POST` as `application/json`; the beacon sent while a page unloads uses `text/plain`. An envelope is at most 32,768 bytes and carries at most 50 items. | Field | What it is | | --- | --- | | `schemaVersion` | The protocol version. | | `id` | Up to 64 letters, digits, `_` or `-`. The same on every retry, so a collector can store an envelope once. | | `key` | The project key. Cloud only. | | `environment` | `development`, `preview` or `production`. | | `release` | The release identity, up to 120 characters. | | `connection` | How the SDK is connected. | | `items` | The signals and declarations in this envelope. | Each item has `type` (`signal` or `declaration`), `kind` (`error` or `event`), `fingerprint`, `countDelta`, `node` (the code path), `flow`, `label`, `message` and `metadata`. Repeated occurrences are summed into `countDelta`, so a collector counts with it rather than counting items. ## Responses and retries | Response | What the SDK does | | --- | --- | | `2xx` | Delivered. | | `401`, `403` | Stops sending for good. | | `408`, `429`, `5xx` | Retries. | | Any other `4xx` | Drops the batch. | Retries happen after 1, 5 and 15 minutes, at most 4 attempts, and the SDK keeps at most 20 envelopes waiting. A `Retry-After` header is read as a number of seconds. ## Running your own collector A collector does three things: authenticate the request, validate the envelope, and store or forward it. ```ts import { normalizeEnvelope } from "@pathrule/signals/protocol"; // In your POST handler, after checking your own Authorization header: const envelope = normalizeEnvelope(body, { requireKey: false, bytes: rawBody.length }); ``` Pass `requireKey: false` when you authenticate another way, such as the bearer header in the [quickstart](/docs/signals/setup), and pass the raw size so the size limit is enforced. Then: - Store an envelope once per `id`; retries reuse it. - Group items by environment, kind and fingerprint, the same way Pathrule does. - Answer `2xx` as soon as the envelope is safe, and `401` or `403` only when the client should stop. ## /docs/signals/agents # Agent integration Signals is built to be read by the coding agents that change your code. An agent sees a short summary before it acts, can read the groups under the path it is working on, and can record a fix. It cannot declare its own fix verified. ## The runtime line When there are active groups under the path an agent is working on, a single line reaches its context through Pathrule's [hooks](/docs/hooks/how-hooks-work) and `pathrule_get_context`: ```text Runtime: 2 active issues under apps/web/checkout (1 came back after a fix). Inspect with pathrule_runtime_events. ``` It carries counts only. The reported messages never travel in this line. ## Reading groups `pathrule_runtime_events` is read only. It takes the workspace, and optionally a `group_id`, a `path`, a `kind`, an `environment`, a `status`, a `verification` state, a `limit` (1 to 100, 20 by default) and a `cursor`. It returns the groups with their revision, verification state and any recorded correction, a cursor for the next page, and coverage. Everything it returns is marked as untrusted observation. Error messages and metadata come from a running app, so an agent treats them as data to investigate, never as instructions. ## Recording a fix `pathrule_runtime_events_resolve` records a correction against a group. It takes the `group_id`, the `expected_revision` the agent read, an `idempotency_key`, and optionally a `baseline_release`, a `note` of up to 500 characters and up to 20 knowledge references. It answers `recorded`, `replayed` or `refused`, with a next step. Recording is a claim, not proof. The group stays where it is until a newer release brings the evidence described in [verification and lifecycle](/docs/signals/how-it-works). Recording a fix works the same way in Pathrule Local and on Pathrule Cloud. ## In a terminal ```bash pathrule instrument events --path apps/web/checkout --verification recurred ``` `pathrule instrument events` lists groups with the same filters: `--path`, `--kind error|event`, `--environment`, `--status active|declared|resolved|archived`, `--verification unobserved|observing|quiet|verified|recurred`, `--group `, `--limit` and `--cursor`. Add `--json` for scripts. ## Setting up Cloud through an agent On Pathrule Cloud an agent can set Signals up for you. `pathrule_instrument` shows the workspace's Signals status and a setup guide. `pathrule_instrument_activate` records your consent, creates a project key and adds the SDK to the project as a source file, so nothing is installed from a package registry. ## /docs/signals/plans-and-limits # Cloud Signals Pathrule Cloud runs Signals for you: managed ingestion, retention, and access for your agents with your own session. Standalone and Local Signals stay free and unmetered on every plan; this page is only about Cloud. ## Project keys The Cloud destination authenticates with a project key. Keys start with `prs_`, are write-only and are public by design, so they are safe to ship in browser code: a key can send events but read nothing. ```bash pathrule instrument status pathrule instrument keys create --label web pathrule instrument keys list pathrule instrument keys revoke --yes ``` `pathrule instrument sdk` adds the SDK to the project as a source file. Every command takes `--workspace`. An agent can do the same through `pathrule_instrument_activate`; see [agent integration](/docs/signals/agents). ## Reading events `pathrule instrument events` and the `pathrule_runtime_events` tool read Cloud groups with your own session, so an agent sees only workspaces you can see. ## Plans | Plan | Standalone and Local Signals | Cloud Signals | |---|---|---| | **Solo** | Yes | No | | **Pro** | Yes | Yes | | **Team** | Yes | Yes, shared across the organization | | **Enterprise** | Yes | By contract | Events are counted per month on a UTC calendar-month boundary, and a Team organization shares one allowance across its workspaces. See the [pricing page](/pricing) for what each plan includes. ## Retention Groups follow the same lifecycle as in [Pathrule Local](/docs/signals/how-it-works#retention-in-pathrule-local): an unresolved group expires after 14 days without an occurrence in production, 7 days in development or preview, and 30 days for a declaration. Archived groups are compacted after 90 days, and compacted records and usage history are deleted after a year. ## What Cloud runs for you - the managed ingest pipeline, - recording fixes on Cloud, and verifying them with the same policy as Local, - envelope deduplication, - automatic retention. ## /docs/patterns/overview # Patterns overview A pattern is a ready-to-use package of team knowledge for a specific stack or a specific development problem. Instead of starting a workspace empty and writing every memory, rule and skill by hand, you add a pattern and your AI assistant starts the project already knowing the conventions that stack tends to need and the mistakes it tends to make. Each pattern is a bundle of the same three content types Pathrule already uses, and every piece arrives pre-scoped to the path it belongs to. A rule about server components lands on `/app`, a billing memory lands on the billing service, a review skill lands at the root. Nothing is dumped into one global file. ## Why patterns exist Most repositories share the same early questions. How should a Next.js App Router project split server and client components? Where do you keep Supabase row-level security rules? What is the safe way to handle a Stripe webhook? Why does a query that was fast in development deadlock in production? The answers are well understood, but every team rediscovers and re-types them. Patterns capture those answers once, as path-scoped Pathrule content, so a new workspace can adopt them in seconds: - **Pre-scoped, not pasted.** A pattern is not a prompt blob. Each piece declares the path it lives at, so your assistant only sees it where it is relevant. A UI tweak never has to read a database rule. - **Typed, not freeform.** A pattern is made of memories, rules and skills, the same types you write yourself. An imported rule keeps its scope type and priority; an imported skill is invocable by name. - **Composed to fit the topic.** The mix of rules, memories and skills differs per pattern. A framework pattern leans on rules for its hard conventions, a workflow pattern leans on skills you run as checklists. - **Yours after import.** Importing a pattern is a one-time seed, not a live subscription. The pieces become ordinary content in your workspace and you edit them like anything else. ## The catalog The public catalog lives at [pathrule.io/patterns](/patterns). It holds 150 patterns, every one first-party and published under Apache-2.0, organised into eight categories: - **Framework** for app and platform frameworks, from Next.js App Router, Nuxt, SvelteKit, Astro and React Router to Django, Rails, Laravel, Spring Boot, ASP.NET Core, SwiftUI, Flutter, Expo and Unity. - **Frontend** for components, forms, state, styling, accessibility, Core Web Vitals, hydration, internationalization and offline behavior. - **Backend** for data access, ORMs, queues, search, APIs, authentication, multi-tenancy and database performance. - **Billing** for payments, subscriptions, invoicing and tax, checkout, payouts, refunds and disputes. - **Infra** for containers, serverless runtimes, CI/CD, infrastructure as code, observability, caching, DNS and TLS. - **Workflow** for code review, debugging, dependency upgrades, Git workflows, releases, incidents and onboarding. - **AI** for agents in production, agent memory, evaluations, observability, guardrails, fine-tuning and verifying AI-generated code. - **Security** for account takeover and MFA, service credentials, rate limiting, encryption, authorization, enterprise SSO and least privilege. The catalog page has a category sidebar and a search box. Each pattern has its own page showing: - a contents summary, how many rules, memories and skills it carries, derived from the bundle itself - a path map of every target path, and the full list of pieces grouped by path - why the pattern exists: the problem it solves, who it is built for, and the mistakes it keeps your assistant from making - the token used to add it, with a copy button, and a manual copy of the full bundle - its license, version and last updated date, with a link to the source Every pattern is also served as plain markdown at `/patterns//raw` (the "View as markdown" link on the page), so an AI assistant can read the whole bundle directly from a shared link. ## How a pattern fits the rest of Pathrule A pattern does not introduce a new runtime concept. It is a packaging format over the model you already know: - The pieces are [memories, rules and skills](/docs/start/core-concepts). - Each piece's path uses the same [path scope](/docs/start/core-concepts#path-scope) rule as content you write yourself. - Once imported, the pieces surface through the same [hooks](/docs/hooks/how-hooks-work) and the same just-in-time retrieval as the rest of your workspace. That is the whole idea: a pattern is a curated head start, expressed in the exact shape your assistant already reads. ## What to read next - [Anatomy of a pattern](/docs/patterns/anatomy) breaks down the content model: pieces, paths, versioning and the open package behind the catalog. - [Importing a pattern](/docs/patterns/importing) covers the token, the preview, and removing a bundle later. - [Core concepts](/docs/start/core-concepts) explains memories, rules and skills if you are new to the model. ## /docs/patterns/anatomy # Anatomy of a pattern A pattern is deliberately simple. It is a small bundle of typed pieces plus the metadata needed to display it, version it and match it to a project. Understanding the shape makes it obvious what you are getting when you import one. ## A pattern is a bundle of pieces Every pattern carries a list of pieces. Each piece is exactly one memory, one rule or one skill, and it knows where it should land. A piece declares: - **`kind`**: `memory`, `rule` or `skill`. This decides which content type it becomes on import. - **`nodePath`**: the workspace-relative path it belongs to, for example `/app`, `/services/billing`, or `/` for the root. This is the scope the piece is delivered with. - **`title`**: the memory title, rule name or skill name. - **`summary`**: a one-line description shown in the bundle list, separate from the body. - **`body`**: the full markdown content. This is exactly what gets written into your workspace, with no transformation. Because each piece names its own path, a pattern is path-scoped by construction. The bundle is not a single document that has to be filed somewhere; it is a set of pieces that already know where they go. ## Type-specific metadata Some pieces carry extra fields that match their content type, and these survive import intact. - **Rule pieces** set a **scope type** (`folder`, `file_type` or `project`) and a **priority** (`high`, `medium`, `low`). A rule that leaves them out is imported as a project rule at medium priority. An imported rule keeps both, so a high-priority folder rule from a pattern surfaces exactly like one you wrote yourself. - **Skill pieces** carry a skill name and optional tags, and their one-line summary becomes the skill's description. On import the skill is also tagged `pattern:`, so you can find every skill a pattern brought in as a group. After import the skill is discoverable and invocable by name, the same as any other workspace skill. - **Memory pieces** need no extra metadata; the body and path are enough. Rule pieces also carry an **enforcement mode** (`advisory` or `strict`), and the manual copy labels each rule with one. Import does not carry it: an imported rule arrives as an advisory rule that rides along as context, whatever the catalog labels it. Blocking an edit needs an executable constraint that a person has approved, the same as for any rule, as described in [Rules as guardrails](/docs/hooks/rules-as-guardrails). That keeps blocking a decision a person on your team makes, not something a catalog switches on. For the underlying meaning of scope, priority and enforcement, see [Core concepts](/docs/start/core-concepts#priority-and-enforcement). ## Counts and paths are derived A pattern never hand-maintains its own summary. The "4 Rules, 2 Memories, 1 Skill" line and the list of target paths on each catalog page and in the package README are computed from the pieces. That means the displayed contents can never drift from what the bundle actually contains. Add a rule to a pattern and its count updates on its own. ## Versioning and freshness Each pattern is versioned and dated so you can tell what you are adopting and when it last changed: - **`version`** is a display version like `1.0.1`. It is shown on the catalog page and in the import preview. The import token does not carry it: `::pathrule:package:` always means the version your client ships. - **`updatedAt`** is the date of the last content change. It is the "Updated" date on the catalog page and the last-modified date in the sitemap. - **`changelog`** is a list of human-readable entries, newest first, recording what changed between versions. Every pattern in the catalog carries one, readable in the open package. Versioning matters because import is a one-time seed (see [Importing a pattern](/docs/patterns/importing)). Your copy never changes underneath you, and Pathrule does not track which version you imported or notify you when a newer one is published. Compare the version and updated date on the catalog page with when you imported, and read the changelog to see what moved. [Importing a pattern](/docs/patterns/importing#seed-not-subscribe) covers how to bring a newer version in. ## Display metadata Besides the pieces, a pattern carries what the catalog needs to present it: a name, a one-line tagline, a longer description, a category (one of Framework, Frontend, Backend, Billing, Infra, Workflow, AI and Security) and an icon. Every pattern in the catalog also explains itself with the problem it solves, the audience it is built for, and a list of the mistakes it keeps your assistant from making. The catalog page shows all three under "Why this pattern". ## Matching metadata A pattern can declare what kind of project it fits, under an `appliesTo` block: relevant paths, stack tags (for example `nextjs`, `react`) and dependency names. Every pattern in the catalog declares one. The web catalog uses the stack tags for search. The import preview hands the same block to your assistant, which compares it with your project's tree and stack before writing anything and asks you to confirm when the pattern does not appear to fit. ## The open package The catalog is backed by a single open package, `@pathrule/patterns`, published on npm under Apache-2.0. The package is pure and serializable: it carries the pattern definitions, their types and a few helper functions, with no dependency on any UI or cloud code. That keeps it readable as plain data and lets every surface consume the exact same bundles. Adding a pattern is one new entry registered in that package. Because the package is the single source of truth, the website catalog, the import tooling and the markdown views all render the same content. The Pathrule MCP server carries its own copy of the package, which is why a newly published pattern becomes importable once the release of Pathrule you run includes it. ## What to read next - [Importing a pattern](/docs/patterns/importing) shows how a bundle gets written into your workspace and how to remove it. - [Patterns overview](/docs/patterns/overview) is the higher-level picture if you skipped it. - [Writing rules](/docs/content/rules) and [Writing skills](/docs/content/skills) cover the piece types in depth. ## /docs/patterns/importing # Importing a pattern You can adopt any pattern in two ways. You can paste its token into any connected AI assistant, which lets Pathrule write the pieces onto the right paths for you, or copy the bundle by hand from the catalog. ## The reference token Every pattern has a reference token of the form: ```text ::pathrule:package: ``` For example, the Next.js App Router pattern is `::pathrule:package:nextjs-app-router`. The token is shown on each catalog page, ready to copy. The `::pathrule:` prefix is a reserved namespace. It is matched before the `::skill-name` invocation path, so a pattern token is never mistaken for a skill and never triggers skill discovery. That separation holds in the prompt hook and in the context request alike. Paste the token as plain text. Like a skill invocation, a token inside backticks or a code block is treated as quoted code and ignored. You can put several tokens in one prompt; each pattern is picked up once. ## Importing by token To add a pattern, paste its token into a prompt in a connected workspace. From there Pathrule does the rest: 1. **It recognises the token.** When Pathrule builds the context for your prompt, it detects the `::pathrule:package:` marker and surfaces an import directive for that slug. 2. **It previews before writing.** A dry run resolves the pattern and returns its version, the problem it solves, its pieces and the paths it intends to use, without changing anything yet. This preview also reports the pattern's declared paths, stacks and dependencies, so the assistant can line the pattern up against your actual project. 3. **It picks paths that match your tree.** A pattern declares suggested paths, but real repositories differ. The assistant chooses a base that matches your layout and re-roots the pattern's paths under it, so the pieces land where they actually belong. In a monorepo, a Next.js pattern's `/app` rules can land under `/apps/web/app`. 4. **It confirms on a mismatch.** If the pattern targets a stack your project does not appear to use, for example a React Native pattern in a project with no Expo, the assistant stops and asks you whether and where to add it rather than importing blindly. 5. **It writes the bundle.** On confirmation, each piece is created through the normal write path: a memory becomes a memory, a rule becomes a rule with its scope type and priority, and a skill becomes an invocable skill tagged with the pattern it came from. Missing nodes along each path are created on demand. The assistant then relays a one-line summary, for example how many rules, memories and skills were imported, how many were already present, and how many failed. After import, the pieces are ordinary workspace content. They surface through the same hooks and retrieval as anything you wrote yourself, and you edit them the same way. An imported rule arrives advisory: it rides along as context and does not block an edit unless a person approves an executable constraint for it (see [Rules as guardrails](/docs/hooks/rules-as-guardrails)). Import writes as you. Each piece goes through the same access check as any other write, so on a team you need write access to the target workspace: a Viewer cannot import. See [Roles and permissions](/docs/teams/roles-and-permissions). ## Importing by manual copy You do not need the token to use a pattern. Each catalog page has a "Manual copy (full bundle)" action that copies the full bundle as plain markdown, with every piece labelled by kind and target path, and every rule labelled with its scope and priority. Paste that into your assistant, or into your own notes, and recreate the pieces wherever you want. This works with no setup and no account. Every pattern is also available as raw markdown at `/patterns//raw`, which is convenient when you want an assistant to read the whole bundle from a link. ## Seed, not subscribe Importing a pattern is a one-time seed. The copy in your workspace is yours from that moment on; it does not stay linked to the catalog and it will not change underneath you. Pathrule does not record which version you imported and does not notify you when a newer version is published, so nothing ever syncs over content you have already adapted. To see whether a pattern moved since you imported it, compare the version and updated date on its catalog page, and read its changelog in the open package. Re-importing does not bring changes in, because every piece whose title is already present is skipped. To take a newer version, remove the bundle and import it again, knowing that this replaces your edits to the imported pieces. If you only want one improved piece, copy it from the catalog page by hand. ## Re-importing and removing - **Re-import never duplicates.** Running the same import again skips every piece whose title is already present and reports what was added and what was already there. A memory counts as present when a memory with the same title exists at its path; a rule or a skill counts as present when one with the same name exists anywhere in the workspace. Skipped pieces are left exactly as they are, edits included. A piece you renamed after import is no longer recognised, so a re-import adds it again. - **Removal is one step.** A pattern's definition is its own manifest of titles and paths, so you can ask your assistant to remove the pattern and a single call undoes the whole bundle. If you imported under a base path, give the same base when you remove; pieces that cannot be found there are reported as not found rather than treated as errors. ### What removal touches Removal finds each piece by its title at its path, not by remembering what the import created. That has three consequences worth knowing before you run it: - **Edited pieces are removed too.** An imported memory, rule or skill that you have since edited is removed along with your edits, as long as its title and path are unchanged. - **Your own item with the same title is removed.** If you wrote a memory, rule or skill yourself with the same title as one of the pattern's pieces, at the same path, removal deletes it as well. Titles are compared without regard to letter case. - **Renamed or moved pieces stay.** Renaming a piece or moving it to another path takes it out of removal's reach, which is the way to keep one piece while removing the rest. Removed items are archived rather than erased. On a Cloud workspace they stay in the workspace archive until permanently deleted, where an owner or admin can restore them from the web console settings under **Workspace**, **Archive**. ## Where it works Token import and removal use the local stdio MCP tools, including when that runtime is attached to a Cloud workspace. Remote MCP does not expose these helpers. A remote client can read the raw bundle and author selected entries with its available knowledge tools. Import behaves the same in Claude Code, Codex, Cursor, Windsurf and GitHub Copilot connected through Pathrule CLI or the VS Code extension. Import and removal work the same on a local workspace and on a Pathrule Cloud workspace. In Claude Code and Codex the prompt hook spots the token before the agent acts. Cursor, GitHub Copilot and Windsurf have no prompt hook, so there, the assistant learns the same import and remove workflow from the context request and the protocol guidance in its instruction files. ## What to read next - [Patterns overview](/docs/patterns/overview) for the bigger picture. - [Anatomy of a pattern](/docs/patterns/anatomy) for what is inside a bundle and how versioning works. - [How hooks work](/docs/hooks/how-hooks-work) for how imported pieces are delivered once they are in your workspace. ## /docs/teams/shared-knowledge # Shared knowledge and conflicts Pathrule is a shared knowledge layer, so two people will eventually edit the same memory, rule, or skill at the same time. Cloud writes are shared, overlaps are checked when you save, and you decide how to resolve them. ## Reading the current state A memory, rule or skill written to a Cloud workspace becomes part of that shared workspace. The current Cloud backend does not provide a real-time subscription that pushes every teammate's edit into an open view. Refresh the knowledge view or make another knowledge request to read current state. Local hooks and instruction files use prepared workspace knowledge; run `pathrule sync` to refresh those files and indexes. Do not assume an already prepared session has received a teammate's latest edit. A local workspace lives on one machine. Other people do not receive its changes until you copy the knowledge into a shared Cloud workspace. ## Overlap detection at save time Pathrule does not lock an item while someone has it open. Locking would stall the team for edits that never actually collide. Instead, every save carries a version token (the same token described in [Writing memories](/docs/content/memories)), and overlap is detected only when two saves target the same starting version. | Situation | What happens | |-----------|--------------| | You save and your starting version is still current | The save goes through normally | | You save but a teammate saved a newer version since you started | A conflict, resolved with the choices below. Your version is not saved until you choose | Because the check is scoped to the individual item, teammates editing different memories never block each other. ## Resolving a conflict In Pathrule for VS Code, a memory, rule or skill is a markdown tab. When a save hits a conflict, VS Code tells you the content changed remotely and that your version was not saved, and offers three choices: | Choice | What it does | |--------|--------------| | Reload | Loads the current version and drops your unsaved edits. | | Copy My Version & Reload | Copies your text to the clipboard first, then loads the current version, so you can reapply what you meant. | | Keep Mine (Overwrite) | Saves your version over the current one. This discards the other person's change, so it is an explicit choice. | Nothing is overwritten until you pick one. Through MCP, an assistant can pass the version it last read; on a mismatch it gets the current version back, re-reads it, and merges its change in rather than overwriting. ## Change history Every change to a memory, rule, or skill is versioned and recorded. - Each change keeps who made it, when, and whether it came from a person or an AI client. - In VS Code, the **Info** action shows an item's version, who created it, who last edited it and its source. The history is for visibility. It tells you how an item reached its current state, which is the same question a [refresh task](/docs/content/suggestions) helps answer when knowledge starts to drift. ## What to read next - [Writing memories](/docs/content/memories) for how the version token works on a single item. - [Suggestions and self-audit](/docs/content/suggestions) for how stale or conflicting knowledge gets flagged. - [MCP overview](/docs/mcp/overview) for how external AI clients read the synced context. ## /docs/teams/roles-and-permissions # Roles and permissions Pathrule starts as a solo tool and grows into a team product. When you invite colleagues, the question becomes who can see and change what. This page covers the roles you assign, how access narrows from organization to workspace, and where the check actually runs. The short version: roles are assigned at the organization level, access can be narrowed per workspace, and every read and write on a Pathrule Cloud workspace is checked by the database against your signed-in user. The same check applies whether the request comes from the web console at [app.pathrule.io](https://app.pathrule.io), Pathrule CLI, the VS Code extension, or the MCP server an AI client speaks. A local workspace created with `--local` has no account and lives on one machine, so roles do not apply to it until you move it to the cloud. ## The four roles Roles are assigned per person at the organization level. An owner or admin invites a colleague by email and picks their role, Editor by default; the colleague accepts the invite to join. Invite from **Members** in the web console, or from the terminal: ```bash pathrule invite colleague@example.com --role viewer ``` | Role | Can do | | --- | --- | | **Owner** | Organization administration and ownership controls. The organization must retain an owner. | | **Admin** | Manage membership and permitted roles, and administer workspaces. | | **Editor** | Read and write content (memories, rules, skills) in the workspaces they can access. The everyday contributor role. | | **Viewer** | Read content in the workspaces they can access. No writes. | A few guardrails follow from this: - Ownership changes require owner authority, and the organization must keep an owner. - Ownership and membership changes are checked on the server, including the requirement to retain an owner. Membership changes require a current authorized session. Sensitive workspace archive and delete actions additionally require fresh authentication. ### Seats and plans Every person in the organization takes a seat, whatever their role. - **Solo** and **Pro** are for one person. They have no invites; to work with others, move to Team. - **Team** is billed per seat, at least two, the owner included. Inviting beyond the seats you pay for needs another seat; with fewer seats than members, everyone keeps access and new invitations wait. - **Enterprise** seats are agreed with sales. Seats and invoices live under **Billing** in the web console; `pathrule billing` opens it from the terminal. See [Pathrule Web](/docs/surfaces/web). ## Workspace access: organization-wide or private A role sets what a person can do. A workspace's access mode sets who can reach it at all. Each workspace is one of two modes. - **Organization-wide.** Every member of the organization has access, at their org role. - **Private.** Only people explicitly added to the workspace have access. Org membership alone is not enough. Owners and admins switch the mode in the web console settings under **Workspace**, **Access**. When a workspace becomes private, only its explicit workspace members have access. Review and add the people who need it; organization membership alone no longer grants access. Inside a private workspace, a person's workspace role decides what they can do there, so you can give someone a different level of access than they have elsewhere. ## Losing access is non-destructive Permission changes never destroy work and rarely hide it. - **Lose write access** (for example, moved from Editor to Viewer) and nothing disappears. You can still read everything you could before; writes from you, or from an assistant working as you, are refused. - **Lose access to a workspace** (removed from a private workspace, or from the organization) and only then does its content drop out of view for you. The content stays with the team. The same boundary reaches the assistant. When an AI client tries to write where a member cannot write, the MCP tool call comes back with a clear permission-denied result the assistant can relay to you in plain language, rather than failing silently or appearing to succeed. The context an assistant receives, and the instruction files Pathrule writes for it, only ever come from workspaces that member can read. ## Where the check runs None of this is enforced in the application you happen to be using. Every read and write on a Cloud workspace runs through a database access check resolved against your signed-in user, your organization membership, and the workspace's access mode. Access checks are part of the server’s database operations, rather than a hidden button in the interface. - **One check for every surface.** The web console, Pathrule CLI, the VS Code extension, the local MCP server and Remote MCP all go through the same database-enforced access control. A change from the terminal and a write from an AI client are gated by the same rules. - **No shared admin key.** Each surface carries a short-lived, per-user token, never a shared service key that could unlock another team's data. A leaked client can only ever reach what that user already can. - **Server-side resolution.** Membership and workspace roles are resolved on the server, not trusted from the client, so an edited request cannot grant itself access it was not given. For the full picture of how the cloud is gated, see the [security overview](/security). ## On self-hosted Enterprise self-hosted runs the same role and permission model in your own Cloudflare account. The roles and the workspace access modes behave the same way; the difference is that the data and the database live in your account. Single sign-on through your own identity provider is arranged under the Enterprise agreement and maps onto the same organization roles described here. See [Enterprise self-hosted](/docs/editions/self-hosted) for how that deployment works. ## /docs/teams/team-profiles # Who is the reference for what An assistant that knows your codebase can still get one thing badly wrong: it decides something that was not its call. It renames a public field, changes a pricing rule, restructures a module, and it does so with no idea that a person on the team is the reference for that area and would have answered in one sentence. Team member profiles close that gap. Each person in your organization gets a profile that answers a single question, who is the reference for which area, and a short version of that answer is compiled into what every agent reads before its first tool call. ## A profile belongs to the team, not to a repository The profile is organization scoped and workspace independent. Someone who is the reference for payments is the reference for payments whether the work happens in the API repository, the mobile app, or a service that did not exist last month. Tying it to one workspace would mean re-establishing the same fact per repository, which is how a directory goes stale. ## Two halves, and only one of them is inferred A profile has a derived half and a declared half, and the split is deliberate. **Derived: the areas you actually work in.** Pathrule already records a short entry per piece of work, and it already knows who authored which memory and rule at which path. Those two counts, work logged against a path and knowledge authored at that path, are the evidence. Nothing else is read: not your code, not your commit messages, not how long anything took. The window rolls, so an area you left behind fades out of your profile instead of following you for years. **Declared: your decision scope.** This one is typed by the person and never derived. Authority over a product decision does not follow from touching files, and a system that inferred it from activity counts would be inventing it. The person who touched the billing code most last month may be the last person who should be deciding a pricing rule. So Pathrule asks instead of guessing. The same rule covers your display name, your pronouns and how available you are: your own words, in your own row. ## You see your own profile, and you can correct it You can read exactly what an agent is told about you and your team: the team block is the **Team** section at the end of the instruction files Pathrule writes for your clients, such as CLAUDE.md or AGENTS.md. A derived list is not the last word. When a person has written their own list of areas or tags, theirs wins over the derived one, and the presence of that list is what marks the answer as corrected rather than inferred, so nothing quietly overwrites it on the next derivation. The database enforces the boundary rather than the interface. A person can write their own profile row and nobody else's. ## What the agent actually gets Not the profile table. A short block, appended to the instruction files your agents read first, that looks like this in substance: - the team name, and the person the file belongs to, with a few of their own areas - a few colleagues, each with the single area they are the reference for - any declared decision scopes, kept to a short list - one instruction: address the user by name, and when a decision touches another person's area, point at its owner instead of deciding for them That last line is the point of the whole feature. A list of names with no instruction is data an agent scrolls past. So the instruction is reserved before anything else is measured, and if the block would end up with the instruction and nobody to point at, the block is dropped entirely rather than shipped as noise. ## What the block cannot say The block accepts names, paths, tags and a declared scope. There is no field for a performance claim, a speed claim, a quality claim or a seniority claim, and free text is capped in length and collapsed to a single line. This is structural rather than a review guideline: a compiled instruction file cannot grow a paragraph of opinion about a colleague here, because there is nothing for such a sentence to travel in. It is also small on purpose, a small fixed budget including its heading. When there is more to say than the budget allows, whole lines are dropped from the least valuable end rather than a sentence being cut in half, so a trimmed block still reads as something an agent can act on. One block, once per file, never a second one. ## Why it rides the compiled file Pathrule has two ways to reach an agent: the compiled instruction files, read once at the start of a session, and the [per-turn hook](/docs/hooks/how-hooks-work), which in Claude Code and Codex reaches the model on every prompt. The hook is the right channel for what changes with the request. This block does not change with the request, so paying for it on every prompt of a long session would be paying many times for one constant fact. It sits at the very end of the file for a related reason. A cached instruction prefix is invalidated from the first changed byte onward, and team membership changes far more often than your workspace knowledge does. Keeping the volatile block last leaves everything above it byte identical when somebody joins. ## Consent Visibility is per person and defaults to being visible to your team. A profile set to private is removed from every team-facing read, including the compiled block, so no agent on the team is told what that person is the reference for. The choice lives in the same row the profile does and the database applies it to every query, so there is no surface where a private profile leaks because one screen forgot to filter. ## What to read next - [Roles and permissions](/docs/teams/roles-and-permissions) for who can read and change what in a workspace. - [How hooks work](/docs/hooks/how-hooks-work) for the other channel, the one that carries what changes per prompt. - [What an AI session records](/docs/content/activity-log) for the activity entries the derived half is counted from. ## /docs/mcp/overview # MCP overview Pathrule speaks the Model Context Protocol. The protocol is what your AI coding assistant uses to call into external tools and read external state. Pathrule shows up to the assistant as a normal MCP server, so any client that can speak MCP can use it. There are two ways to connect. The local server comes with Pathrule CLI and the Pathrule VS Code extension: the assistant talks to it over stdio, and on a Cloud workspace the runtime talks to Pathrule Cloud over HTTPS. For clients that connect to hosted servers, Remote MCP accepts a direct connection over Streamable HTTP with OAuth sign-in and scoped access to your workspace. Local stdio and Remote MCP have different tool catalogs and schemas. Inspect `tools/list` on the connected server. Pathrule does not automatically upload your repository source code; local project-learning tools can inspect files attached to a finding to validate it. ## What the server exposes Pathrule's MCP surface is typed and grouped around the data model. The core tools below cover everyday context, content and activity flows; the [tools reference](/docs/mcp/tools-reference) is the canonical inventory. The local server advertises its whole set, reads and writes alike, from the first `tools/list`, so nothing has to be unlocked before the first write and the list does not change mid-session. A lazy mode that holds write tools back until they are needed is available as an opt-in; see [Local lazy-write control](/docs/mcp/tools-reference#local-lazy-write-control). ### Read tools - `pathrule_get_context`. The primary entry point. Given the current working directory and the user's intent, it returns the right slice of memories, rules, and skills for that path. The response carries the workspace overview, the rules and memories that already match, and a hint about what to read next. - `pathrule_read_memory`, `pathrule_read_rule`, `pathrule_read_skill`. Fetch the full body of a specific node by id when the assistant wants to cite or follow it. - `pathrule_get_tree`, `pathrule_get_node`. Inspect the workspace structure or a specific node. - `pathrule_list_memories`. Enumerate the memories under a path, useful for discovery prompts. ### Write tools - `pathrule_write_memory`, `pathrule_write_rule`, `pathrule_write_skill`. Create content at a workspace path. Missing nodes along the path are created on demand. - `pathrule_update_memory`, `pathrule_update_rule`, `pathrule_update_skill`. Edit an existing record. Optimistic concurrency is enforced with a version id. - `pathrule_delete_memory`, `pathrule_delete_rule`, `pathrule_delete_skill`. Soft delete with a thirty day undo window. ### Activity and housekeeping - `pathrule_log_activity`. Called after any file modifying response so the team can see what the assistant did and where. - `pathrule_goto`. Move the assistant's working node when the user asks for content from a different scope. - `pathrule_ping`. A health check that confirms the server is wired up and shows the runtime's view of the working directory. ## How hooks fit in On clients that support hooks, hooks are how Pathrule keeps the assistant fast. At session start and around tool calls, the hook supervisor reads a cached slice for the current working directory and hands it to the agent as context. This avoids a synchronous MCP round trip for the common case. The session-start hook also delivers the Pathrule protocol itself, so on a hook-capable client the instruction file in your repo stays a short note. Not every client is reached the same way: - **Claude Code and Codex** have hooks including a prompt-submit hook, so the relevant knowledge arrives with each prompt, before the agent acts. - **Cursor and GitHub Copilot** have session and tool hooks but no prompt-submit hook. Context arrives at session start and around tool calls. - **Windsurf** has no hooks. It reads a Pathrule rules file at session start and uses the MCP tools for everything deeper. When the hook is enough, the assistant does not need to call `pathrule_get_context`. It already has the right slice. MCP tools are reserved for two scenarios. 1. The assistant wants more than the hook surfaced. For example, a discovery prompt that needs the full memory body, or a refactor that touches a path the hook did not anticipate. 2. Something is worth keeping. The assistant proposes a memory, rule, or skill and writes it once you confirm, or you ask it to write one directly. Writes go through the write tools, and each one is marked as written by the assistant and versioned, so you can review or undo it. See [How hooks work](/docs/hooks/how-hooks-work) for the underlying mechanics. ## Agent integrations Pathrule is the intelligence layer; your coding agent stays the execution engine and keeps its own model provider. The CLI and the VS Code extension connect the agents you already use to the same workspace through each client's supported hooks, instruction files and MCP. - **Claude Code and Codex**: hooks including a prompt-submit hook, instruction files and the local MCP server. Both can also connect to Remote MCP. - **Cursor and GitHub Copilot**: session and tool hooks, instruction files and the local MCP server. The VS Code extension registers the server for Copilot agent mode. - **Windsurf**: a Pathrule rules file and the local MCP server, with no hooks. - **Any other MCP client**: connects over stdio. Add the Pathrule MCP command to your client's config and it will see the same tool surface. - **Clients that connect to hosted servers**: point them at Remote MCP over Streamable HTTP and sign in with OAuth. Remote MCP installs no hooks and writes no local files. ## What to read next - [How hooks work](/docs/hooks/how-hooks-work) for what happens between the cache and the editor. - [Core concepts](/docs/start/core-concepts) for the data model the tools operate on. - [CLI install](/docs/cli/install) for setting up the runtime that hosts the server. ## /docs/mcp/one-contract # Local and Remote MCP Your workspace knowledge is shared across the Pathrule surfaces you connect. MCP provides the transport and tool discovery. **The local and hosted servers have different capabilities and schemas.** An integration should inspect `tools/list` on the server it actually uses. ## Choose a surface | Surface | Connection | What it adds | | --- | --- | --- | | CLI | Local stdio MCP, instruction files and supported hooks | Repository setup, knowledge authoring, project learning and local context delivery | | VS Code extension | The same local runtime | Knowledge beside your code and client setup from the editor | | Local Console | `pathrule ui` on loopback | Browse and edit local knowledge, activity and Local Signals | | Cloud console | `app.pathrule.io` | Organizations, workspaces, members, billing and settings | | Remote MCP | `cloud.pathrule.io/mcp`, Streamable HTTP and OAuth | Cloud knowledge access without installing a local process | ## Shared knowledge, explicit schemas Both MCP servers expose context and typed operations for memories, rules and skills. Local tools take `node_path`, support targeted `content_edit` updates and use `expected_version_id` for concurrency. Remote tools use a canonical `path`, `title` and `body`, and numeric `expectedVersion` for updates. Remote mutations also use an operation id for safe retries. Local helpers include title resolution, batch reads, project learning, activity logging and refresh workflows. Remote MCP is a narrower Cloud knowledge surface, bound to the workspace you approved. Do not copy local tool arguments into a remote call without checking its schema. ## Local and remote boundaries The local runtime knows your repository and installs the files and hooks each client supports. Remote MCP cannot read local files or install hooks. It returns workspace knowledge when called and does not deliver local personal intelligence. Your coding agent performs the coding work under its own provider account. Pathrule supplies knowledge; changing surfaces does not give Pathrule a coding-agent execution role. See [Remote MCP](/docs/surfaces/remote-mcp) for remote schemas and authorization, and [MCP tools reference](/docs/mcp/tools-reference) for the local catalog. ## /docs/mcp/native-integrations # Native agent integrations Pathrule connects to Claude Code and Codex through their native plugin channels or settings-based hooks. Your existing agent continues to do the coding work. The integration delivers Pathrule knowledge and exposes its MCP tools. ## Preview and connect ```bash pathrule integrations pathrule integrations add claude codex --local --dry-run pathrule integrations add claude codex --local ``` The interactive command shows the proposed changes before you approve them. `--dry-run` previews without writing. For unattended setup, use `--yes` only after reviewing the plan. Choose `--cloud` for a signed-in Cloud workspace. Use `--scope project --project ` for a project-specific setup; the default user scope applies across your projects on this machine. ## Choose the channel ```bash pathrule integrations add claude --channel plugin --local pathrule integrations add codex --channel settings --local ``` Both channels use the same Pathrule runtime. Native plugins use the provider's plugin mechanism; settings mode registers Pathrule in the agent's settings. Client versions and available channels are reported during setup. ## Inspect, repair and remove ```bash pathrule integrations list pathrule integrations doctor pathrule integrations repair pathrule integrations remove claude ``` `list` and `doctor` are read-only. Repair reapplies recorded Pathrule integrations, and removal targets the integration Pathrule recorded. Other servers and unrelated settings are preserved. For Cursor, Windsurf and GitHub Copilot, use [the CLI](/docs/surfaces/cli) or [VS Code extension](/docs/surfaces/vscode). Their supported delivery channels differ from Claude Code and Codex's native plugins. ## /docs/mcp/claude-code # Claude Code Claude Code connects to your Pathrule workspace through Pathrule CLI or the [VS Code extension](/docs/surfaces/vscode). Pathrule provides two integration layers: hooks that push path scoped context before the agent acts, and MCP tools that Claude can pull from when it wants more. Claude Code is one of the two clients, with Codex, that Pathrule reaches with a prompt-submit hook. This page covers what gets written into your project, how the two layers fit together, and how to verify the integration end to end. ## Two layers, one workspace - **Hooks (push).** Claude Code invokes Pathrule's hook supervisor at session start, on every prompt and around file and shell tool calls. The supervisor reads a precomputed slice from the local cache and returns it as context. - **MCP tools (pull).** When the hook payload is not enough (discovery prompts, full memory bodies, writes), Claude calls the Pathrule MCP server directly through tools like `pathrule_get_context` and `pathrule_write_memory`. Hooks are the default. MCP tools are the deep path. The same content tree drives both. | Event | What Pathrule does | | --- | --- | | `SessionStart` | Hands Claude the workspace id and root, the Pathrule protocol and your team context, once per session. | | `UserPromptSubmit` | Scopes the turn: the rules and memories that fit the prompt, with the strongest memories as full bodies, and matching skills by name. | | `PreToolUse` | Before a read, edit, write, search or shell call: names and one-line summaries of what applies to that path, the block-pattern check for edits and writes, and the teammate conflict check. | | `PostToolUse` | Records what happened, including failed tool calls, so the session's activity and recurring friction are captured. | | `Stop`, `SubagentStop`, `SessionEnd` | Close the turn and the session. An approved required check can hold the turn open here until its command has passed. | ## Companion files When you install Pathrule into Claude Code, these are the files involved. - **`~/.claude.json`.** Claude Code's user config. Pathrule adds its MCP server entry here and leaves your other servers alone. - **`.claude/settings.json`** in the project. Pathrule merges its hook registrations into this file and keeps any hooks you added yourself. - **`CLAUDE.md`.** With the hook installed, Pathrule's region of this file is a short note that Pathrule is active and its knowledge is delivered by the hook. Anything you wrote outside that region stays yours. - **`.claude/rules/*.md`.** Written only when the hook is not installed, as described below. - **`.claude/skills//SKILL.md`.** Skills attached to your workspace, materialized so Claude can invoke them by name. The protocol and the path knowledge do not have to live in files. When the Claude Code hook is installed, the protocol rides the `SessionStart` hook and knowledge arrives through the per-prompt and per-tool hooks, so Pathrule removes the protocol copy and the knowledge files it wrote in earlier versions. Beyond the hook registration, the short note and your skills, it writes nothing into your tree. If the hook is not installed, Pathrule falls back to the compiled files: the full protocol and workspace overview in `CLAUDE.md`, a protocol copy in `.claude/rules/pathrule-protocol.md`, workspace knowledge in `.claude/rules/pathrule-knowledge.md` and a `CLAUDE.md` in each directory that has knowledge attached. ## Rule enforcement A rule has a priority (high, medium, low) that ranks how it surfaces. Priority does not decide blocking. A rule blocks only when it carries an approved block pattern: a forbidden form in the content, a forbidden location for the file, or both. - An assistant can propose a block pattern when it writes or updates a rule. The proposal is stored with the rule as a proposal and is not enforced. An agent cannot approve it; nothing blocks until a person has approved the pattern. - On `PreToolUse`, before an edit or a write, the hook checks the new content and the target path against every rule with an approved block pattern for that path, whatever its priority. - If one matches, the hook denies the tool call before the file is written. Claude sees `Pathrule blocked:` with the rule name, a preview of the rule, the approved "do this instead" message and a pointer to the full rule, and retries inside the constraint. Every other rule is advisory. It rides along as context and the assistant decides how to apply it. Blocking runs through the local hook; Remote MCP has no hooks, so it surfaces rules as context only. ## Install Through Pathrule CLI: ```bash pathrule setup ``` Run it in the project folder and pick Claude Code when it asks which AI tools you use. Setup signs you in to Pathrule Cloud when needed, attaches the folder to a workspace, installs the MCP entry, remembers your choice for this folder and writes the hook and companion files. Run `pathrule setup --local` instead to use Pathrule with no account; knowledge then stays on this machine. To wire the pieces by hand in a folder that is already attached: ```bash pathrule install claude pathrule sync pathrule doctor ``` `pathrule install claude` adds the MCP entry to `~/.claude.json`. `pathrule sync` installs the hook script and writes `.claude/settings.json`, `CLAUDE.md` and your skills for the AI tools chosen for this folder. Through the [VS Code extension](/docs/surfaces/vscode), choose Claude Code in **Connect AI Clients**. The extension writes the same MCP entry and hook configuration through its bundled CLI. ### Remote MCP Claude Code can also connect to the hosted endpoint, with no local install: ```bash claude mcp add --transport http pathrule https://cloud.pathrule.io/mcp ``` Then complete the OAuth sign-in with your Pathrule account. Remote MCP gives Claude the MCP tools only: it installs no hooks, writes no local files and has no local mode. See [Pathrule Remote MCP](/docs/surfaces/remote-mcp). ## Verify Open Claude Code in a directory you attached. Start a new turn. The Pathrule section should appear in the context surface before the first tool call, listing the path it resolved, the matching rules, the strongest memory bodies and any less-certain candidates by title. If nothing appears, run: ```bash pathrule doctor ``` The doctor is read-only. It reports your sign-in, workspace and whether this folder is attached, whether the Pathrule MCP entry is installed for Claude Code and each other client, and which Pathrule-managed files are in the folder and who wrote them. Add `--json` for the full report, which also flags an MCP entry that points at a runtime that no longer exists. To put everything back in place, run: ```bash pathrule repair ``` Repair rewrites a stale MCP entry, reinstalls the hook script and the hook registration, re-syncs `CLAUDE.md` and your skills, and runs the doctor again. ## When Claude writes content Claude can write memories, rules, and skills back into Pathrule using the MCP write tools. The runtime tags the source as `claude`, so content an AI wrote stays distinguishable from content a person wrote. Use the `pathrule_log_activity` tool to make every file modifying response visible in the activity log. This is the bridge between what Claude did and what your team sees. ## What to read next - [How hooks work](/docs/hooks/how-hooks-work) for the model behind the push layer. - [MCP overview](/docs/mcp/overview) for the pull layer. - [MCP tools reference](/docs/mcp/tools-reference) for every tool Claude can call. ## /docs/mcp/codex # Codex CLI Codex CLI connects to your Pathrule workspace through Pathrule CLI or the [VS Code extension](/docs/surfaces/vscode). The integration has three pieces: Codex's native hooks, a companion `AGENTS.md` file at the workspace root, and the same MCP tool surface the other clients use. Codex is one of the two clients, with Claude Code, that Pathrule reaches with a prompt-submit hook. This page covers what gets written into your project for the integration, how it differs from the Claude Code and Cursor flows, and how to verify it. ## What Pathrule writes When you install Pathrule into Codex CLI, you get: - **An MCP server entry** in `~/.codex/config.toml`, so the assistant can call `pathrule_*` tools. Your other servers in that file stay as they are. - **`.codex/hooks.json`** in the project. The hook registrations, merged so any hooks you added yourself are kept. - **A marked block in the project's `.codex/config.toml`** that turns Codex's hooks on. The rest of that file is yours and stays untouched. - **`AGENTS.md`** at the workspace root. With the hook installed, Pathrule's part of it is a short note that Pathrule is active and delivered by the hook. - **Materialized skills** in `.agents/skills//SKILL.md`, so Codex can invoke them by name. `AGENTS.md` is the analogue of `CLAUDE.md` for Codex. When the Codex hook is installed, the protocol rides the `SessionStart` hook instead of the file, and path knowledge arrives through the prompt and tool hooks, so no protocol copy or knowledge files are written into your tree. Without the hook, `AGENTS.md` carries the full protocol and workspace overview, and Pathrule adds an `AGENTS.md` in each directory that has knowledge attached, which Codex loads when work enters that directory. ## Hook coverage Codex's hook contract is close to Claude Code's. Pathrule registers session-start, prompt-submit, pre-tool, post-tool and stop hooks: - **Session start** delivers the workspace metadata, the protocol and your team context once per session. - **Prompt submit** scopes the turn with the rules and memories that fit the prompt, the strongest memories as full bodies. - **Pre-tool** adds the names of what applies to the path the patch or command touches, and checks rules with an approved block pattern before a patch lands. - **Post-tool** records the outcome. - **Stop** lets an approved required check hold the turn open until its command has passed. The main differences from Claude Code are in the tool surface: Codex uses its `apply_patch` format (with `*** Update File:` markers) instead of separate Edit and Write tools, and there is no Read hook. Pathrule's shared hook script understands `apply_patch`, resolves the affected paths back to workspace nodes and treats a patch as an edit, so a rule with an approved block pattern stops a matching patch before it is applied. A block pattern an assistant proposed is not enforced until a person has approved it. The investment lives in the content layer, not in the client, so the same memories, rules and skills serve Codex and every other client. ## Per client isolation Codex coexists with Claude Code and Cursor on the same machine. You can install one, two, or all three. They share the same Pathrule workspace, the same MCP server, and the same content tree. The configs each client reads are independent. ## Install Through Pathrule CLI: ```bash pathrule setup ``` Run it in the project folder and pick Codex when it asks which AI tools you use. Setup signs you in to Pathrule Cloud when needed, attaches the folder to a workspace, installs the MCP entry, remembers your choice for this folder and writes the Codex files. Run `pathrule setup --local` instead to use Pathrule with no account; knowledge then stays on this machine. To wire the pieces by hand in a folder that is already attached: ```bash pathrule install codex pathrule sync pathrule doctor ``` `pathrule install codex` adds the MCP entry to `~/.codex/config.toml`. `pathrule sync` installs the hook script and writes the project files for the AI tools chosen for this folder, or for the ones it detects in the folder when none were chosen. Through the [VS Code extension](/docs/surfaces/vscode), choose Codex in **Connect AI Clients**. The extension writes the same MCP entry and hook configuration through its bundled CLI. ### Remote MCP Codex can also connect to the hosted endpoint, with no local install: ```bash codex mcp add pathrule --url https://cloud.pathrule.io/mcp ``` Then complete the OAuth sign-in with your Pathrule account. Remote MCP gives Codex the MCP tools only: it installs no hooks, writes no local files and has no local mode. See [Pathrule Remote MCP](/docs/surfaces/remote-mcp). ## Verify Open Codex CLI in a directory you attached to a workspace. The Pathrule session metadata should arrive at session start, and the assistant should be able to call `pathrule_get_context` against your working directory. Run a simple prompt that touches a path with content. The relevant rules and memories should arrive with the prompt, and the assistant can reach deeper through MCP. If nothing arrives, run: ```bash pathrule doctor ``` The doctor is read-only. It reports your sign-in, workspace and whether this folder is attached, whether the Pathrule MCP entry is installed for Codex and each other client, and which Pathrule-managed files are in the folder and who wrote them. Add `--json` for the full report, which also flags an MCP entry that points at a runtime that no longer exists. `pathrule repair` rewrites a stale entry, reinstalls the hook script and hook configuration, re-syncs `AGENTS.md` and runs the doctor again. ## What stays the same The content layer is identical across clients. - The same memory that shows up to Claude Code through the hook shows up to Codex through its own hooks and the MCP tools. - A rule with an approved block pattern blocks a matching patch on Codex just as it blocks an edit on Claude Code. - A skill is invokable by name. If your team writes content for one assistant, every assistant gets it. ## What to read next - [Claude Code](/docs/mcp/claude-code) for the sibling integration with native hooks. - [Cursor](/docs/mcp/cursor) for the Cursor integration. - [MCP tools reference](/docs/mcp/tools-reference) for every tool Codex can call. ## /docs/mcp/cursor # Cursor Cursor connects to your Pathrule workspace through Pathrule CLI or the [VS Code extension](/docs/surfaces/vscode). Pathrule uses Cursor's native hooks and the local MCP server to deliver scoped workspace knowledge. Cursor has session and tool hooks but no prompt-submit hook, so context arrives at session start and around tool calls rather than with each prompt. Cursor uses the local MCP server; Remote MCP setup is not documented for Cursor. This page covers what Pathrule writes into your project for Cursor, how the hook events map across clients, and how to verify the integration. ## What Pathrule writes When you install Pathrule into Cursor, you get: - **`.cursor/hooks.json`.** Cursor's native hook configuration. Pathrule registers the events it cares about here and keeps any hooks you added yourself. - **An MCP server entry in `~/.cursor/mcp.json`.** Your user-level Cursor MCP config, pointed at the local Pathrule MCP server. Your other servers stay as they are. - **`.cursor/rules/pathrule-protocol.mdc`**, plus `.cursorrules` for older Cursor builds. With the hook installed, these carry only a short note that Pathrule is active and delivered by the hook. - **Materialized skills** in `.cursor/skills//SKILL.md`, so Cursor can invoke them by name. When the Cursor hook is installed, the protocol rides `sessionStart` instead of the rule file and path knowledge arrives through the hooks, so no knowledge files are written into your tree. Without the hook, the rule file carries the full protocol and workspace overview, and Pathrule adds a glob-scoped `.cursor/rules/pathrule-k-*.mdc` rule for each directory that has knowledge attached. No third party Skills toggle is needed. Cursor sees the CLI-managed Pathrule hook provider directly. ## Hook event coverage Cursor's events map to Pathrule's injection points: - **`sessionStart`.** When a new session begins. Pathrule returns the workspace metadata, the protocol and your team context, the same bootstrap Claude Code receives at its session start. - **`preToolUse`.** Before Cursor runs a tool. This is where a rule with an approved block pattern denies a matching edit or write, with the rule and the approved remedy as the reason. On Cursor this event carries the decision only; the path scoped context is delivered through `sessionStart` and `postToolUse` instead. - **`postToolUse`.** After a tool finishes. Pathrule uses this both to capture activity and as the compensation point for the path scoped context that Cursor's pre-tool event cannot carry. - **`stop`, `subagentStop` and `sessionEnd`.** Close out the turn and the session. Cursor's per-prompt event is deliberately not registered: its output cannot carry context, so `sessionStart` plus `postToolUse` cover the same ground. A single shared hook script handles the event shape differences between Cursor and Claude Code. You do not need to think about it: install Cursor through Pathrule and the right shape lands. ## Per client isolation Pathrule supports any combination of AI clients on a single machine. - **Cursor only.** Pathrule writes only the Cursor configs. - **Claude Code only.** Pathrule writes only the Claude Code configs. - **Both.** Pathrule writes both. The hooks register independently, the MCP server is shared, the content tree is the same. The choice is whatever you pick when Pathrule setup asks which AI tools you use, in `pathrule setup` or in the VS Code extension. ## Install Through Pathrule CLI: ```bash pathrule setup ``` Run it in the project folder and pick Cursor when it asks which AI tools you use. Setup signs you in to Pathrule Cloud when needed, attaches the folder to a workspace, installs the MCP entry, remembers your choice for this folder and writes the Cursor files. Run `pathrule setup --local` instead to use Pathrule with no account. To wire the pieces by hand in a folder that is already attached: ```bash pathrule install cursor pathrule sync pathrule doctor ``` `pathrule install cursor` adds the Pathrule server to `~/.cursor/mcp.json` and leaves your other servers alone. `pathrule sync` writes the project files for the AI tools chosen for this folder, or for the ones it detects in the folder when none were chosen. Through the [VS Code extension](/docs/surfaces/vscode), which also runs inside Cursor, choose Cursor in **Connect AI Clients**. The extension writes the same MCP entry and hook configuration through its bundled CLI. ## Verify Open Cursor in a directory you attached to a workspace. Open the Hooks Settings tab to confirm Pathrule appears as a registered provider. Start a new chat. The path scoped context should show up before the first tool call. If the integration is silent: ```bash pathrule doctor ``` The doctor is read-only. It reports your sign-in, workspace and whether this folder is attached, whether the Pathrule MCP entry is installed for Cursor and each other client, and which Pathrule-managed files are in the folder and who wrote them. Add `--json` for the full report, which also flags an MCP entry that points at a runtime that no longer exists. `pathrule repair` rewrites a stale entry, re-syncs the project files, including `.cursor/hooks.json`, and runs the doctor again. ## What stays the same Everything you write in Pathrule reaches Cursor with the same shape it reaches Claude Code. - A memory written with the CLI, the VS Code extension or through MCP shows up in both. - A rule with an approved block pattern blocks a matching edit in both. - A skill is invokable by name in both. - The MCP tools (`pathrule_get_context`, `pathrule_write_memory`, etc.) behave identically. If you ship a feature for one assistant, you get it for the other. ## What to read next - [Claude Code](/docs/mcp/claude-code) for the sibling integration. - [How hooks work](/docs/hooks/how-hooks-work) for the underlying model. - [MCP tools reference](/docs/mcp/tools-reference) for every tool the assistant can call. ## /docs/mcp/windsurf # Windsurf Windsurf connects to your Pathrule workspace through Pathrule CLI or the [VS Code extension](/docs/surfaces/vscode). Pathrule writes a local MCP server entry plus a companion rules file that Windsurf reads at session start. Windsurf has no hooks, so unlike Claude Code, Codex, Cursor and GitHub Copilot it receives no context from hooks: the rules file carries the protocol and workspace overview, and the MCP tools deliver everything deeper. Windsurf uses the local MCP server; Remote MCP setup is not documented for Windsurf. This page covers what Pathrule writes into your project for Windsurf, why the same content reaches Windsurf as every other tool, and how to verify the integration yourself. ## What Pathrule writes When you install Pathrule into Windsurf, you get: - **An MCP server entry** in `~/.codeium/windsurf/mcp_config.json`. It points the assistant at the local Pathrule MCP server so it can call the `pathrule_*` tools, and leaves your other servers alone. - **A companion instruction file**, `.windsurf/rules/pathrule-protocol.md`, plus `.windsurfrules` for older Windsurf builds. It carries the workspace overview and the Pathrule protocol, the same substance the other clients get in their own native formats. - **Path knowledge files.** A `.windsurf/rules/pathrule-k-*.md` rule for each directory that has knowledge attached, headed with the directory it applies to. - **Materialized skills** in `.windsurf/skills//SKILL.md`, so Windsurf can invoke them by name. Windsurf has no Pathrule hook, so these files are how the protocol and knowledge reach it at session start. On hook-capable clients, Pathrule now delivers the same protocol through the session-start hook and keeps only a short note in the instruction file; Windsurf keeps the full file because nothing else would carry it. The companion file is not hand-copied per client. Pathrule generates it from a shared renderer that also produces the Claude Code, Cursor, and Codex instructions, so the four stay in sync instead of drifting apart over time. ## How the content reaches Windsurf Any tool that speaks MCP can use Pathrule over stdio: add the Pathrule MCP command to the client config, and the assistant sees the same tool surface. For Windsurf, Pathrule CLI writes that config and renders the companion file alongside it. The companion file delivers the workspace overview and protocol at session start; the MCP tools deliver everything deeper on demand. Two facts make this work without per-client divergence. - **One tool contract.** The MCP tools (`pathrule_get_context`, `pathrule_read_memory`, `pathrule_write_memory`, and the rest) are the same set Claude Code and Cursor call. The assistant fetches context and writes memories, rules, and skills through the identical surface; the client config is the only thing that changes. - **One source of truth.** The companion file and the materialized skills are rendered views, not the canonical copy. A memory written with the CLI, the VS Code extension or through MCP reaches Windsurf with the same shape it reaches every other client. Pathrule does not automatically upload your repository source code. Local project-learning tools can inspect the files attached to a finding to validate it. What is stored is your team's knowledge (memories, rules, skills), the activity agents log, the findings agents record with the files they rest on, and, on a cloud workspace, the file path pairs Pathrule reads from recent git history to learn which files change together. See [what Pathrule computes](/docs/start/what-pathrule-computes) for what is sent and stored in Cloud mode. ## One content layer, many delivery formats The instruction format each client reads differs, so Pathrule produces every companion file from the same shared renderer rather than hand-copying one per tool. That keeps the Windsurf protocol identical in substance to the Claude Code, Cursor, and Codex versions, even though the file format differs. The investment lives in the content layer, not in the client. The same memories, rules, and skills serve Windsurf and every other client without rewriting anything. ## Through the VS Code extension Windsurf is a VS Code fork. If you run the Pathrule VS Code extension inside Windsurf, the extension detects the host and writes the same managed MCP entry through the installer the CLI uses, with no hand-edited JSON. That entry points at the bundled Pathrule runtime and never carries secrets. This is one more entry point to the same workspace, not a separate integration. See [Pathrule for VS Code](/docs/surfaces/vscode) for what the extension does and [Local and Remote MCP](/docs/mcp/one-contract) for the differences between local stdio and Remote MCP. ## Per client isolation Windsurf coexists with Claude Code, Cursor, and Codex on the same machine. You can install one client, several, or all of them. - They share the same Pathrule workspace, the same MCP server, and the same content tree. - The configs each client reads are independent. Installing Windsurf does not touch the others. - Removing one client leaves the rest, and the content, untouched. The choice is whatever you pick when Pathrule setup asks which AI tools you use, in `pathrule setup` or in the VS Code extension. ## Install Through Pathrule CLI: ```bash pathrule setup ``` Run it in the project folder and pick Windsurf when it asks which AI tools you use. Setup signs you in to Pathrule Cloud when needed, attaches the folder to a workspace, installs the MCP entry, remembers your choice for this folder and writes the Windsurf files. Run `pathrule setup --local` instead to use Pathrule with no account. To wire the pieces by hand in a folder that is already attached: ```bash pathrule install windsurf pathrule sync pathrule doctor ``` `pathrule install windsurf` adds the MCP entry to `~/.codeium/windsurf/mcp_config.json`. `pathrule sync` renders the project files for the AI tools chosen for this folder, or for the ones it detects in the folder when none were chosen. You can also use the VS Code extension running inside Windsurf, as described above. ## Verify Open Windsurf in a directory you attached to a workspace. The assistant should read the companion file at session start and be able to call `pathrule_get_context` against your working directory. Run a prompt that touches a path with content. The assistant should surface that content through the MCP tools. If it cannot: ```bash pathrule doctor ``` The doctor is read-only. It reports your sign-in, workspace and whether this folder is attached, whether the Pathrule MCP entry is installed for Windsurf and each other client, and which Pathrule-managed files are in the folder and who wrote them. Add `--json` for the full report, which also flags an MCP entry that points at a runtime that no longer exists. `pathrule repair` rewrites a stale entry, re-renders the companion files and runs the doctor again. ## What stays the same The content layer is identical across clients. - The same memory that shows up to Claude Code through the hook shows up to Windsurf through the MCP tools. - A rule reaches Windsurf through the companion file and MCP. Windsurf has no hooks, so a rule cannot block an edit there; pre-write blocking is available only on clients with tool hooks: Claude Code, Codex, Cursor and GitHub Copilot. - A skill is invokable by name. - The MCP tools behave identically. If your team writes content for one assistant, every assistant gets it. ## What to read next - [Cursor](/docs/mcp/cursor) for the sibling VS Code-fork integration with native hooks. - [Local and Remote MCP](/docs/mcp/one-contract) for why the tool surface is the same everywhere. - [Pathrule for VS Code](/docs/surfaces/vscode) for the extension that can register Windsurf from inside the editor. - [How hooks work](/docs/hooks/how-hooks-work) for the delivery model behind the content. ## /docs/mcp/copilot # GitHub Copilot GitHub Copilot connects to your Pathrule workspace through Pathrule CLI or the [VS Code extension](/docs/surfaces/vscode). It receives scoped workspace knowledge through session and tool hooks, instruction files and the local MCP server. Copilot has no prompt-submit hook, so context arrives at session start and around tool calls rather than with each prompt. Remote MCP setup is not documented for Copilot. Copilot is unusual because one repo level file set feeds three surfaces at once: VS Code agent mode, the Copilot CLI and the coding agent. This page covers what Pathrule writes for Copilot, how the surfaces differ, how the hook events map, and how to verify the integration. ## What Pathrule writes When you enable Copilot, Pathrule writes Copilot's own paths rather than inventing new ones. Every file lives under `.github/`, which is where Copilot already looks. | File | What it does | |---|---| | `.github/copilot-instructions.md` | Auto applied in agent mode and the CLI. With the hook installed, a short Pathrule note plus Copilot's guardrail for calling `pathrule_get_context`; without it, the full Pathrule protocol body. | | `.github/instructions/pathrule.instructions.md` | An `applyTo`-scoped pointer that keeps the protocol present even when instruction matching is glob driven. | | `.github/hooks/pathrule.json` | The hook configuration. This is the one hook location all three Copilot surfaces read. | | `.github/skills//SKILL.md` | Skills attached to your workspace, so Copilot can invoke them by name. | When the Copilot hook is installed, the protocol rides the `sessionStart` hook instead of the instructions file and path knowledge arrives through the hooks, so no knowledge files are written into your tree. Without the hook, Pathrule also writes an `applyTo`-scoped `.github/instructions/pathrule-k-*.instructions.md` file for each directory that has knowledge attached. Skills have one nuance. Copilot also reads `.claude/skills`. If you have both Claude Code and Copilot enabled on the same workspace, Pathrule skips `.github/skills` so Copilot does not see every skill twice. Enabling both clients produces no duplicated skills and no duplicated protocol in Copilot's context. You can confirm what landed: ```bash cat .github/copilot-instructions.md cat .github/hooks/pathrule.json ``` ## Three surfaces, one file set The same `.github/` files light up each Copilot surface, but the surfaces differ in how hooks and MCP reach them. | Surface | Hooks | MCP config location | |---|---|---| | VS Code agent mode | Reads `.github/hooks`; also reads `.claude/settings.json` when present | User level `mcp.json`, or registered in editor by the Pathrule VS Code extension | | Copilot CLI | Reads `.github/hooks` | `~/.copilot/mcp-config.json` | | Coding agent (on github.com) | Reads `.github/hooks` from the committed repository | Repository settings on github.com, configured by you (not file managed) | For VS Code, the MCP config root key is `servers`, not `mcpServers`. If you use the [Pathrule VS Code extension](/docs/surfaces/vscode), Copilot agent mode is registered for you in the editor, with no MCP file to edit by hand. The coding agent is the one surface Pathrule cannot wire from disk. It works from what is committed to the repository, and its MCP servers are set in the repository's settings on github.com, outside any file Pathrule manages, so Pathrule does not configure MCP for it. To give it the instructions and skills, commit the `.github/` files. If your workspace has a `.gitignore`, materialized skills are listed in a Pathrule section of it; delete those lines to commit them. The hook configuration runs the Pathrule hook installed on the machine that wrote it, so hook-time context and blocking apply where Pathrule is installed: VS Code agent mode and the Copilot CLI. ## Hook event coverage Copilot's hook events map to the same injection points Pathrule uses on Cursor and Claude Code. - **`sessionStart`.** When a session begins. Pathrule returns the workspace metadata, the protocol and your team context, the bootstrap Claude Code receives at its session start. - **`postToolUse`.** After a tool finishes. Pathrule delivers the path scoped context for what the agent just touched, and captures activity. - **`preToolUse`.** Before a tool runs. This is where a rule with an approved block pattern denies a matching edit before the change lands, with the rule and the approved remedy as the reason. In VS Code agent mode this event can also carry the path scoped context; the Copilot CLI takes context only on `sessionStart` and `postToolUse`. - **`agentStop`, `subagentStop` and `sessionEnd`.** Close out the turn and the session. The per prompt event is deliberately not wired. Copilot's output for that event carries no additional context, so matching it would spend a process per prompt for no injection. SessionStart plus PostToolUse cover the same ground. The result is parity with the Cursor injection profile. A single shared hook script handles every client. It detects the Copilot payload shape, normalizes it to one canonical form, runs the same rule and memory selection used for every other client, then writes back in Copilot's schema. You do not configure any of this per surface. The script is fail open by construction: an unrecognized or malformed payload returns nothing rather than breaking your Copilot session. ## Install Through Pathrule CLI: ```bash pathrule setup ``` Run it in the project folder and pick GitHub Copilot when it asks which AI tools you use. Setup signs you in to Pathrule Cloud when needed, attaches the folder to a workspace, installs the MCP entries, remembers your choice for this folder and writes the `.github/` files. Run `pathrule setup --local` instead to use Pathrule with no account. To wire the pieces by hand in a folder that is already attached: ```bash pathrule install copilot pathrule sync pathrule doctor ``` `pathrule install copilot` writes the Pathrule server into both MCP configs, `~/.copilot/mcp-config.json` for the Copilot CLI and VS Code's user `mcp.json`, and leaves every other server in those files alone. `pathrule sync` writes the project files for the AI tools chosen for this folder, or for the ones it detects in the folder when none were chosen. Through the Pathrule VS Code extension, choose GitHub Copilot in **Connect AI Clients**. The extension registers Copilot agent mode in the editor and writes the instruction files and hook config for you. ## Verify Open a workspace you attached to Pathrule and start a Copilot session on the surface you use. - **VS Code agent mode or the Copilot CLI.** Start a new chat. The path scoped context should arrive before the first tool call. Edit a file under a path with attached knowledge and watch the relevant rules and memories surface. - **Coding agent.** Once the `.github/` files are committed, the coding agent reads the instructions and skills from the repository. Add an MCP server in the repository's settings on github.com if you want it to call tools. If the integration is silent: ```bash pathrule doctor ``` The doctor is read-only. It reports your sign-in, workspace and whether this folder is attached, lists Copilot twice, once for the Copilot CLI config and once for VS Code's `mcp.json`, so a half-installed setup shows up, and shows which Pathrule-managed files are in the folder and who wrote them. Add `--json` for the full report, which names each config path and also flags an MCP entry that points at a runtime that no longer exists. To fix that, run: ```bash pathrule repair ``` Repair rewrites stale Pathrule MCP entries, leaves your other servers untouched, re-syncs the project files and runs the doctor again. `pathrule uninstall copilot` removes the Pathrule entry from both MCP configs, and turning Copilot off for the folder removes every file Pathrule owns for it. ## What stays the same Everything you write in Pathrule reaches Copilot with the same shape it reaches Claude Code and Cursor. - A memory written with the CLI, the VS Code extension or through MCP shows up in Copilot. - A rule with an approved block pattern blocks a matching edit in Copilot. - A skill is invokable by name in Copilot. - The MCP tools (`pathrule_get_context`, `pathrule_write_memory`, and the rest) behave identically. You write knowledge once and every supported agent reads it. ## What to read next - [Cursor](/docs/mcp/cursor) for the sibling hook integration. - [Local and Remote MCP](/docs/mcp/one-contract) for why the same tool surface reaches every client. - [How hooks work](/docs/hooks/how-hooks-work) for the underlying delivery model. - [Pathrule for VS Code](/docs/surfaces/vscode) for in editor registration of Copilot agent mode. ## /docs/mcp/tools-reference # MCP tools reference This page inventories Pathrule's MCP tools by capability. The assistant rarely needs all of them. Most sessions touch only `pathrule_get_context` plus one or two reads or writes. The local stdio server and hosted Remote MCP each add only the operations their runtime can actually perform. For the underlying model, see [MCP overview](/docs/mcp/overview). ## Context and discovery | Tool | Purpose | | --- | --- | | `pathrule_get_context` | The primary entry point. Resolves the current working directory to a workspace node and returns the right slice of memories, rules, and skills for the task. | | `pathrule_get_tree` | Returns the workspace node tree (folders, files, contexts). Useful for discovery prompts. | | `pathrule_get_node` | Fetches a single node plus its attached memories, rules, and skills. | | `pathrule_resolve` | Maps a known title or name to an id, path and version handle without walking the tree. A unique match can include the body in the same call. Local stdio. | | `pathrule_read` | Batch reads memory, rule and skill ids in one round trip, up to the server cap. Local stdio. | | `pathrule_goto` | Fuzzy resolves a name or path to a node id. Useful when the user names a target loosely. | | `pathrule_knowledge_map` | A read-only map of the workspace's memories, rules and skills grouped into related regions: the whole workspace at a glance, one region's items and issues, or what else relates to given items, files or a query. Useful before a quality pass or before updating knowledge. | | `pathrule_ping` | Health check. Returns the runtime's view of the current working directory and a timestamp. | | `pathrule_setup` | Bootstraps Pathrule in a new repo by proposing initial memories, rules, and skills the user can approve. | Most sessions start and end with `pathrule_get_context`. The response carries the workspace overview, the matching content ids, and a hint about which tool to call next. The assistant follows that hint rather than guessing. ## Memory | Tool | Purpose | | --- | --- | | `pathrule_list_memories` | Enumerates the memories under a path with titles and short previews. The virtual MainMemory index. | | `pathrule_read_memory` | Returns the full body of a memory by id, including the version token for optimistic concurrency. | | `pathrule_write_memory` | Creates a memory at a node path. Missing nodes along the path auto create. Source defaults to `claude` when called over MCP. | | `pathrule_update_memory` | Edits an existing memory: a full replacement, or a small targeted edit with `content_edit`. `move_to_path` re-homes it, and `restore: true` brings back a deleted memory. Pass `expected_version_id` so a concurrent edit conflicts cleanly. | | `pathrule_delete_memory` | Soft deletes a memory. Restorable until permanently deleted. `hard: true` deletes it permanently and needs a workspace admin. | The default flow is `get_context` to find the relevant memory id, then `read_memory` for the body if the assistant needs to cite it, and `write_memory` when the user asks to capture something. ## Rule | Tool | Purpose | | --- | --- | | `pathrule_read_rule` | Returns the full body of a rule by id. | | `pathrule_write_rule` | Creates a rule at a node path with a scope type (`folder`, `file_type`, `project`) and a priority (`high`, `medium`, `low`). It can also propose a block pattern or a required check; a proposal is stored as a proposal, an agent cannot approve it, and nothing is enforced until a person has approved it. | | `pathrule_update_rule` | Edits an existing rule with optimistic concurrency. Also moves it to another path or restores a deleted rule. | | `pathrule_delete_rule` | Soft deletes a rule. Restorable until permanently deleted. | Rules are workspace level and can be attached to more than one node. Writing a rule at the same path twice should use update, not write, to avoid duplicates. ## Skill | Tool | Purpose | | --- | --- | | `pathrule_read_skill` | Returns the full SKILL.md body of a skill by id. For `github_ref` skills it returns the cached snapshot. | | `pathrule_write_skill` | Creates a skill at a node path. Accepts the full SKILL.md including frontmatter. Source can be `manual`, `template`, or `github_ref`. | | `pathrule_update_skill` | Edits an existing skill with optimistic concurrency. Also moves it to another path or restores a deleted skill. | | `pathrule_delete_skill` | Soft deletes a skill. Restorable until permanently deleted. | For the authoring flow, see [Writing skills](/docs/content/skills). An assistant drafts first and calls `pathrule_write_skill` after the user approves the body. ## Patterns | Tool | Purpose | | --- | --- | | `pathrule_import_pattern` | Previews and imports a published bundle of memories, rules and skills at the chosen workspace path. | | `pathrule_remove_pattern` | Removes the pieces owned by a previously imported pattern bundle. | ## Activity | Tool | Purpose | | --- | --- | | `pathrule_log_activity` | Logs a structured record of a file modifying response. Required after every response that creates, edits, or deletes files. Fields: domain, action, scope, subjects, files_touched, task_summary. | The activity log feeds the workspace's recent activity, which the VS Code extension shows in its Recent Activity view, and the derived learning layers. Logging one record per response (not per file) is the right granularity. ## Project learning What an agent works out from your code, kept with the files it read and shared with the workspace. See [Project learning](/docs/intelligence/project-learning). | Tool | Purpose | | --- | --- | | `pathrule_record_learning` | Saves a finding the agent reached by reading the code, together with the files it read and what they contained. Pathrule checks those files on disk before accepting it. A finding is not a memory, rule or skill; it reaches every member's agent as advice to verify, in the context the agent requests, while its sources are unchanged in that checkout. It is never promoted to a rule automatically. Pass the id of an earlier finding to replace it with a corrected one. | | `pathrule_review_learning` | Lists current, stale and conflicting findings, including the ones held back from context, and retracts a finding by id. Only the person whose agent recorded a finding can retract it, and the retraction applies to the whole workspace. | | `pathrule_review_history` | Reads past review discussion on the repository's GitHub origin through your existing `gh` login, so an agent can see how the team settled a similar question before. It stores no comments and skips bot, external and dismissed reviews; without GitHub access, everything else keeps working. | ## Suggestions and refresh | Tool | Purpose | | --- | --- | | `pathrule_list_pending_refreshes` | Lists stale memory and rule items the self-audit has flagged. | | `pathrule_get_refresh_brief` | Claims a refresh task and returns the full repair context, including the audit reason and the assistant instructions. | | `pathrule_resolve_refresh` | Marks a refresh task applied or rejected. Closes the human in loop workflow. | | `pathrule_request_refresh` | Flags a memory or rule that the assistant found stale, contradictory, duplicated, too narrow or unclear during normal work. | Suggestions are how Pathrule keeps the content tree from drifting. The assistant can flag a concrete issue, claim a brief, propose a fix, and resolve it, all without leaving the editor. ## Local lazy-write control The local stdio server advertises its full tool set from the first `tools/list`: reads, writes, updates, deletes, patterns, setup, refresh and activity. Nothing has to be unlocked before the first write, and the list stays the same for the whole session, so a long conversation never pays for a tool list that changes halfway through. If you would rather start each session with a smaller list, lazy mode is available as an opt-in. Set `PATHRULE_MCP_TOOLS=lazy` in the environment of the Pathrule MCP entry. In lazy mode the read tools and `pathrule_log_activity` are visible on startup, and one extra tool appears: | Tool | Purpose | | --- | --- | | `pathrule_enable_writes` | Lazy mode only. Enables the write, update, delete, pattern, setup and refresh-mutation tools for the rest of the MCP session. The server then emits `tools/list_changed` once. | Lazy mode removes nothing; it changes when mutation tools become visible. Without the variable, or with any other value, `pathrule_enable_writes` does not exist because there is nothing to enable. ## Hosted Remote MCP Remote MCP has its own Cloud-native schemas. A read grant exposes seven tools: `pathrule_get_context`, plus list and read tools for each of memory, rule and skill. A write grant adds write, update, delete and history for each kind, for a full catalog of nineteen tools. | Operation | Remote arguments and behavior | | --- | --- | | Context, lists and reads | Scoped to the workspace approved in the OAuth grant | | Write | `path`, `title` and `body`, with a stable operation id | | Update | Item `id`, numeric `expectedVersion`, `title` and `body`, with a stable operation id | | Delete | Soft deletion with retained history, under the write grant | | History | Per-item history, under the write grant | The authorization server recognizes `pathrule:read`, `pathrule:write`, `pathrule:refresh` and `pathrule:activity`. Recognized scopes do not add tools absent from the catalog. Remote MCP does not expose organization administration, workspace setup, snapshots, pattern imports, project learning, activity logging or refresh workflows. It installs no hooks and reads no local files. Use `tools/list` on the connected server to see its exact schemas. [Remote MCP](/docs/surfaces/remote-mcp) covers authorization and the local delivery boundary. ## Conventions The conventions below apply to the local stdio surface. Remote schemas are described above. - **Path first writes.** Write tools take a workspace relative `node_path` like `/apps/api` or `/`. If the path does not exist, intermediate nodes auto create. - **Optimistic concurrency.** Update and delete tools accept an `expected_version_id` from a prior read. A mismatch returns a clear conflict response with the current version, so the assistant can re-read and merge rather than overwrite. - **Duplicates are refused.** A memory whose title already exists at that path, or a rule or skill whose name already exists in the workspace, is rejected with a duplicate error, so the assistant updates the existing record instead. A memory or rule can be forced through with `allow_duplicate: true` after the assistant has reviewed the existing one. - **Compact by default.** Responses are compact for the common case. On the local server, pass `verbose: true` when you need the full record back. - **Stable ids.** Tool responses carry stable `id` and `version_id` values. The assistant can reference them in follow up calls without re reading the parent. ## What to read next - [MCP overview](/docs/mcp/overview) for the model behind the tool surface. - [How hooks work](/docs/hooks/how-hooks-work) for the push layer that complements these pull calls. - [Writing memories](/docs/content/memories), [Writing rules](/docs/content/rules), [Writing skills](/docs/content/skills) for what to put inside the writes. ## /docs/hooks/how-hooks-work # 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 each client actually exposes. - `SessionStart` hands the assistant the workspace it is in, the Pathrule protocol and your team context, once per session. - `UserPromptSubmit` scopes an upcoming turn on clients whose prompt event accepts context. - `PreToolUse` supplies context or a strict-rule decision before an action when the client accepts it. - `PostToolUse` records outcomes and compensates with path-scoped context on clients whose pre-tool event accepts decisions but not context. - 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, Codex, Cursor and GitHub Copilot. Windsurf has no Pathrule hooks, so its generated rules file supplies the session bootstrap and the local MCP server supplies deeper context on demand. ## Client delivery profiles | Client | Bootstrap and context | Strict pre-write blocking | | --- | --- | --- | | Claude Code and Codex | Session start, prompt-submit and pre-tool hooks | Yes | | Cursor and GitHub Copilot | Session start, post-tool context and pre-tool decisions (no prompt-submit hook) | Yes | | Windsurf | Rules file at session start, then the local MCP server | No Pathrule hooks | | Remote MCP | Explicit hosted MCP calls | No local hooks | A strict rule is one that carries a block pattern a person has approved. See [Rules as guardrails](/docs/hooks/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 the local index, so a network problem does not leave the turn without context. ## 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. Cursor and GitHub Copilot do not accept context on their prompt event, so the session-start hook carries the bootstrap and the post-tool hook carries the path-scoped names. 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 A client whose Pathrule hook is installed gets the protocol and team context from the session-start hook instead of from its instruction file. On Claude Code the session-start context joins the system prompt, so it survives conversation compaction. The instruction file (`CLAUDE.md`, `AGENTS.md`, the Cursor rule or the Copilot instructions) keeps only a short Pathrule note, and 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: - A client with no Pathrule hook, such as Windsurf, or a client whose hook is not 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. ```bash pathrule doctor ``` It is read-only and checks: - Your sign-in, organization and workspace. - Whether the current folder is attached to a 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. 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: ```bash pathrule repair ``` Repair rewrites stale MCP entries, reinstalls the hook script and each client's hook registration, re-syncs the companion files and the local cache the hook reads, and runs the doctor again. 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](/docs/mcp/overview) for the tool surface that backs the deep path. - [Core concepts](/docs/start/core-concepts) for the data model the hook reads from. - [CLI install](/docs/cli/install) for installing the runtime that hosts the hook supervisor. ## /docs/hooks/rules-as-guardrails # Rules as guardrails A rule in Pathrule is not a note the assistant reads later. It is a guardrail that arrives before the assistant acts. Most documentation tells you what went wrong after it shipped. A guardrail can stop the change before it lands. This page explains the difference between context that informs a turn and a rule that can block one. For the mechanics of how hooks deliver context, read [How hooks work](/docs/hooks/how-hooks-work) first. This page is about what a strict rule does once that context is in place. ## Pull asks. Push arrives. The old model is pull. The assistant has to remember to ask for your conventions, call a tool, and read the result before it edits anything. If it forgets, it edits blind, and you find the problem in review. The hook model is push. On Claude Code and Codex, context arrives without the assistant asking for it when you submit a prompt and right before the assistant uses a tool. Cursor and GitHub Copilot have no prompt-submit hook, so there the session-start hook carries the bootstrap and the tool hooks carry the rules for the path being touched. Either way, by the time the assistant is about to write a file, the rules attached to that path are already in front of it. Windsurf has no hooks: it reads Pathrule's rules file and asks the local MCP server for more, so on Windsurf rules inform but do not block. ## Two levels: advisory and blocking Not every rule should interrupt the assistant. Pathrule treats rules at two levels. - **Advisory rules** ride along as context. They appear next to the file the assistant is about to touch, with their priority, so the assistant can factor them in. They do not stop anything. Most rules are advisory, at any priority. - **Strict rules** can block. A rule becomes strict when it carries a block pattern a person has approved: a forbidden form in the content, such as an import, an identifier, a class name or a CSS declaration, a forbidden location for a file, or both. When the assistant is about to edit or write a file in a way that matches, the hook stops the tool call before the file is written and returns the reason. The assistant reads it and tries again, this time inside the constraint. Priority and blocking are independent. Priority (high, medium, low) decides how prominently a rule surfaces and which rules make the cut when space is short. It does not decide blocking: every strict rule for the path is checked, whatever its priority. ### How a rule becomes strict An assistant cannot arm a block pattern on its own. 1. The rule is written in plain words first, by you or by an assistant you asked. 2. An assistant can propose a block pattern for it through the MCP write and update tools for rules. The preferred form names the forbidden text exactly as the rule spells it, with real examples that must be caught and near misses that must not. Pathrule builds the pattern from that and tests it against both sets; if either fails, the proposal is refused with the reason rather than weakened. 3. The proposal is stored with the rule and is not enforced. 4. Only after a person approves it does the hook start blocking, and the remedy written for it becomes the "do this instead" the assistant sees. A rule can also carry a required check: a verification command that must have passed before the turn ends, such as a test suite for a package. Like a block pattern, it is proposed and is not enforced until a person approves it. Once approved, on Claude Code and Codex the hook holds the turn open with the exact command to run until it has passed. ### What the assistant sees A blocked edit comes back with the rule name, a short preview of the rule, the approved remedy and a pointer to the full rule. For a rule named "No direct database client in UI components", it reads like this: ```text Pathrule blocked: "No direct database client in UI components" UI components never import the database client. Data goes through the data layer hooks. Do this instead: call the data layer hook for this resource. Your edit matches this rule's forbidden pattern. Read the full rule via pathrule_read_rule() and retry without the violation. ``` Claude Code, Codex, Cursor and GitHub Copilot receive this as a denial of the tool call, in each client's own hook format. Windsurf has no hooks, so nothing is blocked there. Blocking applies to file edits and writes; a shell command still receives the rule as context. The split is deliberate. Blocking a low-stakes edit wastes the assistant's turn and yours. Blocking is reserved for the rules where a violation is a real regression and someone has signed off on exactly what counts as one. ## Before and after Consider a rule that says secrets never go into committed files, with an approved block pattern for the key format your provider uses. | | Without the guardrail | With the guardrail | | --- | --- | --- | | The assistant's intent | Add an API key to a config file to make a feature work | Same | | What happens | The edit lands | The hook blocks the matching tool call before the file is written | | When you find out | Later, in review (or not at all) | In the same turn. The assistant sees the rule text and switches to an environment variable | | Result on disk | A committed secret | The matching edit was not written | The same pattern applies to any rule a team has paid for in production: a data-access policy that must filter by user, a migration convention, a file that is generated and must not be hand-edited. The rule stops being a comment someone hopes the assistant read and becomes a check that runs before the edit lands. A block pattern catches the forms it was approved for, so it complements review rather than replacing it. ## Filenames pull the right memory You do not always have to wait for a tool call. On Claude Code and Codex, when your prompt names a file that an attached memory is about, the prompt hook can surface that memory's body before the assistant opens anything. Naming the file you are working on is often enough to put the right context in front of the assistant on the first turn. When more than one memory matches the same filename, the hook shows the candidates instead of guessing. ## Fail open by design A guardrail that breaks your workflow when it breaks is worse than no guardrail. Pathrule fails open. If the hook cannot evaluate a rule, errors, or times out, it does not block your work. The change proceeds. Enforcement is a safety net, not a gate you can get stuck behind. You stay in control. If you ever want hooks off entirely, one file turns them off. ## Verify it yourself You do not have to take the behavior on faith. To see which hooks your AI client has registered, read its settings file. For Claude Code, Pathrule registers its hooks in the project: ```bash cat .claude/settings.json ``` Cursor uses `.cursor/hooks.json`, Codex uses `.codex/hooks.json` and GitHub Copilot uses `.github/hooks/pathrule.json`. To turn every Pathrule hook off instantly (the kill switch), create one file: ```bash touch ~/.pathrule/kill-hooks ``` The next tool call passes straight through with no Pathrule involvement. Remove the file to turn hooks back on: ```bash rm ~/.pathrule/kill-hooks ``` To confirm a rule is actually attached to a path, run `pathrule rule list` in the folder, or open the assistant's Pathrule context surface in your editor. The rule shows up with its priority before the assistant acts on that path, and a strict rule shows its block the first time an edit matches it. ## What to read next - [How hooks work](/docs/hooks/how-hooks-work) for the delivery mechanics and the empty-state behavior. - [Writing rules](/docs/content/rules) for how to author a rule worth enforcing. - [MCP overview](/docs/mcp/overview) for the deep path the assistant uses when the hook is not enough. ## /docs/retrieval/how-retrieval-works # How retrieval finds the right knowledge A workspace can hold thousands of memories, rules and skills. The job of retrieval is to put the few that matter into the assistant's context before it starts, and to leave the rest out. This page describes what that selection does and how it improves over time. How the ranking is computed is part of Pathrule's proprietary engine and is not published. ## Path scope comes first The first filter is location. Every memory, rule and skill lives at a node path. When the assistant works in `/apps/api/payments`, Pathrule starts from what is pinned to that path and what it inherits from the paths above it. A UI tweak in `/apps/web/dashboard` does not pull in the rules about database migrations. This is the same path scope described in [Core concepts](/docs/start/core-concepts), applied as the first cut. By the time anything more expensive runs, the candidate set is already small. ## Meaning and keywords, together Once the path narrows the field, Pathrule matches your intent against the candidates two ways at once. - **Keyword matching** catches exact hits: a file name, a function name, a literal phrase from a memory title. - **Meaning-based matching** catches the rest: a question phrased differently from how the memory was written, a synonym, a paraphrase, a concept that shares no words with the entry. The second one is not a text search with extra steps. Each entry and your request are compared by what they mean rather than by the words they share, which is why a match can happen with no shared string at all. See [what Pathrule computes](/docs/start/what-pathrule-computes). Neither alone is enough. Keyword search misses a memory that says the same thing in other words. Meaning-based search can blur an exact file-name match. Pathrule combines them, so an exact match keeps its priority and a same-idea-different-words match still surfaces. On a Cloud workspace, the prompt hook 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 the local index for that prompt. In local mode, with no account, matching leans on path scope and keywords. ## The files next to the one you are in Path scope and meaning both start from where the assistant is working. A further signal widens that slightly: Pathrule learns which files your team habitually changes in the same piece of work, and lets knowledge attached to those neighbours surface too. It means a decision recorded once, on the file where it was made, still reaches the sessions that need it, even when the prompt never mentions that file. The signal is built from file paths, not file contents: the paths your agents' logged work touched and, on a Cloud workspace, a one-time seed from the file paths of recent git history, so it helps before your team has logged much work. It fades as those relationships stop happening. On a Cloud workspace, when one neighbour moves with the file in front of the assistant especially often, the context an agent asks for also carries a one-line heads-up naming it. See [files that change together](/docs/retrieval/co-change). ## It works across languages The meaning-based match is not tied to one language. A prompt in Turkish can surface a memory written in English, and a mixed-language prompt can still find the right entry. This is the case plain keyword search cannot handle. When the prompt and the memory share an idea but no words, matching has to work on meaning rather than spelling. ## The best matches arrive ready to use Retrieval delivers in two tiers. The entries that clearly fit the prompt come through as full content, so the assistant works straight from your team's knowledge instead of going to read it. Only the most relevant few are sent each turn, within a per-prompt budget, and content the assistant already has is not sent again, so the assistant gets what it needs without carrying the whole knowledge base. Everything else that qualifies arrives as a name, an id and one line, enough for the assistant to recognise it and pull the body when it turns out to matter, so a relevant entry that does not fit is still listed rather than dropped. Skills are offered by name, because a procedure should be asked for rather than pushed. A prompt that asks two separate things is matched part by part, so both parts get knowledge. [What arrives in full, and what arrives as a name](/docs/retrieval/graduated-delivery) covers all three. ## Candidates are evidence, not answers When retrieval is not certain, it does not pretend to be. Pathrule surfaces likely entries as candidates and tells the assistant to read the full body before acting on one. A candidate is a pointer worth checking, not a fact to repeat. This follows Pathrule's standing rule that wrong context is worse than no context. In an ambiguous case Pathrule shows a candidate rather than asserting an answer. ## It learns from how knowledge is actually used Retrieval is not frozen at the moment a memory is written. Over time Pathrule observes which entries actually helped on which kinds of work, and lets that move future results. An entry that keeps proving useful for a kind of task is more likely to surface for similar work later. The observation is concrete rather than a rating anyone gives. Each delivery is recorded along with how the turn went: which of the delivered entries the assistant actually consulted rather than merely received, how many tool calls the work took, and how many failed and on which files. A turn that received knowledge and still ran into failures counts against the knowledge it was given. That record is taken by the layer that did the delivering, not asked for. The assistant does not have to call a tool or cooperate in any way for the turn to be measured, which keeps the loop consistent across clients. Because the record is kept per kind of work, the result is not one score per entry. The same memory can rank high for a migration and low for a UI tweak. A single importance field, maintained by hand, cannot express that difference. The learning is conservative by design. - **Unclear outcomes do not teach.** A turn whose outcome is ambiguous is not used as a lesson. - **A clear miss reduces, it does not erase.** A single clear miss lowers an entry's standing for that kind of work rather than wiping out its history. - **Influence fades with time.** An entry that stops matching the current code loses ground instead of haunting results. And it changes the choice, not the size. What an entry has proven can move it ahead of an equally relevant rival, but it does not push an entry past the relevance bar that decides whether anything is sent at all. Over time a workspace delivers a better few entries per turn in the same amount of context. Learning here buys accuracy, not room. [How knowledge compounds](/docs/start/how-knowledge-compounds) covers this loop end to end, and [Suggestions and self-audit](/docs/content/suggestions) covers how stale entries are raised for review. ## The same for the whole team On a Cloud workspace, ranking draws on the workspace's shared data in Pathrule Cloud rather than on a separate copy in each person's client. Two teammates asking the same thing on the same path get consistent results, whichever coding agent they use. Claude Code and Codex receive the prompt-ranked selection through their prompt-submit hook. Cursor and GitHub Copilot have no prompt-submit hook, so their session and tool hooks carry path-scoped knowledge instead. Any client, Windsurf included, gets a ranked selection when it asks the MCP server for context with `pathrule_get_context`. It also means the learning is shared. When an entry proves useful, it surfaces better for everyone on the team, not just the person who triggered it. ## What retrieval does not see Retrieval operates on your team-written memories, rules and skills, plus the path you are working in, the words of your request and the record of how past work went. It does not read, index or upload the contents of your source files. The match runs over knowledge your team chose to write down, not over the repo itself. From a checkout, a Cloud workspace takes file paths: the first time an agent asks for deep context, Pathrule reads the file paths of recent git history to seed which files change together, and the file names near the top of the folder tree to recognise the technologies in use. Separately, `pathrule snapshot`, when you or your agent run it, uploads the file tree, manifests, short documentation samples and recent git metadata. [What Pathrule computes](/docs/start/what-pathrule-computes#what-none-of-it-is-built-from) lists what is read and what is kept. ## Where this fits - [Core concepts](/docs/start/core-concepts) defines path scope, the first filter retrieval uses. - [How hooks work](/docs/hooks/how-hooks-work) describes how the selected slice reaches the assistant before its first tool call. - [How knowledge compounds](/docs/start/how-knowledge-compounds) places retrieval inside the deliver, capture, score loop. ## /docs/retrieval/graduated-delivery # What arrives in full, and what arrives as a name Retrieval has two jobs. Choosing the right knowledge is the famous one. Deciding how much room each chosen entry deserves is the one that determines whether the good answer actually fits. A simpler design answers the second question with one rule: everything that ranks goes out as full content, in rank order, until the room runs out. The entry ranked eighth gets exactly the treatment the entry ranked first gets, and the next one gets nothing at all, even when it is relevant. Relevance decides the order and nothing else. In Pathrule, relevance decides the form. ## Three forms, one ranking - **The closest few arrive as full content.** The assistant reads them and acts, with no separate fetch and no round trip. - **Everything else relevant arrives as a name, an id and one line.** Enough for the assistant to recognise it and pull the body when it turns out to matter. - **Skills arrive by name only**, however well they rank. More on that below. The important property is the one at the bottom of the list: a relevant entry is not thrown away for want of room. What does not fit the per-prompt budget is listed by title, and the cheap form is what makes that affordable. How many bodies arrive in full is chosen to keep the strongest matches whole while costing less than sending every ranked entry in full. The exact budget is part of Pathrule's engine and can change between releases. ## Why a skill is never pushed A memory is a fact. A rule is a constraint. Both are things an assistant should simply know while it works, so both can arrive as content. A skill is a procedure. Putting a procedure into the context of a turn that did not ask for one does not inform the assistant, it instructs it, and an assistant that has been handed a checklist tends to follow the checklist. So skills are offered by name and the assistant reaches for one when the work is actually the work that skill describes. Invoking it, for example with `::skill-name`, brings in its full body. See [writing skills](/docs/content/skills) for what a skill is meant to be. ## Rules earn their room too If rules skipped the relevance test, a constraint about database migrations could crowd out the memory that would have answered a question about a button. So rules pass through the same relevance test as everything else, and an unrelated rule arrives as a name rather than taking a full slot. The exception is deliberate: a rule marked strict keeps its body, because a hard constraint whose violation causes a regression is not something to ration. See [Rules as guardrails](/docs/hooks/rules-as-guardrails). ## The demotion is what makes relevance observable There is a second reason the cheap form matters, and it is about learning rather than cost. When every ranked entry is pushed as a body, the layer never finds out whether any of them were wanted. A body that arrives unasked produces no evidence either way. An offered name is different: the assistant either pulls it or does not, and a pull is a deliberate act by the party that knows what the work needed. That pull is a useful relevance signal, and an entry that keeps being pulled is more likely to arrive in full next time. It fits the wider loop described in [how retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works): the layer measures what it delivered rather than asking the assistant to report back. ## The bar has to hold in every language Whether an entry is sent at all depends on a relevance bar, and that bar can quietly depend on language. The same memory can score one way against a prompt written in English and lower against a faithful translation of that prompt, because meaning-based matching does not produce identical results across languages for the same idea. A bar tuned only against English prompts would cut off the other languages without anyone noticing, and the symptom would not be an error. It would be a team that writes its prompts in Turkish getting less context than a team that writes the same prompts in English. So the bar is set where it holds across languages, and Pathrule tests this with prompts in several languages rather than assuming it. [How Pathrule proves hard claims](/docs/start/technical-proof) describes how claims like this are checked. ## A prompt that asks two things gets knowledge for both Ask one question and meaning-based matching works well. Ask two in the same message and it has a structural problem: the request becomes a single average of two different ideas, and an average of two things is often close to neither. The entry that answers your first question and the entry that answers your second can both fall short of a bar that either would have cleared on its own. Pathrule reads a multi-part request as its parts. Each part is matched separately and the results are combined, so a two-part question gets knowledge for both parts, while a single-part question is matched as before. The room available grows with the question rather than with the workspace. Asking two things costs a little more than asking one. Having ten thousand memories instead of a hundred costs the same. ## What to read next - [How retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works) for the selection this delivery model sits on top of. - [How hooks work](/docs/hooks/how-hooks-work) for how the selected slice reaches the assistant before its first tool call. - [How Pathrule proves hard claims](/docs/start/technical-proof) for how claims like the cross-language behaviour are tested. ## /docs/retrieval/co-change # Files that change together Some files travel in pairs. A route and its validator. A migration and the type that mirrors it. A component and the token file it reads. Nobody writes that down, and it is rarely visible in the folder structure, but everyone on the team knows it after a few months. Pathrule learns it from the work itself. When your agents log what they did, each entry carries the paths it touched. If two paths keep appearing in the same piece of work, Pathrule records that they change together. On a Cloud workspace it also gets a head start from your git history, so the signal is useful from the first week rather than after a few months. ## What it does for retrieval Path scope and meaning-based matching both start from where you are. Co-change adds the files next to it. When the assistant is working in `/apps/api/payments/refund.ts`, retrieval already considers what is pinned to that path and what matches the intent. Co-change lets knowledge attached to the paths that habitually move with it rise as well. So a rule about the ledger writer can reach a session that never mentioned the ledger, because in this codebase refunds and the ledger have always been edited together. This matters most for the knowledge nobody thought to attach in two places. A decision recorded once, on the file where it was made, can still reach the sessions that need it. ### What the assistant sees On a Cloud workspace, co-change shows up in the context an agent asks Pathrule for (through `pathrule_get_context`) in three places: - **A heads-up.** When one neighbour moves with the file in front of the assistant especially often, the assistant gets a single line saying so: that file typically changes together with this one. One line at most, and only for a strong relationship, so it reads as a warning rather than noise. - **Related paths.** Alongside the context for a focused or deep request, the assistant receives a short list of the paths that habitually change with the one it is working on. - **Coupled areas in a deep answer.** When an agent asks for deep context, the answer names the parts of the workspace coupled to the area in question, with the titles of the memories, rules and skills attached to them. Fetching this is handled on its own, so a failure to fetch it does not cost a turn the memories and rules it was there to accompany. ## How the relationship is measured A logged pair counts when both paths appear in the **same logged piece of work**. Sharing a folder is not enough, and neither is being changed on the same day by different tasks. The unit is one piece of work, because that is what indicates a real dependency rather than a coincidence of layout. The relationships are rebuilt from recent activity, so a relationship which stops happening fades without anyone having to remove it. A refactor that splits two files apart shows up as their relationship weakening over the following weeks. ### The head start from git history A new workspace has no logged work yet, which is exactly when knowing the neighbours would help most. So on a Cloud workspace, the first time an agent asks Pathrule for deep context, the local runtime reads the file paths of recent git history. Files changed in the same commit form a pair, and very large commits, which are usually refactors or renames, are skipped because they pair everything with everything. The resulting file path pairs, with how often each pair occurred, are saved to the workspace in Pathrule Cloud. This happens once, without a prompt, and reads nothing but file paths. As your team logs work, the relationships it records count for more and the git seed counts for less, so the picture moves from how the code changed in the past to how your team works on it now. ## What it is built from, and what it is not The signal is built **only** from file paths: the paths in the work your agents log, and on a Cloud workspace the file paths of recent git history. Pathrule does not read your source code, your diffs or your commit messages to compute it, and nothing about a file other than its path is part of it. A local workspace, used without an account, has no git seed. Its pairs come from logged work alone, which has a practical consequence worth knowing: it needs a real editing history. A workspace where every logged task touches exactly one file produces no pairs at all, because there is nothing to pair. In that case retrieval keeps working from path scope and meaning, and co-change contributes nothing rather than guessing. It is also per workspace. Relationships learned in one workspace do not carry over to another, and the signal sits behind the same access control as the rest of your knowledge. ## Where to look Co-change works in the background, so there is nothing to configure and nothing to switch on. It becomes more useful as your team logs more work, which is the same thing that makes [work episodes](/docs/content/work-episodes) and [suggestions](/docs/content/suggestions) more useful. If your agents are logging their work, this is already accumulating. [What Pathrule computes](/docs/start/what-pathrule-computes#what-none-of-it-is-built-from) lists what Pathrule reads from a checkout. ## /docs/retrieval/friction # Files that slow an assistant down Some files are harder for an assistant to work in than others, and the reason is usually not the code itself. A path in your docs that moved. A generated file that cannot be edited safely. A directory that needs a permission the agent does not have. You already know which files those are, roughly, from having been annoyed by them. Pathrule records it precisely. ## What gets recorded When a tool an assistant calls fails, three things are stored: the kind of tool, the file it was working on, and a short code for how it failed. `file_not_found`, `permission_denied`, `timeout`, `rate_limit`, `token_limit`, `syntax_error`, or `unknown` when the failure is real but nothing recognises it. That is the whole record. Not the command. Not the error message. Not the file. A count and a code, attached to a path. On a Cloud workspace these counts and codes are stored with the workspace in Pathrule Cloud. The failure is observed, not reported. Pathrule's tool hook watches the call itself, so the count does not depend on the assistant noticing its own mistake, remembering a session, or calling anything afterwards. An assistant that fails quietly and moves on is recorded exactly like one that announces it. How long the call took is part of the same observation, which is what lets a command that hung be told apart from one that refused. This applies to clients where Pathrule has tool hooks: Claude Code, Codex, Cursor and GitHub Copilot. Windsurf has no Pathrule hooks, so its tool calls are not observed this way. The path is normalised to workspace-relative form first, which matters more than it sounds. An absolute path on a laptop is `/Users//…`, and that name has no business travelling to shared knowledge. Relative paths also mean the same file groups correctly across a team, instead of once per machine. ## What it is used for **A picture of where work gets stuck.** Failures group by file, tool and code over time. What comes out is a short list rather than a chart: the files an assistant fails in most, and how. A file that keeps appearing under `file_not_found` is usually a stale path somewhere in your own instructions. One under `syntax_error` is usually a file that is genuinely awkward to edit. One under `permission_denied` is usually a setup problem you can fix once. **Retrieval learning.** If a turn received knowledge from Pathrule and still ran into failures, that knowledge takes a negative signal, and some kinds of failure count for more than an ordinary miss because they tend to mean the guidance sent the assistant somewhere it could not go. The signal joins the loop described in [how retrieval finds the right knowledge](/docs/retrieval/how-retrieval-works). Knowledge that keeps showing up in turns that go badly gradually becomes less likely to be chosen, without anyone having to review it. ## What the signal cannot see This part depends on which assistant you use, and it is not uniform. File tools report failures properly. A read, edit or write that fails arrives with its message, gets classified, and lands on the right file. That is the case that matters, because a file path is what makes a count actionable. Shell commands often do not. Some assistants report no exit code at all, so a command that fails and one that succeeds arrive looking identical. Pathrule does not infer a failure from output text: a search result can legitimately contain the words "no such file or directory", and a wrong failure attached to a file is worse than a missing one. When the assistant does not report a failure, nothing is recorded, and when it reports one that no rule recognises, the code is `unknown` rather than a guess. ## What it does not do Recording a failure does not block a tool call and does not appear in the assistant's context. A failure is a fact about your codebase, recorded after the fact. It does not change what the assistant is allowed to do, and a file with a bad record is not treated as off limits. Nothing here is a score attached to a person: the record is about files, not about who was working in them. ## /docs/cli/install # Install Pathrule CLI is the terminal first surface for Pathrule. It is published on npm as `@pathrule/cli` under the Apache-2.0 license, and it runs the local MCP server, the hook supervisor and the local cache for the agents you drive from a shell. This page covers installing it, signing in, connecting a repository and your AI clients, using it with no account, and taking it out of a project again. Every command is listed in the [command reference](/docs/cli/commands). ## Requirements - macOS, Linux, or Windows. - Node.js 20.11.1 or newer. The CLI checks the version on every run and stops with a clear message on an older one. - A modern shell: zsh, bash or fish, or PowerShell on Windows. - An AI coding assistant that speaks MCP. Pathrule CLI connects Claude Code, Codex, Cursor, Windsurf and GitHub Copilot. Optional for install, but you will want one to verify the hook flow. ## Install ### npm (macOS, Linux, Windows) `npm` is the install path on all three operating systems. It needs Node.js 20.11.1 or newer. ```bash npm install -g @pathrule/cli ``` On Windows, run this from PowerShell. Pathrule registers a Windows compatible hook command automatically, so the same `pathrule` commands work there exactly as they do in a Unix shell. To upgrade, run the same install with `@latest`: ```bash npm install -g @pathrule/cli@latest ``` Once a day, an interactive run checks for a newer release and prints a one line notice with this command. It only ever names a version newer than yours. `pathrule update` runs the same check on demand, and `pathrule config set update.policy manual` turns the daily check off. ### Direct download There is no standalone installer and no package manager formula. Install Pathrule CLI through npm on every operating system. ### Verify ```bash pathrule --version ``` The CLI prints its version and exits zero. If the command is not found, make sure the npm global install location is on your PATH and reopen the shell. ## Sign in Cloud use requires an account. Local setup skips sign-in; see [Use it without an account](#use-it-without-an-account). `pathrule login` signs in with a one-time code by default. The same command works on your own computer, over SSH and on a headless box or CI runner. ### Device code flow ```bash pathrule login ``` The CLI prints a one-time code. On a machine with a browser it opens the approval page with the code already filled in: sign in to your Pathrule account there and approve. On a headless box or over SSH, open the printed URL on any device, enter the code and approve. The terminal finishes signing in on its own, and your password never passes through it. Pass `--no-open` to keep the CLI from opening a browser at all. It prints the URL instead. Older guides use `pathrule login --device-code`, which is still accepted and runs this same flow. ### Browser PKCE flow ```bash pathrule login --browser-callback ``` This signs in with GitHub in a browser on the same machine and returns the session to the terminal over a callback on your own machine, secured with PKCE. If your account uses two-factor authentication, the CLI asks for the code. It needs an interactive terminal and a browser here. When the callback cannot be used, the CLI says so and continues with the device code flow, and with `--no-open` or in a script it uses the device code flow from the start. `pathrule whoami` shows the account you are signed in as. `pathrule logout` signs the CLI out, and `pathrule logout --all` also signs out the other Pathrule surfaces on this machine, such as the VS Code extension. ## Attach a workspace A workspace is the unit Pathrule scopes content to. The CLI always attaches the folder you run it in, so change into the repository first. There is no option that takes a path. The guided route does everything in one run: ```bash cd ~/repos/my-team pathrule setup ``` `pathrule setup` starts by choosing **Pathrule Cloud** or **Local**. Cloud is the recommended managed start, with accounts, organizations and shared intelligence. Local runs on this machine and requires no account. Setup connects the workspace and the AI clients you choose. On an Apple Silicon Mac it also offers the optional [on-device model](/docs/intelligence/local-model), which you can skip. Cloud setup can attach an existing workspace or create one for this folder. The local runtime then delivers through the supported client configuration and hooks. To do it step by step: ```bash cd ~/repos/my-team pathrule workspace list pathrule workspace attach my-team ``` `pathrule workspace attach` takes the workspace's exact name or its id. With no argument it attaches your current workspace. To start a new workspace instead, `pathrule init` creates one named after the folder and attaches it in one step, and `pathrule init my-team` or `pathrule workspace create my-team` does the same with the name you give. Workspaces come from your current organization: `pathrule org list` shows yours and `pathrule org use ` switches. After attach, any time you run an AI client in this folder or below it, the runtime knows which workspace's content to serve. In a script, `pathrule setup` takes its answers as options and needs `--yes` to act: ```bash pathrule setup --workspace my-team --target all --yes ``` ## Connect your AI clients `pathrule setup` asks which AI clients you use, installs them, and remembers the choice for this workspace. To connect one by hand: ```bash pathrule install cursor pathrule sync ``` `pathrule install` takes `claude`, `cursor`, `codex`, `windsurf` or `copilot`, and with no client it installs all five. It writes Pathrule's MCP server entry into that client's own user-level configuration and leaves every other server there alone. GitHub Copilot gets two entries, one for the Copilot CLI and one for VS Code. `pathrule uninstall ` removes the entry again. `pathrule sync` writes the files your clients read into the repository and refreshes the local hook index. Run it in the folder the workspace is attached to, after attaching and whenever you want those files to catch up with the workspace. It writes for the AI clients chosen for this workspace in `pathrule setup`. When none are chosen, it writes for the clients whose Pathrule files are already in the repository, and for Claude Code when there are none. `pathrule sync --skills` copies the workspace's skills into your clients' skill folders. ## What Pathrule writes into your repository Pathrule writes into the places each client already reads, so nothing new has to be configured in the client. | Client | Instruction files | Hook configuration | | --- | --- | --- | | Claude Code | `CLAUDE.md` at the root, and in folders that carry their own knowledge, plus `pathrule-*.md` files under `.claude/rules/` | Pathrule's entries in `.claude/settings.json` | | Codex | `AGENTS.md` at the root, and in folders that carry their own knowledge | `.codex/hooks.json`, plus a marked block in `.codex/config.toml` that turns hooks on | | Cursor | `pathrule-*.mdc` files under `.cursor/rules/`, and the legacy `.cursorrules` | `.cursor/hooks.json` | | Windsurf | `pathrule-*.md` files under `.windsurf/rules/`, and the legacy `.windsurfrules` | None. Windsurf reads the instruction files and MCP. | | GitHub Copilot | `.github/copilot-instructions.md`, and `pathrule*.instructions.md` files under `.github/instructions/` | `.github/hooks/pathrule.json` | Pathrule marks what it writes: its instruction files carry a Pathrule banner, and anything it adds to a file of yours sits inside a marked block. When an instruction file such as `CLAUDE.md` or `AGENTS.md` already holds your own content, Pathrule saves your version as a backup before it writes, or writes inside its marked block and leaves the rest of the file alone. A `.pathrule` folder at the repository root keeps Pathrule's record of the files it manages, together with those backups. Skills synced with `pathrule sync --skills` go into each client's skill folder, such as `.claude/skills/`, and when the repository has a `.gitignore`, Pathrule adds a commented section that keeps those folders out of git until you delete it. Outside the repository, `pathrule install` writes the MCP entries into each client's user-level configuration, and the CLI keeps its session, cache and hook script in your Pathrule home, `~/.pathrule` by default. To see what Pathrule manages in a folder without changing anything, run `pathrule doctor`, which lists each managed file with the surface and version that wrote it. The client pages go deeper: [Claude Code](/docs/mcp/claude-code), [Codex](/docs/mcp/codex), [Cursor](/docs/mcp/cursor), [Windsurf](/docs/mcp/windsurf) and [GitHub Copilot](/docs/mcp/copilot). ## Use it without an account Pathrule CLI also runs entirely on your machine, with no account and no cloud. Inside the project: ```bash cd ~/repos/my-project pathrule setup --local ``` `pathrule init --local` creates a local workspace for the current folder. `pathrule setup --local` does the same, then installs the local MCP entry for every AI client, or for one with `--target `, installs the hooks and writes the repository files, all without signing in. Your agent writes memories, rules and skills through Pathrule's MCP tools, and you read and search them from the terminal with `--local`, for example `pathrule memory list --local`. See [Work without an account](/docs/cli/commands#work-without-an-account) for every local command and [Open source core](/docs/editions/open-source-core) for what the local edition includes. ### Open-source-only setup Pathrule CLI itself is open source under Apache-2.0, and local mode runs it with no account and no cloud service. The on-device model that setup offers on an Apple Silicon Mac is optional: decline it when setup asks, or remove it later with `pathrule intelligence remove`. Everything that does not need the model keeps working without it. [Open source core](/docs/editions/open-source-core) lists what is open source today and what is proprietary. ## Verify the wiring The doctor is the single command that confirms the setup end to end. It only reads; it never changes anything. ```bash pathrule doctor ``` It checks: - You are signed in, and an organization and a workspace are selected. - The current folder is the one the workspace is attached to. - Each AI client has Pathrule's MCP entry installed. - The files Pathrule manages in this folder, with the surface and version that wrote each one. A file written by another surface or a newer version is flagged. When something needs attention, doctor names the next command, such as `pathrule login` or `pathrule attach `. `pathrule doctor --json` returns the full report for a script, which also covers the Node.js version and flags an MCP entry whose launch command is out of date, and it exits non-zero when a check fails. An out-of-date entry is fixed by `pathrule repair`, which rewrites Pathrule's entries in your client configurations, leaves every other server alone, and writes the repository files again. ## Remove Pathrule from a project Start with the read-only plan from the repository: ```bash pathrule eject ``` It lists Pathrule-owned files and managed regions, including any recovery of your earlier content. Review that plan, then apply it explicitly: ```bash pathrule eject --apply ``` For a Cloud folder attachment, `pathrule detach` disconnects the local folder without deleting the Cloud workspace. The VS Code extension can also unbind its folder. Native integrations have their own recorded setup. Use `pathrule integrations remove ` to remove one. Settings-based MCP entries installed with `pathrule install` can be removed with `pathrule uninstall `. These operations preserve unrelated client settings and servers. ## What to read next - [Command reference](/docs/cli/commands) for every command and option. - [Quickstart](/docs/start/quickstart) to write your first memory and watch the hook fire. - [How hooks work](/docs/hooks/how-hooks-work) for the model that explains what doctor is verifying. - [MCP overview](/docs/mcp/overview) for the tools the assistant calls once the runtime is up. ## /docs/cli/commands # Command reference Every command in Pathrule CLI, grouped the way `pathrule help` groups them. Each entry says what the command does and which options matter. For a first setup, start with [Install](/docs/cli/install). ```bash pathrule [subcommand] [arguments] [options] pathrule help ``` ## Global options | Option | What it does | | --- | --- | | `--json` | Prints one machine-readable JSON object instead of human output. It also turns off color, prompts and browser windows. | | `--yes` | Accepts the confirmation that `setup` and `cache prune` ask for before they change anything. | | `--no-open` | Never opens a browser. A command that would open one prints the URL instead. | | `--no-color` | Prints plain output with no color. Setting the `NO_COLOR` environment variable to `1` does the same. | | `--local` | Runs `init`, `setup`, `sync`, `search` and the `memory`, `rule` and `skill` commands against an account-free local store. See [Work without an account](#work-without-an-account). | | `--help`, `-h` | Prints the command list. | | `--version`, `-v` | Prints the CLI version. | When the `CI` environment variable is `true`, the CLI also skips prompts and browser windows, so a command never waits for input on a runner. ### Options a command does not know The CLI does not reject an option it does not recognise. Most commands read it as a plain argument, which makes the command fail or act on the wrong target. `pathrule workspace attach --path ~/repos/app` looks for a workspace named `--path`, and `pathrule install --client cursor` stops because `--client` is not a client name. `setup`, `invite`, `team`, and `memory add`, `rule add` and `skill add` check their own options and stop with an error on one they do not know. Use the options on this page or in `pathrule help`. ### JSON output With `--json`, every reply is one JSON object with `ok`, `command` and `cwd`, plus `data` when the command succeeded, or `error` with a `code` and a `message` when it did not. Some replies add `next_steps` with the commands to run next. `--json` is available on commands that advertise it in `--help`. `snapshot` and `eject` do not support it, so run that one without it. Sign in with plain `pathrule login`, since the sign-in flow needs to show you a code. ### Exit codes `0` means the command did what you asked. Most usage errors, such as a missing argument or an unknown client name, exit with `64`. Any other failure exits with `1`, and `pathrule doctor` exits with `1` when a check fails. On a Node.js version older than 20.11.1, every command stops with `78` before it does anything. ## Get started | Command | What it does | | --- | --- | | `pathrule setup` | Connects the current folder in one guided run. It signs you in if needed, suggests the workspaces in your organization that match this folder (the same git remote, for example), attaches the one you pick or creates one named after the folder, asks which AI clients to connect, installs them, writes the files they read, and offers to start a first project scan in one of them. On an Apple Silicon Mac it finally offers the optional [on-device model](/docs/intelligence/local-model). | | `pathrule init [name]` | Creates a workspace in your current organization, named after the folder unless you give a name, and attaches the current folder to it. | Without a terminal to prompt in, `pathrule setup` only prints a plan: the organization, the matching workspaces, and the command that would attach the best one. These options make it act, and acting needs `--yes`: - `--workspace ` attaches an existing workspace. `--workspace-id` is the same option. - `--create-workspace` creates a workspace named after the folder. Add `--workspace-name ` to name it yourself. - `--select-workspace ` makes a workspace current without attaching this folder. - `--org ` switches organization first. - `--target ` installs the MCP entry for `claude`, `cursor`, `codex`, `windsurf`, `copilot` or `all`. ```bash pathrule setup --workspace my-project --target all --yes ``` `pathrule setup bootstrap --rerun` scans the repository's docs and commit history again and prepares fresh memory and rule candidates for the current workspace's first project scan. ## Account and context | Command | What it does | | --- | --- | | `pathrule login` | Signs in with a one-time code. The CLI prints the code and opens the approval page in your browser with the code filled in, or prints the URL to open on any device when there is no browser. `--no-open` never opens a browser. `--browser-callback` signs in with GitHub in a browser on this machine and returns over a local callback, and falls back to the code when that is not possible. `--device-code` is accepted and runs the default code flow. | | `pathrule logout` | Signs Pathrule CLI out on this machine. `--all` also signs out the other Pathrule surfaces on this machine, such as the VS Code extension. | | `pathrule whoami` | Shows the signed-in account and when the session expires. | | `pathrule org list` | Lists your organizations with your role, and marks the current one with `*`. Plain `pathrule org` does the same. | | `pathrule org current` | Shows the current organization and your role in it. | | `pathrule org use ` | Switches the current organization. | | `pathrule workspace list` | Lists the workspaces in the current organization and marks the current one with `*`. Plain `pathrule workspace` does the same. | | `pathrule workspace current` | Shows the current workspace. | | `pathrule workspace use ` | Makes a workspace current without attaching a folder. | | `pathrule workspace create ` | Creates a workspace and attaches the current folder to it. | | `pathrule workspace attach [name-or-id]` | Attaches the current folder to an existing workspace, matched by its exact name or its id. With no argument it attaches the current workspace. There is no path option: run it inside the folder. | | `pathrule workspace detach [name-or-id]` | Removes the workspace's folder attachment on this machine. The workspace and its content stay in Pathrule. | | `pathrule workspace inspect` | Shows the current workspace in detail: its organization and plan, where it is attached, its git remote, how many memories, rules and skills it holds, plan usage, which AI clients are set up, and recent activity. | Attaching, creating, `init` and `workspace use` also make that workspace current. Commands such as `memory`, `rule`, `skill`, `search` and `sync` work on the current workspace. ## Workspace setup | Command | What it does | | --- | --- | | `pathrule attach [name-or-id]` | The same as `workspace attach`. | | `pathrule detach [name-or-id]` | The same as `workspace detach`. | | `pathrule install [client]` | Writes Pathrule's MCP server entry into an AI client's own user-level configuration and leaves every other server in it alone. The client is `claude` (or `claude-code`), `cursor`, `codex`, `windsurf`, `copilot` (or `github-copilot`), or `all`, which is the default. GitHub Copilot gets two entries, one for the Copilot CLI and one for VS Code. | | `pathrule uninstall [client]` | Removes Pathrule's MCP entry from that client's configuration, or from all five. | | `pathrule sync` | Writes the files your AI clients read into the repository: instruction files, hook configuration and the local hook index. Run it in the folder the workspace is attached to. `--skills` syncs only the workspace's skills into your clients' skill folders. `--local` syncs an account-free workspace. | | `pathrule mcp run` | Starts Pathrule's local MCP server over standard input and output. This is the command the MCP entry written by `pathrule install` launches, so your AI client runs it and you do not need to. | `pathrule sync` writes files for the AI clients chosen for this workspace in `pathrule setup`. When none are chosen, it writes for the clients whose Pathrule files are already in the repository, and for Claude Code when there are none. Claude Code's `CLAUDE.md` and hook entry are refreshed on every sync. [Install](/docs/cli/install#what-pathrule-writes-into-your-repository) lists each file. To take Pathrule back out of a repository, see [Remove Pathrule from a project](/docs/cli/install#remove-pathrule-from-a-project). ## Knowledge | Command | What it does | | --- | --- | | `pathrule search ` | Searches memories, rules and skills in the current workspace. `--type memory,rule` narrows the kinds, `--path /apps/api` narrows to a path, and `--limit ` caps the results. | | `pathrule memory list` | Lists memories. `--path` or a leading path narrows the list, so `pathrule memory list /apps/api` and `pathrule /apps/api memory list` are the same. `--limit ` caps it. | | `pathrule memory read ` | Prints a memory. Pass `--print` to print long content in full in the terminal. | | `pathrule memory add` | Writes a memory with `--path --title `. The body comes from `--body`, from standard input, or from your editor (`VISUAL` or `EDITOR`) when you give neither. `--allow-duplicate` skips the duplicate check. | | `pathrule rule list`, `read`, `add` | The same for rules. `rule add` takes `--name` instead of `--title`, plus `--priority` (`high`, `medium` or `low`, default `medium`) and `--scope` (`project`, `folder` or `file_type`, default `project`). | | `pathrule skill list`, `read`, `add` | The same for skills. `skill add` takes `--name` and an optional `--description`. | | `pathrule refresh list` | Lists the open refresh tasks, the requests to update knowledge that has gone stale. `--include-in-progress` adds the claimed ones, and `--limit <n>` caps the list. | | `pathrule refresh claim [id]` | Claims a refresh task, the next open one when you give no id, and prints its brief. | | `pathrule refresh resolve <id> --status applied` | Closes a refresh task as `applied` or `rejected`. `--note "<text>"` records why. | | `pathrule snapshot` | Captures an inventory of the current folder, with its file tree, manifests and short docs samples, git branch and recent history, and uploads it to the workspace. It reads no other file contents. `--dry-run` prints it without uploading, and `--notes "<text>"` attaches a note. | | `pathrule snapshot list [n]` | Lists the workspace's most recent snapshots. | ## Your working preferences and the local model | Command | What it does | | --- | --- | | `pathrule me list` | Lists what [User Intelligence](/docs/intelligence/user-intelligence) holds about how you work, both what is in use and what is not yet. Plain `pathrule me` does the same. | | `pathrule me teach "<sentence>"` | Teaches a preference in your own words. It needs the optional on-device model. | | `pathrule me explain <id>` | Shows one preference with the evidence behind it. The id is the short id `me list` prints. | | `pathrule me scope <id>` | Keeps a preference to the workspace you run it in. `--everywhere` lets it apply in every workspace. | | `pathrule me forget <id>` | Stops using a preference and keeps it as rejected, so the same evidence does not bring it back. `--delete` removes it entirely. | | `pathrule me context "<task>"` | Prints what an agent would receive for that task, and which preferences were held back and why. | | `pathrule intelligence status` | Shows whether the [on-device model](/docs/intelligence/local-model) is installed, its version, and whether an update is available. Plain `pathrule intelligence` does the same. | | `pathrule intelligence install` | Sets up the local runtime the model needs, then downloads the model and verifies its checksum before it becomes active. It needs an Apple Silicon Mac. | | `pathrule intelligence update` | Installs a newer model when one is available. If the update fails, the model you had stays in place. | | `pathrule intelligence remove` | Removes the model. Everything that does not need it keeps working as before. | ## Local Console and agent integrations | Command | What it does | | --- | --- | | `pathrule ui` | Opens the accountless Local Console for knowledge, activity and Local Signals. `--port`, `--no-open` and `--json` control how it opens. | | `pathrule integrations` | Interactive setup for Claude Code and Codex. Outside an interactive terminal, lists the setup. | | `pathrule integrations add claude codex --local --dry-run` | Previews a native integration without writing. Choose `--cloud` for Cloud mode. | | `pathrule integrations list` | Lists detected agents and recorded integrations. | | `pathrule integrations doctor` | Read-only checks of the installed integration. | | `pathrule integrations repair` | Reapplies recorded Pathrule integrations. | | `pathrule integrations remove <agent>` | Removes the recorded integration. | | `pathrule telemetry` | Shows the telemetry preference and whether this CLI can send. | | `pathrule telemetry enable` | Opts a signed-in managed CLI into anonymous usage events. | | `pathrule telemetry disable` | Turns them off. | See [Local Console](/docs/surfaces/local-console) and [Native agent integrations](/docs/mcp/native-integrations). ## Remove project integration `pathrule eject` shows a read-only plan for removing the files and managed regions Pathrule owns in the current repository. `pathrule eject --apply` carries it out after you review it. Eject does not have a `--json` form. Native plugins are removed through `pathrule integrations remove <agent>`. ## Diagnostics and maintenance | Command | What it does | | --- | --- | | `pathrule status` | Shows the signed-in account, the current organization and plan, the current workspace, and whether this folder is attached. | | `pathrule doctor` | Runs read-only checks: sign-in, organization, workspace, whether this folder is attached, whether each AI client has Pathrule's MCP entry, and the files Pathrule manages in this folder with the surface and version that wrote each one. It names the next command when something needs attention. With `--json` the report also covers the Node.js version and flags an MCP entry whose launch command is out of date. `--bundle` writes a support file with credentials and local paths redacted. | | `pathrule repair` | Rewrites out-of-date Pathrule MCP entries in your AI client configurations, leaving other servers alone, writes the repository files again, and reports what changed. | | `pathrule preflight <action>` | Checks whether your plan allows an action before you try it. The action is `create_workspace`, `write_memory`, `write_rule`, `write_skill`, `sync_agents` or `materialize_skills`. | | `pathrule cache prune` | Lists stale local cache folders without removing them. `--yes` removes them. | | `pathrule config get <key>` | Reads a preference: `update.policy`, `telemetry.enabled` or `telemetry.id`. | | `pathrule config set <key> <value>` | `update.policy manual` stops the daily update check, while `notify` and `auto` keep it. `telemetry.enabled false` turns the anonymous usage telemetry off. Setting the `NO_TELEMETRY` environment variable to `1` does the same for one run or shell. | | `pathrule config reset telemetry-id` | Replaces the telemetry id with a new one. | | `pathrule update` | Checks for a newer CLI and prints the command that installs it. It never installs anything itself. | Once a day, an interactive run also checks for a newer CLI and prints a one line notice with the upgrade command. It only names a version that is newer than yours. The standalone local CLI sends no telemetry. A signed-in managed CLI sends anonymous usage events only after you opt in with `pathrule telemetry enable`. Events carry no code, paths, prompts, knowledge, email or account and workspace ids. Turn them off with `pathrule telemetry disable`; `NO_TELEMETRY=1`, `DO_NOT_TRACK=1` and CI keep them off. ## Team and billing | Command | What it does | | --- | --- | | `pathrule team` | Lists the members and pending invites of the current organization, or of `--org <slug-or-id>`. `pathrule team open` opens Pathrule Web, where members are managed. | | `pathrule invite <email>` | Invites a teammate to the current organization as an editor. `--role` sets `admin`, `editor` or `viewer`, and `--org` and `--workspace` set the organization and workspace. It reports whether the invite email went out and how the invite affects your seats. | | `pathrule billing` | Opens the organization's billing in Pathrule Web. | | `pathrule upgrade` | Opens billing to pick a plan. | ## Help and version | Command | What it does | | --- | --- | | `pathrule help` | Prints the command list. | | `pathrule version` | Prints the CLI version, the same as `--version`. | ## Work without an account Pathrule CLI runs on a local store with no account and no cloud. Run these inside the project: ```bash cd ~/repos/my-project pathrule init --local pathrule setup --local ``` `pathrule init --local [name]` creates a local workspace for the current folder, kept on this machine, and reuses the one that already covers the folder if there is one. `pathrule setup --local` does the same and then installs the local MCP entry for every AI client, or for one with `--target <client>`, installs the hooks and writes the repository files, all without signing in. `--workspace-name <name>` names a new workspace. Options that need an account, such as `--org` or `--workspace`, stop with an error. In a local workspace your AI agent writes memories, rules and skills through Pathrule's MCP tools. From the terminal you read and search them with `--local`: ```bash pathrule memory list --local pathrule rule read "No service key in browser code" --local pathrule search "migrations" --local pathrule sync --local ``` `memory add`, `rule add` and `skill add` need an account. With `--local` they say so and change nothing. See [Open source core](/docs/editions/open-source-core) for what the local edition includes. ## What to read next - [Install](/docs/cli/install) for the first setup, what Pathrule writes into a repository, and how to remove it. - [Pathrule CLI](/docs/surfaces/cli) for what the CLI owns and when to use it. - [User Intelligence](/docs/intelligence/user-intelligence) for what `pathrule me` manages.