Guida rapida

Parti da un repository locale e dall'agente che usi già. La CLI è lo strumento di installazione e l'interfaccia da terminale di Pathrule. Collega gli agenti supportati su macOS, Linux o Windows, e la stessa conoscenza del workspace è raggiungibile anche dall'estensione per VS Code e tramite MCP. Il modello opzionale on-device ha requisiti di piattaforma a parte.

Se vuoi prima esplorare un piccolo progetto locale, segui Workspace di esempio. Lo crei e lo modifichi tu.

1. Installa un runtime

Installa la CLI con Node.js 20.11.1 o versione successiva:

npm i -g @pathrule/cli

• CLI esegue Pathrule nel terminale, via SSH e nelle automazioni. Per i requisiti dettagliati consulta Installazione della CLI.
• Estensione per VS Code ti permette di consultare e modificare la conoscenza direttamente nell'editor, e può anche collegare i tuoi client di IA. Consulta Pathrule per VS Code.

Puoi usarle entrambe con la stessa conoscenza del workspace. Con Cloud sono collegate tramite il tuo account. L'uso locale della CLI non richiede alcun account.

2. Accedi

pathrule setup ti chiede di scegliere tra Cloud e Local. Con Cloud accedi al tuo account per condividere la conoscenza del workspace. Local non richiede alcun account. Usa pathrule setup --local per scegliere direttamente Local e saltare l'accesso. Locale o Cloud mette a confronto le due modalità. Prosegui con il passo 3 per avviare la configurazione.

Con Cloud puoi anche accedere separatamente con un codice monouso, da desktop, via SSH o su una macchina headless:

pathrule login

La CLI mostra il codice e apre la pagina di approvazione con il codice già inserito. Se sulla macchina non c'è un browser, apri l'URL mostrato da qualsiasi dispositivo, inserisci il codice e approva. Se invece vuoi usare il flusso con callback nel browser su questa macchina, esegui pathrule login --browser-callback.

Con entrambi i flussi risulti autenticato, con una sessione che il runtime mantiene aggiornata in background.

3. Crea un workspace

Il workspace è l'unità a cui Pathrule lega i contenuti. Rispecchia un repository, o un piccolo gruppo di repository, sulla tua macchina.

Con la CLI tutto avviene nella cartella in cui la esegui, quindi spostati prima nel repository. La procedura guidata crea o collega il workspace e collega i tuoi client di IA in un'unica esecuzione:

cd ~/repos/my-team
pathrule setup

La configurazione mostra la tua organizzazione, suggerisce i workspace corrispondenti oppure ne crea uno per questa cartella, e ti chiede quali client di IA supportati collegare. Può poi proporti una prima scansione del progetto, eseguita dal tuo agente, che propone memorie, regole e skill da approvare. Per un workspace conservato su questa macchina senza account, esegui pathrule setup --local; consulta la configurazione locale.

Per configurare Cloud manualmente, pathrule init crea un workspace con il nome della cartella e collega la cartella al workspace. Per collegare un workspace Cloud esistente indica il nome o l'id:

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

Non esiste un'opzione che accetti un percorso: la CLI collega sempre la cartella corrente. Poi collega i tuoi client con pathrule install <client> e pathrule sync, come descritto in Installazione della CLI. Il runtime usa questa associazione per ricondurre la directory corrente a un workspace.

4. Scrivi la tua prima memoria

Il modo più rapido per verificare che tutto sia collegato correttamente è scrivere una memoria e poi aprire il tuo assistente nell'ambito che copre. Per questa guida, mettila nella radice del workspace.

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.

Dal terminale, su un workspace Cloud, la memoria si crea con un solo comando. Senza --body, la CLI apre il tuo editor (VISUAL o EDITOR) per scrivere il corpo; in alternativa puoi passare --body o inviare il testo tramite pipe.

pathrule memory add --path / --title "Our database is Postgres on Supabase"

Subito dopo esegui pathrule sync nel repository, così i file e l'indice locale letti dai tuoi client recepiscono la nuova memoria.

In VS Code, usa New Memory… nella vista di Pathrule. Su un workspace locale, scrivi nella Local Console oppure chiedi al tuo agente di salvarla tramite gli strumenti MCP di Pathrule. La CLI elenca, legge e cerca la conoscenza locale, ma non la aggiunge.

5. Guarda l'hook in azione

Apri Claude Code o Codex nella directory che hai collegato al workspace. Inizia un nuovo turno e fai una domanda qualsiasi che tocchi l'area coperta dalla memoria.

Quando invii il prompt, l'hook di Pathrule legge la porzione in cache per quel percorso, formatta le memorie e le regole pertinenti e le passa all'agente prima della sua prima chiamata a uno strumento. Vedrai comparire la memoria nell'area del contesto che il tuo agente mette a disposizione, senza passaggi aggiuntivi a metà attività.

Cursor e GitHub Copilot non hanno un hook del prompt: Pathrule li raggiunge tramite hook di sessione e di strumento, i loro file di istruzioni e MCP. Windsurf non ha hook e usa il proprio file di regole per l'avvio della sessione e MCP per il contesto più approfondito; per questi client, quindi, verifica il funzionamento con le rispettive guide: Cursor, GitHub Copilot e Windsurf.

Se non compare nulla, esegui la diagnostica.

pathrule doctor

La diagnostica controlla l'accesso, il workspace e se questa cartella è collegata al workspace, la voce MCP di ciascun client di IA e i file che Pathrule gestisce nella cartella, e per ogni elemento che richiede attenzione indica il comando da eseguire. Una voce di un client non aggiornata si sistema con pathrule repair.

6. Aggiungi una regola

Le memorie sono fatti. Le regole sono vincoli. Aggiungi una regola sullo stesso percorso. Su un workspace Cloud, dal terminale:

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."

Puoi anche usare New Rule… nell'estensione per VS Code, oppure chiedere al tuo agente di salvare la regola.

Riapri Claude Code. La regola arriva insieme alla memoria. Con la priorità high finisce tra le prime posizioni. Quando viene consegnata come contesto, una regola è un requisito che l'agente riceve l'istruzione di rispettare, non un blocco. Una regola può anche includere un vincolo eseguibile: un agente può proporlo, il vincolo viene salvato come proposta e non viene applicato, e solo dopo l'approvazione di una persona l'hook pre-tool può bloccare una modifica corrispondente, nei client i cui hook di strumento rispettano questa decisione. Consulta Le regole come guardrail.

Cosa leggere dopo

• Concetti fondamentali per il modello di dati alla base di memorie, regole e skill.
• Come funzionano gli hook per capire cosa succede tra la cache e l'agente.
• Panoramica di MCP per gli strumenti che il tuo assistente usa per leggere e scrivere i contenuti.
• Riferimento dei comandi della CLI per tutti i comandi della CLI di Pathrule.