Claude Code

Claude Code si collega al tuo workspace Pathrule tramite Pathrule CLI o l'estensione per VS Code. Pathrule offre due livelli di integrazione: gli hook, che inviano il contesto legato al percorso prima che l'agente agisca, e gli strumenti MCP, da cui Claude può attingere quando ha bisogno di altro. Claude Code è uno dei due client, insieme a Codex, che Pathrule raggiunge con un hook all'invio del prompt.

Questa pagina spiega cosa viene scritto nel tuo progetto, come si integrano i due livelli e come verificare l'integrazione dall'inizio alla fine.

Due livelli, un solo workspace

• Hook (push). Claude Code invoca il supervisore degli hook di Pathrule all'avvio della sessione, a ogni prompt e attorno alle chiamate agli strumenti su file e shell. Il supervisore legge dalla cache locale una porzione già calcolata e la restituisce come contesto.
• Strumenti MCP (pull). Quando il payload dell'hook non basta (prompt esplorativi, testo completo delle memorie, scritture), Claude chiama direttamente il server MCP di Pathrule tramite strumenti come pathrule_get_context e pathrule_write_memory.

Gli hook sono la modalità predefinita. Gli strumenti MCP sono la via per andare più a fondo. Entrambi si basano sullo stesso albero di contenuti.

File di supporto

Quando installi Pathrule in Claude Code, questi sono i file coinvolti.

• ~/.claude.json. La configurazione utente di Claude Code. Pathrule vi aggiunge la voce del suo server MCP e lascia intatti gli altri server.
• .claude/settings.json nel progetto. Pathrule unisce a questo file le proprie registrazioni degli hook e mantiene gli hook che hai aggiunto tu.
• CLAUDE.md. Con l'hook installato, la sezione di Pathrule in questo file è una breve nota che indica che Pathrule è attivo e che la sua conoscenza viene fornita dall'hook. Tutto ciò che hai scritto fuori da quella sezione resta tuo.
• .claude/rules/*.md. Scritti solo quando l'hook non è installato, come descritto più avanti.
• .claude/skills/<name>/SKILL.md. Le skill associate al tuo workspace, materializzate perché Claude possa invocarle per nome.

Il protocollo e la conoscenza legata ai percorsi non devono per forza stare in file. Quando l'hook di Claude Code è installato, il protocollo viaggia con l'hook SessionStart e la conoscenza arriva tramite gli hook per prompt e per strumento, quindi Pathrule rimuove la copia del protocollo e i file di conoscenza che scriveva nelle versioni precedenti. Oltre alla registrazione dell'hook, alla breve nota e alle tue skill, non scrive nulla nel tuo albero. Se l'hook non è installato, Pathrule ripiega sui file compilati: il protocollo completo e la panoramica del workspace in CLAUDE.md, una copia del protocollo in .claude/rules/pathrule-protocol.md, la conoscenza del workspace in .claude/rules/pathrule-knowledge.md e un CLAUDE.md in ogni directory a cui è associata della conoscenza.

Applicazione delle regole

Una regola ha una priorità (high, medium, low) che stabilisce con quanta evidenza viene presentata. La priorità non decide il blocco. Una regola blocca solo se ha un pattern di blocco approvato: una forma vietata nel contenuto, una posizione vietata per il file, o entrambe.

• Un assistente può proporre un pattern di blocco quando scrive o aggiorna una regola. La proposta viene salvata con la regola come proposta e non viene applicata. Un agente non può approvarla; nulla viene bloccato finché una persona non ha approvato il pattern.
• Su PreToolUse, prima di una modifica o di una scrittura, l'hook confronta il nuovo contenuto e il percorso di destinazione con ogni regola che ha un pattern di blocco approvato per quel percorso, qualunque sia la sua priorità.
• Se c'è una corrispondenza, l'hook nega la chiamata allo strumento prima che il file venga scritto. Claude vede Pathrule blocked: con il nome della regola, un'anteprima della regola, il messaggio approvato "fai invece così" e un riferimento alla regola completa, e riprova rispettando il vincolo.

Tutte le altre regole sono indicative. Arrivano come contesto e l'assistente decide come applicarle. Il blocco passa dall'hook locale; Remote MCP non ha hook, quindi presenta le regole solo come contesto.

Installazione

Tramite Pathrule CLI:

pathrule setup

Eseguilo nella cartella del progetto e scegli Claude Code quando ti chiede quali strumenti di IA usi. Il setup ti fa accedere a Pathrule Cloud se necessario, associa la cartella a un workspace, installa la voce MCP, ricorda la tua scelta per questa cartella e scrive l'hook e i file di supporto. Esegui invece pathrule setup --local per usare Pathrule senza account; in questo caso la conoscenza resta su questa macchina.

Per collegare i singoli pezzi a mano in una cartella già associata:

pathrule install claude
pathrule sync
pathrule doctor

pathrule install claude aggiunge la voce MCP a ~/.claude.json. pathrule sync installa lo script dell'hook e scrive .claude/settings.json, CLAUDE.md e le tue skill per gli strumenti di IA scelti per questa cartella.

Tramite l'estensione per VS Code, scegli Claude Code in Connect AI Clients. L'estensione scrive la stessa voce MCP e la stessa configurazione degli hook tramite la CLI integrata.

Remote MCP

Claude Code può collegarsi anche all'endpoint ospitato, senza alcuna installazione locale:

claude mcp add --transport http pathrule https://cloud.pathrule.io/mcp

Poi completa l'accesso OAuth con il tuo account Pathrule. Remote MCP fornisce a Claude solo gli strumenti MCP: non installa hook, non scrive file locali e non ha una modalità locale. Vedi Pathrule Remote MCP.

Verifica

Apri Claude Code in una directory che hai associato. Avvia un nuovo turno. La sezione Pathrule dovrebbe comparire nel contesto prima della prima chiamata a uno strumento, con il percorso risolto, le regole corrispondenti, il testo delle memorie più pertinenti ed eventuali candidati meno certi elencati per titolo.

Se non compare nulla, esegui:

pathrule doctor

Il doctor è in sola lettura. Riporta il tuo accesso, il workspace e se questa cartella è associata, se la voce MCP di Pathrule è installata per Claude Code e per ciascun altro client, e quali file gestiti da Pathrule si trovano nella cartella e chi li ha scritti. Aggiungi --json per il report completo, che segnala anche una voce MCP che punta a un runtime non più esistente. Per rimettere tutto a posto, esegui:

pathrule repair

Repair riscrive una voce MCP obsoleta, reinstalla lo script e la registrazione dell'hook, risincronizza CLAUDE.md e le tue skill ed esegue di nuovo il doctor.

Quando Claude scrive contenuti

Claude può scrivere memorie, regole e skill in Pathrule usando gli strumenti di scrittura MCP. Il runtime etichetta la fonte come claude, così i contenuti scritti da un'IA restano distinguibili da quelli scritti da una persona.

Usa lo strumento pathrule_log_activity per rendere visibile nel log delle attività ogni risposta che modifica file. È il ponte tra ciò che ha fatto Claude e ciò che vede il tuo team.

Cosa leggere dopo

• Come funzionano gli hook per il modello alla base del livello push.
• Panoramica di MCP per il livello pull.
• Riferimento degli strumenti MCP per tutti gli strumenti che Claude può chiamare.