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.

For a small local project you can explore first, follow Example workspace. You create and edit it yourself.

1. Install a runtime

Install the CLI with Node.js 22.14.0 or newer:

npm i -g @pathrule/cli

• CLI runs Pathrule in the terminal, over SSH and in automation. See 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.

You can use both with the same workspace knowledge. Pathrule Cloud connects them through your account. Pathrule Local needs no account.

2. Sign in

Every folder is served by one edition, Pathrule Cloud or Pathrule Local. On a new install the device default is Pathrule Cloud, so pathrule setup in step 3 offers to sign you in when you are not. Pathrule Local needs no account: you will run pathrule setup --local in step 3 and can skip this step. Local or Cloud compares the two.

To sign in to Pathrule Cloud before setup, with a one-time code on a desktop, over SSH or on a headless box:

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. The terminal finishes signing in on its own.

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:

cd ~/repos/my-team
pathrule setup

On Pathrule Cloud, setup uses the workspace already attached to this folder, or an existing workspace with the folder's name, or creates one named after the folder in your current organization. It then writes Pathrule's MCP entry for every AI client it supports, and the hooks and repository files for Claude Code, and for Codex when the repository has Codex files. When the folder also has a Local workspace with knowledge, setup shows what it would copy to Pathrule Cloud and asks before copying anything. For a workspace kept on this machine with no account, run pathrule setup --local; see local setup.

To use an existing Cloud workspace instead, attach it by name or id:

cd ~/repos/my-team
pathrule workspace attach my-team
pathrule sync

There is no option that takes a path: the CLI always attaches the current folder. pathrule sync writes the hook and repository files for the attached workspace, and pathrule install <client> adds an AI client's MCP entry by hand, as CLI install describes. The runtime resolves your current directory to a workspace using that mapping, and pathrule status shows which edition and workspace serve the folder.

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.

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.

Ask your agent to save it as a Pathrule memory at the workspace root. It writes through Pathrule's MCP tools, with pathrule_write_memory. On a Local workspace you can also write it in the Local Console, which pathrule ui opens, and in VS Code you can use New Memory… in the Pathrule view.

The CLI lists, reads and searches knowledge in either edition, but it does not write it. pathrule memory list and pathrule memory read "Our database is Postgres on Supabase" read the memory back, and pathrule sync refreshes the files and the local index your clients read from the workspace.

5. Watch the hook fire

Open Claude Code or Codex in the directory you set up. 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, Windsurf and GitHub Copilot have no Pathrule hook. They reach the same knowledge through Pathrule's MCP tools when the agent calls them, so verify those clients with their guides: Cursor, GitHub Copilot and Windsurf.

If nothing appears, run the doctor.

pathrule doctor

The doctor checks which edition serves this folder, your sign-in and whether the folder is attached in a Cloud folder, each AI client's MCP entry, and the files Pathrule manages in the folder. In a Cloud folder it names the next command for anything that needs attention. pathrule install rewrites an out-of-date client entry.

6. Add a rule

Memories are facts. Rules are constraints. Add a rule at the same path: ask your agent to save a Pathrule rule named "No service key in browser code" at the workspace root, with priority high, saying never to use the SUPABASE_SERVICE_ROLE_KEY in any file under apps/web and to use the anon key plus row level security. The agent writes it with pathrule_write_rule.

You can also write the rule in the Local Console on a Local workspace, or use New Rule… in the VS Code extension.

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 Claude Code and Codex. See Rules as guardrails.

What to read next

• Core concepts for the data model behind memories, rules, and skills.
• How hooks work to understand what happens between the cache and the agent.
• MCP overview for the tool surface your assistant uses to read and write content.
• CLI command reference for every Pathrule CLI command.