Claude Code: dove salva memoria e configurazione, come spostarla, resettarla o eliminarla

Dove salva la memoria delle conversazioni Claude Code? Dove “vive” nel mio sistema?

Claude Code persiste su filesystem in due aree distinte della home directory, governate da una gerarchia di settings a cinque livelli e da un sistema di memoria che combina file scritti manualmente, regole condizionali e note che Claude stesso genera in autonomia. Senza una mappa precisa di cosa va dove, alcune operazioni banali diventano impraticabili: rinominare la cartella di un progetto fa perdere la history /resume, sincronizzare la home su Dropbox corrompe le credenziali OAuth, audit GDPR diventano impossibili e la CLI inizia a impiegare secondi solo per partire.

Questa guida documenta esattamente dove Claude Code scrive, cosa scrive, quando lo cancella e quali sono le strade ufficiali per spostare la memoria su un altro disco, sincronizzarla tra macchine, resettarla in modo selettivo o cancellarla del tutto. I path, le opzioni di setting e i numeri di versione sono verificati sulla documentazione ufficiale aggiornata a maggio 2026 e integrati con osservazioni empiriche su installazioni Windows 11, macOS e WSL2.

---

1. Architettura del filesystem: la mappa completa

Tutto lo stato persistente di Claude Code vive sotto la home dell’utente, distribuito su due elementi distinti che vengono spesso confusi:

• ~/.claude/ — una cartella che contiene settings utente, history delle conversazioni, auto-memory, plugin, credenziali e cache varie
• ~/.claude.json — un file JSON posizionato accanto alla cartella (non al suo interno), che custodisce il grosso della configurazione utente, la lista dei progetti, e la registrazione di tutti gli MCP server installati in scope user o local

I due elementi sono complementari e nessuno dei due è “il punto di verità” da solo. La cartella ~/.claude/ ospita i dati che cambiano spesso (conversazioni, cache, snapshot di shell). Il file ~/.claude.json ospita configurazione strutturata che cambia raramente ma cresce in modo monotono: ogni nuovo progetto aperto e ogni MCP server aggiunto appendono righe e, su installazioni di qualche mese, il file raggiunge facilmente decine di KB. In un’installazione di esempio Windows osservata per questa guida, ~/.claude.json pesava 55 KB su 1.411 righe dopo circa sei mesi di utilizzo professionale.

1.1 I due punti di ingresso: ~/.claude/ (cartella) vs ~/.claude.json (file)

La distinzione critica è che settings.json non sta dentro ~/.claude.json. Sono due file completamente diversi:

Elemento	Tipo	Cosa contiene
~/.claude/settings.json	File dentro la cartella .claude/	Preferenze utente versionabili: model, permissions, env, hooks, feature toggle
~/.claude/settings.local.json	File dentro la cartella .claude/	Override locale gitignored: tipicamente accumula allow/deny lists generate cliccando “Yes” sulle conferme di permesso
~/.claude.json	File alla radice della home	Configurazione interna runtime: lista progetti, MCP server in scope user/local, stato CLI, history /resume

Confondere ~/.claude.json con ~/.claude/settings.json è l’errore più frequente nella documentazione di terze parti. I due file hanno scope, formato e ciclo di vita opposti: settings.json è pensato per essere letto, modificato manualmente, committato (ad eccezione del .local.json); ~/.claude.json è uno store runtime gestito dal binario, che la documentazione invita esplicitamente a non modificare a mano.

1.2 Path canonici per OS

Path	macOS	Linux / WSL2	Windows
Cartella utente	~/.claude/	~/.claude/	%USERPROFILE%\.claude\
Configurazione runtime	~/.claude.json	~/.claude.json	%USERPROFILE%\.claude.json
Managed policy CLAUDE.md	/Library/Application Support/ClaudeCode/CLAUDE.md	/etc/claude-code/CLAUDE.md	C:\Program Files\ClaudeCode\CLAUDE.md
Managed settings	/Library/Application Support/ClaudeCode/managed-settings.json	/etc/claude-code/managed-settings.json	C:\Program Files\ClaudeCode\managed-settings.json
Windows policy (Registry)	n/a	n/a	HKLM\SOFTWARE\Policies\ClaudeCode o HKCU\SOFTWARE\Policies\ClaudeCode

Su Windows il path legacy C:\ProgramData\ClaudeCode\managed-settings.json è stato dismesso a partire dalla versione 2.1.75: se trovate documentazione che lo cita, è obsoleta. Su WSL2 Claude Code legge dalla home Linux, non da quella Windows: spostando il setup tra i due ambienti la configurazione non viene condivisa automaticamente.

1.3 Override del path di default: CLAUDE_CONFIG_DIR

L’unico meccanismo ufficialmente supportato per cambiare l’intera posizione della configurazione è la variabile d’ambiente CLAUDE_CONFIG_DIR. Impostandola, Claude Code usa quel path al posto di ~/.claude/ e, di conseguenza, anche ~/.claude.json viene cercato relativamente a quella directory.

# Esempio Linux/macOS — sposta tutto sotto /opt/claude-config
export CLAUDE_CONFIG_DIR="/opt/claude-config"
claude

# Equivalente Windows — sposta sotto D:\claude-config
$env:CLAUDE_CONFIG_DIR = "D:\claude-config"
claude

Il riferimento nel CHANGELOG ufficiale appare con continuità dalle versioni 2.1.120 e 2.1.136 (correzioni che assicurano coerente uso della variabile in lock file IDE e in /setup-vertex//setup-bedrock), il che indica che è una feature stabilizzata e supportata in tutti i flussi interni della CLI.

Questa è la strada principale quando si vuole spostare tutta la configurazione (compresa la auto-memory, le credenziali, gli MCP server). Per spostare soltanto la auto-memory generata da Claude esiste un secondo meccanismo dedicato (autoMemoryDirectory) che vedremo nella sezione §5: i due strumenti rispondono a esigenze diverse e non si annullano a vicenda.

---

2. Inventory di ~/.claude/: cosa contiene ogni file e cartella

Su un’installazione attiva, la cartella ~/.claude/ ospita una ventina tra file e sottocartelle. La documentazione ufficiale ne copre solo una parte; altre cartelle compaiono via via che la CLI introduce nuove feature, e non sempre vengono documentate immediatamente. Questa sezione mappa l’intero contenuto osservato su Claude Code 2.1.152, indicando per ciascuna voce funzione, sensibilità (cosa contiene di privato) e portabilità (se vale la pena copiarla su una nuova macchina).

2.1 settings.json e settings.local.json: la gerarchia a 5 livelli

settings.json e settings.local.json sono i due file dove vivono le preferenze utente e le permission liste. Il sistema di configurazione di Claude Code applica le impostazioni seguendo una gerarchia a 5 livelli dalla precedenza più alta alla più bassa:

1. Managed policy — managed-settings.json deployato a livello sistema da MDM / Group Policy. Non può essere sovrascritto da nessuno degli strati sottostanti
2. Command line arguments — flag passati direttamente a claude (es. --model, --add-dir): override temporanei valgono solo per la sessione corrente
3. Local settings — .claude/settings.local.json nel progetto, tipicamente gitignored
4. Project settings — .claude/settings.json nel progetto, versionato
5. User settings — ~/.claude/settings.json, valgono per tutti i progetti dell’utente

Per la maggior parte dei setting (model, env, hooks…) si applica la regola classica del primo livello che definisce il valore vince. Le permission rules invece non sovrascrivono: si fondono. Se la project settings mette Bash(npm test) in allow e la user settings mette Bash(curl *) in deny, vengono applicate entrambe.

Un dato sorprendente che emerge testando installazioni reali: nella stragrande maggioranza dei casi ~/.claude/settings.json resta piccolissimo (a volte una decina di byte), mentre settings.local.json di progetto accumula nel tempo decine di permission rule. Esempio reale tratto da un setup professionale dopo qualche settimana di utilizzo:

{
  "permissions": {
    "allow": [
      "Bash(ping:*)",
      "Bash(ipconfig:*)",
      "Bash(curl:*)",
      "Bash(powershell:*)",
      "Bash(tailscale status:*)",
      "Bash(net view:*)"
    ]
  }
}

Ogni volta che si conferma un comando con “Yes, and don’t ask again”, quella regola finisce qui. Questo file diventa quindi sia un audit log implicito di cosa si è autorizzato Claude a fare, sia (col tempo) una fonte di rumore se si vogliono revocare permessi: ne riparleremo in §6.4 con la strategia di reset.

2.2 projects/: anatomia dei JSONL e l’encoding dei path

La cartella ~/.claude/projects/ è dove Claude Code archivia ogni singola conversazione. È anche, di gran lunga, la cartella più pesante della directory: nell’installazione osservata pesava 121,7 MB contro 33 MB della seconda cartella più grande.

La struttura interna funziona così: ogni progetto su cui si è lavorato genera una sottocartella il cui nome è una versione “encoded” del path del progetto. L’algoritmo di encoding non è documentato ufficialmente: quanto segue è il pattern dedotto dall’osservazione su installazioni reali.

• ogni carattere \ (o / su Unix) diventa -
• ogni : diventa -
• ogni _ diventa -
• la concatenazione di drive letter + colon su Windows produce il caratteristico doppio trattino iniziale

Esempi reali osservati su un setup Windows:

Path originale	Cartella encoded
D:\python\script\wordpress_api	d--python-script-wordpress-api
C:\Users\giova	C--Users-giova
D:\python\script\schema-org-mcp	d--python-script-schema-org-mcp

Dentro ogni cartella encoded ci sono uno o più file .jsonl, ciascuno con un UUID come nome (es. c2368ebe-023a-4d80-a0f1-bff9f9db8063.jsonl) e con dimensioni che variano da poche centinaia di KB a oltre 1.8 MB per sessioni lunghe. Ogni riga è un evento della conversazione (messaggio utente, risposta assistant, tool call, risultato) serializzato in JSON. Conoscere questo schema permette di estrarre analytics dalle conversazioni passate, cosa che vedremo in §11.

Il dato cruciale è che il path encoded è la chiave su cui Claude Code cerca le sessioni quando si lancia /resume o claude --continue. Se si rinomina la cartella del progetto, la cartella encoded resta indietro col vecchio nome e Claude non trova più la history. Il fix è semplice: rinominare manualmente la cartella encoded per matchare il nuovo path. Tornerà utile in §10.1.

2.3 Sottocartelle minori: todos/, shell-snapshots/, statsig/, ide/, debug/, session-env/, tasks/, paste-cache/

Queste sottocartelle vivono di vita propria. Sono prevalentemente working storage che Claude Code popola al volo e ripulisce periodicamente:

• todos/ — stato delle todo list create con il tool TodoWrite. Cancellabili senza side effect: al massimo si perde l’elenco delle todo della sessione in corso
• shell-snapshots/ — snapshot dello stato della shell prima dell’esecuzione di comandi, utile per debug. Coperti dalla retention cleanupPeriodDays a partire dalla v2.1.117
• statsig/ — feature flag e telemetria locale del client Statsig. Vedremo le implicazioni in §8.1
• ide/ — file di integrazione con IDE (VS Code, JetBrains). Lock file di shell integration
• debug/ — log di debug della CLI
• session-env/ — variabili d’ambiente specifiche di sessione (snapshot di env al lancio). Non è coperto da cleanupPeriodDays: il CHANGELOG v2.1.117 cita solo tasks/, shell-snapshots/ e backups/
• tasks/ — stato dei task in background, soggetto a sweep cleanupPeriodDays
• paste-cache/ — cache dei testi incollati nel terminale (quelli che appaiono come [Pasted text #1 +23 lines])

Nessuna di queste cartelle contiene configurazione che si vuole portare con sé spostando l’installazione. Sono tutte localmente derivate e ricostruibili.

2.4 history.jsonl e l’indice di /resume

history.jsonl è un file alla root di ~/.claude/ che funge da indice cronologico globale di tutte le query dell’utente. Ogni riga è una singola interazione, in un formato compatto:

{"display":"sono connesso alla rete di casa via tailscale...","pastedContents":{},"timestamp":1773063568981,"project":"C:\\Users\\giova","sessionId":"5183d66d-b03d-4e16-b2fe-562dac4e6230"}

Lo schema non è documentato ufficialmente. Sulle installazioni osservate tre campi sono chiave:

• timestamp (epoch millisecondi)
• project — path letterale, non encoded: contiene C:\\Users\\giova non C--Users-giova. Questa asimmetria con la cartella projects/ permette di leggere history.jsonl con un parser semplice senza dover decodificare nulla
• sessionId — UUID che fa da chiave su projects/<encoded>/<sessionId>.jsonl

Quando claude --continue o /resume cercano sessioni, leggono history.jsonl per trovare quelle del progetto corrente, e poi risolvono ogni sessionId contro la cartella encoded. Se history.jsonl viene cancellato, --continue smette di funzionare ma le conversazioni restano fisicamente in projects/ e sono ancora aperture manualmente. Questo è importante per capire il meccanismo di reset selettivo che vedremo in §6.2.

2.5 commands/, agents/, skills/, rules/, hooks/, plugins/: il sistema di estensione

Queste cartelle sono il punto di entrata per estendere il comportamento di Claude Code:

• commands/ — slash command custom: file Markdown il cui nome è il comando (mio-comando.md → /mio-comando)
• agents/ — definizioni di subagenti custom (vedi anche ~/.claude/agents/)
• skills/ — skill personalizzati (sistema agent-installable): caricati on-demand quando il prompt li richiede
• rules/ — regole markdown caricate al lancio o solo per file matching (paths: frontmatter)
• hooks/ — script che vengono lanciati su eventi del ciclo di vita (PreToolUse, PostToolUse, ecc.)
• plugins/ — sistema di plugin distribuiti via marketplace (pesa qualche MB su installazioni con plugin attivi)

Questi sono i file che conviene davvero portarsi dietro quando si migra Claude Code su un’altra macchina: rappresentano il lavoro di personalizzazione vero e proprio. Sono anche gli unici candidati naturali al versionamento in git (in una repo personale), perché sono testo, deterministici e privi di credenziali.

2.6 .credentials.json: credenziali e modello di sicurezza per OS

.credentials.json alla root di ~/.claude/ è dove finiscono i token di autenticazione (Claude.ai login, MCP OAuth tokens su Linux/Windows). Sulla macchina osservata pesava 543 byte: il file è piccolo e contiene solo token, non chiavi private. Il modello di sicurezza dipende dall’OS:

OS	Storage credenziali	Protezione
macOS	Keychain (sistema operativo)	Cifratura a livello OS, accesso protetto da credenziali utente
Linux	~/.claude/.credentials.json	File mode 0600 (solo owner read/write)
Windows	%USERPROFILE%\.claude\.credentials.json	ACL utente standard

Su macOS i client secret OAuth degli MCP server sono cifrati nel Keychain di sistema. Su Linux e Windows il file .credentials.json deve restare con permessi restrittivi: una sync verso Dropbox o iCloud lo esporrebbe in chiaro al servizio cloud. Approfondiamo lo scenario di sync e le sue implicazioni in §5.4 e §8.2.

2.7 Cartelle non documentate: telemetry/, file-history/, cache/, backups/

Esplorando un’installazione reale emergono cartelle e file che la documentazione ufficiale Anthropic non descrive. Quanto segue è comportamento osservato, non specifica: nomi, contenuti e regole di cleanup possono cambiare tra versioni.

• telemetry/ — pesa quanto basta per saltare all’occhio (33 MB nell’installazione osservata) e contiene metriche OpenTelemetry serializzate localmente. Disabilitabile via CLAUDE_CODE_ENABLE_TELEMETRY=0. Approfondimento in §8.1
• file-history/ — cronologia delle modifiche ai file fatte da Claude Code; usata dal sistema di undo/diff incrementale. ~5 MB osservati
• cache/ — cache generiche del client
• backups/ — copie di sicurezza di file modificati prima di operazioni potenzialmente distruttive. Soggette a cleanupPeriodDays
• paste-cache/, sessions/ (vs projects/), stats-cache.json, mcp-needs-auth-cache.json — cache e stato runtime, ricostruibili
• .last-cleanup — timestamp dell’ultima esecuzione del cleanup periodico

Sono tutte locali, ricostruibili, e nessuna va inclusa in backup né in sync cloud. Le tratteremo come “ephemeral storage” nella matrice di portabilità in §5.3.

---

3. Il file ~/.claude.json: configurazione utente e MCP

~/.claude.json è il file alla radice della home che custodisce gran parte dello stato strutturato della CLI: lista dei progetti aperti, configurazione MCP in scope user e local, flag interni, contatori. Cresce monotonamente con l’uso e raramente cala di volume. Su installazioni mature è normale vederlo a decine di KB su migliaia di righe. Per chi parte da zero su MCP, l’architettura dei server MCP spiega il protocollo e il modello client-server alla base di questi blocchi di configurazione.

3.1 Struttura interna del file

Il file è un singolo oggetto JSON. La doc ufficiale ne descrive il contenuto a livello generale (OAuth session, MCP server configurations, per-project state, cache); le chiavi sotto sono osservate su installazioni reali, non parte della specifica pubblica:

• projects — oggetto indicizzato per path letterale del progetto (es. "D:\\python\\script\\wordpress_api": { ... }). Ogni entry contiene gli MCP server installati in scope local, l’history dei prompt usati, flag di approvazione di .mcp.json
• mcpServers — oggetto con gli MCP server installati in scope user
• numStartups, firstStartTime, userID — telemetria locale per il client
• customApiKeyResponses, oauthAccount — riferimenti a metodo di autenticazione corrente

Il file viene riscritto dalla CLI al volo: modifiche manuali sono possibili ma rischiose, perché un edit concorrente con un’altra istanza della CLI può causare perdita di stato. La via supportata per modificarlo è claude mcp add/remove e i comandi correlati.

3.2 Gerarchia MCP server: local > project > user > plugins > claude.ai

Quando lo stesso MCP server è definito in più scope, Claude Code connette una sola volta seguendo questa precedenza:

1. Local — registrato in ~/.claude.json sotto projects.<path>.mcpServers, valido solo nel progetto corrente
2. Project — definito in .mcp.json alla root del progetto, versionato, condiviso col team
3. User — ~/.claude.json sotto mcpServers root, vale per tutti i progetti
4. Plugin-provided — server bundlati nei plugin installati
5. claude.ai connectors — server importati dall’account Claude.ai

I duplicati nei primi tre scope si matchano per nome. Plugin e connector si matchano per endpoint (URL o comando). Solo l’entry dello scope più alto viene usata: i fields non si fondono. Per vedere come questa gerarchia si traduce in configurazione reale, ho documentato installazione e debug di due server in una guida pratica ai server MCP con Claude Code.

3.3 .mcp.json di progetto vs MCP user-scope

.mcp.json alla root del progetto è il file pensato per condividere MCP server col team via git. Supporta espansione di variabili d’ambiente con sintassi ${VAR} o ${VAR:-default}, utile per gestire path machine-specific senza committare valori sensibili. Quando un utente apre per la prima volta un progetto con .mcp.json, Claude Code chiede approvazione esplicita per usare quei server.

Gli MCP server in scope user vivono dentro ~/.claude.json e non si vedono nel filesystem di progetto. Per migrare gli MCP user-scope su un’altra macchina, l’unico modo affidabile è copiare ~/.claude.json (o usare claude mcp add daccapo).

3.4 Bloat del file e degradazione delle performance

Sul filesystem osservato per questa guida, ~/.claude.json pesava 55 KB su 1.411 righe dopo circa sei mesi di utilizzo professionale. Il file è ancora gestibile, ma la lettura parsing che avviene a ogni avvio della CLI inizia a essere percepibile su SSD lenti o filesystem di rete.

Cosa lo fa crescere:

• Ogni nuovo progetto aperto aggiunge una entry sotto projects
• Prompt history per progetto viene memorizzata qui (non solo in history.jsonl)
• MCP server registrati non vengono mai compattati
• Approval flag per .mcp.json di ogni progetto

Su installazioni mature il file può raggiungere decine di MB e rendere claude --version percepibilmente lento. La diagnosi e la pulizia sicura del file le copriamo nel troubleshooting §10.2.

---

4. Sistema di memoria: CLAUDE.md, rules, auto-memory e import

Claude Code ha due meccanismi complementari per dare istruzioni persistenti: i file CLAUDE.md scritti dall’utente e l’auto-memory scritta dall’assistente. Entrambi vengono caricati a ogni nuova sessione, ma li si gestisce in modo diverso e servono scopi diversi. La documentazione ufficiale è esplicita sul punto: né l’uno né l’altro è configurazione “enforced”, sono entrambi context. Per bloccare un’azione a prescindere da quello che Claude decide di fare, lo strumento corretto è un hook PreToolUse, non una riga in CLAUDE.md. Il motivo per cui serve un sistema di memoria persistente sta nei limiti del context window degli LLM: senza un canale esterno, ogni sessione ripartirebbe da zero.

4.1 I quattro scope di CLAUDE.md

I file CLAUDE.md si possono mettere in quattro posti, in ordine dal più ampio al più specifico (e quindi dal primo a essere letto al più recente a essere appeso al context):

Scope	Path	Per cosa
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS) / /etc/claude-code/CLAUDE.md (Linux/WSL) / C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	Istruzioni org-wide deployate da IT/DevOps. Non escludibili
User	~/.claude/CLAUDE.md	Preferenze personali su tutti i progetti
Project	./CLAUDE.md o ./.claude/CLAUDE.md	Standard team condivisi via git
Local	./CLAUDE.local.md	Preferenze personali sul singolo progetto, gitignored

Tutti i CLAUDE.md trovati nella catena di cartelle genitrici della working directory vengono concatenati al lancio. Nelle sottocartelle del progetto, invece, eventuali CLAUDE.md nidificati vengono caricati on-demand solo quando Claude legge file in quella sottocartella.

In monorepo o setup dove non si vogliono caricare tutti i CLAUDE.md dei sub-progetti, il setting claudeMdExcludes in settings.json accetta una lista di glob: i file matchati non vengono appesi al context (documentato in code.claude.com/docs/en/memory e /en/settings).

4.2 .claude/rules/ e path-scoped rules

Per progetti grandi, anziché far crescere CLAUDE.md oltre i 200 righe (limite oltre il quale l’aderenza cala visibilmente), conviene spezzare le istruzioni in più file dentro .claude/rules/. Ogni file .md può avere un frontmatter YAML con campo paths: che lo carica solo quando Claude lavora su file matching:

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.test.ts"
---

# API rules
- Tutti gli endpoint devono validare input con zod
- Errori usano il formato standard `{ code, message, details }`

I file senza frontmatter paths: vengono caricati sempre, con la stessa priorità di .claude/CLAUDE.md. Le rules user-level in ~/.claude/rules/ valgono per tutti i progetti.

4.3 La sintassi @import e i suoi limiti

Dentro qualsiasi CLAUDE.md si possono importare altri file con la sintassi @path/to/file.md. Path relativi e assoluti sono entrambi supportati, e gli import sono ricorsivi fino a una profondità massima di 4 hop — non 5 come a volte riportato da fonti di terze parti. I commenti HTML a livello di blocco (<!-- nota -->) vengono strippati prima dell’iniezione nel context, utili per appunti maintainer-only che non consumano token.

See @README.md for project overview.

# Workflow
- Branching: @docs/git-workflow.md
- Testing: @docs/testing.md

Limitazione importante: gli @import dentro blocchi di codice vengono ignorati (non vengono espansi). Funziona solo nel corpo Markdown normale.

4.4 Auto-memory: cosa Claude salva da solo

Auto-memory (introdotta in v2.1.59 e attiva di default) è il sistema con cui Claude annota autonomamente fatti rilevanti emersi dalla conversazione: preferenze esplicite dell’utente, regole correttive ricevute, contesto di progetto non desumibile dal codice. I file vengono salvati in ~/.claude/projects/<encoded_path>/memory/, con MEMORY.md come indice ed eventuali file tematici (feedback_x.md, project_y.md) separati.

Comportamento osservato e documentato:

• Solo i primi 200 righe o 25 KB di MEMORY.md vengono caricati al lancio di ogni sessione
• I file tematici sono letti on-demand, non caricati al boot
• Tutti i worktree dello stesso git repo condividono la stessa cartella memory
• Si può disattivare con autoMemoryEnabled: false in settings o con CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Quando si chiede a Claude qualcosa come “ricordati che uso sempre pnpm”, quella riga finisce nella auto-memory; non in CLAUDE.md. Per le cose che invece vanno tenute in CLAUDE.md, va detto esplicitamente.

I subagent (vedi code.claude.com/docs/en/sub-agents#enable-persistent-memory) hanno un sistema di memoria persistente separato dal main agent: le istruzioni stratificate nella conversazione principale non si propagano automaticamente al subagent, va dichiarato e abilitato in modo esplicito nella definizione del subagent stesso.

4.5 Differenza tra memoria, conversazione, todos e history

Quattro concetti vengono spesso confusi, ma sono cose diverse, salvate in punti diversi:

Concetto	Cosa è	Dove vive	Persistenza
CLAUDE.md	Istruzioni scritte da te	Dove l’hai messo (vedi §4.1)	Permanente, file-based
Auto-memory	Note che scrive Claude	~/.claude/projects/<enc>/memory/	Permanente fino a delete manuale
/memory	Slash command che apre l’editor sui file di memoria	Comando, non un file	n/a
Conversazione	Trascritto completo della sessione	~/.claude/projects/<enc>/<uuid>.jsonl	Soggetto a cleanupPeriodDays
Todos	Lista task della sessione corrente	~/.claude/todos/	Per sessione, ricostruibile
history.jsonl	Indice cronologico dei prompt	~/.claude/history.jsonl	Permanente fino a delete manuale

4.6 Cosa sopravvive a /compact

/compact riassume la conversazione corrente per liberare context. Non tutto sopravvive:

• ✅ CLAUDE.md del project root viene re-iniettato automaticamente
• ❌ CLAUDE.md nidificati in sottocartelle non vengono re-iniettati: ricaricano alla prossima lettura di un file in quella sottocartella
• ✅ Auto-memory MEMORY.md (entro il limite 200 righe / 25 KB)
• ❌ Istruzioni date solo a voce in conversazione

Se un’istruzione importante è data solo a voce e poi si fa /compact, quell’istruzione è persa. La soluzione corretta è scriverla in CLAUDE.md (o chiedere a Claude di salvarla in auto-memory).

---

5. Spostare la memoria: due strade ufficiali più symlink

Spostare lo storage di Claude Code è un’esigenza ricorrente: nuovo disco SSD, sync work-personal, profili multipli sulla stessa macchina, backup su cloud personale. Esistono due meccanismi ufficiali distinti e una terza via — i symbolic link — che è non documentata ma funziona se applicata con criterio.

CLAUDE_CONFIG_DIR è la via sicura per spostare l’intera config su un altro path locale o un volume esterno. La sync via cloud commerciale richiede invece di scegliere a mano cosa includere: i pochi file statici sì, tutto il resto no per evitare conflict e per non esporre credenziali in chiaro su Linux/Windows.

File / Cartella	Sync cloud (Dropbox/iCloud/OneDrive)	CLAUDE_CONFIG_DIR
CLAUDE.md user/project	✅ Sì	✅ Sì
commands/, agents/, skills/, rules/, hooks/	✅ Sì	✅ Sì
settings.json	✅ Sì	✅ Sì
settings.local.json	⚠️ Con cautela	✅ Sì
projects/<x>/memory/	⚠️ Con cautela (con autoMemoryDirectory)	✅ Sì
projects/<x>/*.jsonl	❌ No	✅ Sì
.credentials.json	❌ MAI	✅ Sì
~/.claude.json	❌ No	✅ Sì (incluso)
history.jsonl	❌ No	✅ Sì
statsig/, telemetry/, cache/	❌ No	⚠️ Con cautela (Locale comunque)
shell-snapshots/, debug/, session-env/, paste-cache/	❌ No	⚠️ Con cautela (Locale)
todos/, tasks/, sessions/	❌ No	⚠️ Con cautela (Locale)

5.1 Spostare solo l’auto-memory: il setting autoMemoryDirectory

Per spostare la auto-memory generata da Claude in un’altra cartella, la via supportata è il setting autoMemoryDirectory in ~/.claude/settings.json:

{
  "autoMemoryDirectory": "~/dropbox/claude-memory"
}

Il valore deve essere un path assoluto o iniziare con ~/. Il setting è accettato solo a livello user o policy (non project né local), per una ragione di sicurezza: una repo clonata potrebbe altrimenti fornire un .claude/settings.local.json malevolo che redirige la auto-memory verso una cartella sensibile.

Questa opzione è la più chirurgica quando si vuole sincronizzare solo le note autogenerate (non le credenziali, non le conversazioni complete) tra macchine. Funziona bene con Dropbox / iCloud / OneDrive purché ci sia una sola macchina che scrive alla volta — più istanze attive in scrittura concorrente sullo stesso path rischiano conflitti.

5.2 Spostare l’intera config: CLAUDE_CONFIG_DIR

Per spostare tutto il setup — settings, credenziali, MCP server, history, memoria, plugin — la variabile CLAUDE_CONFIG_DIR è la via giusta. Impostata, Claude Code la rispetta per tutti gli accessi a ~/.claude/ e ~/.claude.json. Il riferimento appare nel CHANGELOG come correzione ricorrente (v2.1.111, v2.1.136), segno che è effettivamente usata dappertutto nel codice della CLI.

# .bashrc / .zshrc
export CLAUDE_CONFIG_DIR="/Volumes/External/claude-config"

# PowerShell profile
$env:CLAUDE_CONFIG_DIR = "E:\claude-config"

Importante: CLAUDE_CONFIG_DIR riposiziona la cartella di config; la doc ufficiale non specifica formalmente come venga risolto il path equivalente di ~/.claude.json. La prima volta che si parte con il nuovo path, Claude Code crea le strutture vuote — quindi va fatto un primo copy manuale dei contenuti dalla vecchia posizione.

5.3 Symlink su Dropbox / iCloud / OneDrive: cosa sì e cosa no

L’approccio “metto tutto ~/.claude/ su Dropbox con un symlink” è seducente ma rischioso. Funziona solo se si selezionano con cura i file: la sync di Dropbox fa lock e versionamento, e su file scritti molto spesso si generano duplicati con suffissi tipo settings (conflicted copy 2026-05-27).json.

Matrice di portabilità — cosa va su cloud e cosa no:

Path	Sync cloud?	Motivo
~/.claude/CLAUDE.md	✅ Sì	Statico, raro update, alto valore
~/.claude/commands/, skills/, agents/, rules/, hooks/	✅ Sì	Custom, raro update
~/.claude/settings.json	✅ Sì	Statico
~/.claude/projects/<x>/memory/	⚠️ Solo se la macchina è una	Auto-memory cambia spesso; autoMemoryDirectory è più sicuro
~/.claude/projects/<x>/*.jsonl	❌ No	File grandi, scritti continuamente, alto rischio conflict
~/.claude/.credentials.json	❌ MAI	Token in chiaro su Linux/Windows
~/.claude.json	❌ No	Riscritto a ogni operazione, conflict garantito
~/.claude/{statsig, telemetry, shell-snapshots, cache, file-history, paste-cache, debug, session-env, todos, tasks, ide, sessions, backups}/	❌ No	Ephemeral, ricostruibile
~/.claude/history.jsonl	❌ No	Aggiornato a ogni prompt

Il pattern raccomandato: lasciare ~/.claude/ sulla home locale e fare symlink mirati solo verso le tre/quattro cartelle che hanno valore (commands/, skills/, agents/, rules/, CLAUDE.md) puntando a un repo git o a Dropbox.

5.4 Multi-profilo work / personal sulla stessa macchina

Su una macchina condivisa work/personal, la combinazione CLAUDE_CONFIG_DIR + alias shell permette di avere setup completamente separati:

# ~/.zshrc
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'
alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'

Ogni alias parte con i propri MCP server, le proprie credenziali OAuth, la propria auto-memory. Utile per separare progetti cliente che usano DataForSEO da quelli che usano Stripe, per esempio: niente cross-contamination tra MCP server e niente token misti tra account Claude.ai diversi.

---

6. Reset della memoria: dal soft al hard

“Reset” è una parola che copre quattro azioni molto diverse. Confondere il livello sbagliato significa perdere lavoro o, all’opposto, restare con stati zombie che pensavamo di aver cancellato.

Per un reset chirurgico su singolo progetto, dalla v2.1.126 è disponibile il comando ufficiale claude project purge <path> (con flag --dry-run, -y/--yes, -i/--interactive, --all): pulisce in un colpo transcripts, tasks, file history e l’entry di configurazione del progetto. Va preferito al fix manuale di cancellazione cartelle quando lo scope è un singolo progetto. Per gli altri scenari valgono i livelli sotto.

6.1 /clear, /compact: cosa fanno davvero

• /clear azzera la conversazione corrente. Lascia intatti CLAUDE.md, auto-memory, todos, history. Equivale a chiudere la sessione e aprirne una nuova
• /compact riassume la conversazione corrente per recuperare context. Non cancella nulla su disco; può però far “sparire” istruzioni date a voce, come visto in §4.6

Nessuno dei due tocca lo storage persistente. Sono operazioni intra-sessione.

6.2 Cancellare history senza perdere conversazioni

Lo scenario tipico: la lista /resume è inquinata da sessioni di test, voglio “ripartire pulito” senza perdere i JSONL.

history.jsonl è l’indice usato da /resume e --continue. Cancellarlo (o accorciarlo a mano) ripulisce la lista. I file di conversazione restano in ~/.claude/projects/<encoded>/<uuid>.jsonl e sono ancora leggibili manualmente: cambia solo che Claude non li propone più nel selector di resume.

# Cancella l'indice: la history è "rimossa" dalla UI ma i file restano
rm ~/.claude/history.jsonl

Remove-Item "$env:USERPROFILE\.claude\history.jsonl"

6.3 Reset della auto-memory

Auto-memory è in ~/.claude/projects/<encoded>/memory/. Per resettarla, basta eliminare il contenuto della cartella:

rm -rf ~/.claude/projects/d--python-script-wordpress-api/memory/

Alla prossima sessione Claude Code la ricostruisce da zero. Per disattivare permanentemente l’auto-memory:

{
  "autoMemoryEnabled": false
}

Oppure via env: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Per resettare solo un file tematico (es. dimenticare un feedback specifico), si cancella il singolo .md lasciando MEMORY.md: alla session successiva Claude rilegge l’indice e aggiorna i riferimenti.

6.4 Reset di allow/deny lists in settings.local.json

Quando l’allow list di settings.local.json (di progetto) cresce a decine di righe perché si è cliccato “Yes and don’t ask again” troppo spesso, l’approccio più pulito è riazzerare il file:

{
  "permissions": {
    "allow": []
  }
}

Per le approvazioni di .mcp.json di progetto, c’è anche un comando dedicato:

claude mcp reset-project-choices

Rimuove tutte le approvazioni MCP per il progetto corrente; alla prossima sessione Claude richiederà di approvare di nuovo.

6.5 Reset MCP server e token OAuth

Per rimuovere un MCP server in scope local o user:

claude mcp remove <name>

Per revocare il token OAuth di un server, dentro Claude Code si usa il menu /mcp → “Clear authentication” sulla riga del server. Su macOS questo cancella l’entry dal Keychain; su Linux/Windows rimuove dal file credenziali. Forzare il logout completo da Claude.ai si fa con /login, che invalida e ripropone il flow.

---

7. Cancellare tutto: disinstallazione completa di Claude Code

Lo scenario qui è radicale: voglio rimuovere Claude Code dalla macchina come se non fosse mai stato installato. La disinstallazione npm da sola lascia indietro abbastanza materiale da far ricomparire profili e history al reinstallo. La checklist completa è in tre fasi.

7.1 Disinstallazione del binario

npm uninstall -g @anthropic-ai/claude-code

Questo rimuove il binario e gli npm assets, ma non tocca ~/.claude/ né ~/.claude.json né le credenziali in Keychain.

7.2 Pulizia dei file di stato

# Linux/macOS
rm -rf ~/.claude/ ~/.claude.json

# Se si usa CLAUDE_CONFIG_DIR, cancellare anche quella
rm -rf "$CLAUDE_CONFIG_DIR"

# Windows
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\"
Remove-Item -Force "$env:USERPROFILE\.claude.json"

A questo punto il filesystem è pulito. Restano però i token OAuth nei keychain di sistema.

7.3 Pulizia credenziali nel Keychain (macOS) e equivalenti

Su macOS i token OAuth di Claude.ai e degli MCP server sono nel Keychain di sistema. Per rimuoverli, aprire Keychain Access (Accesso Portachiavi) e cercare “Claude Code” o “anthropic” — eliminare le entry che corrispondono. In alternativa via CLI:

security delete-generic-password -s "Claude Code"

Su Linux e Windows i token erano nel file .credentials.json che è già stato cancellato al punto 7.2: niente di ulteriore.

7.4 Variabili d’ambiente residue

Alcuni utenti hanno aggiunto variabili a .bashrc, .zshrc o profilo PowerShell:

• CLAUDE_CONFIG_DIR
• ANTHROPIC_MODEL
• CLAUDE_CODE_* varie
• MCP_TIMEOUT, ENABLE_TOOL_SEARCH, MAX_MCP_OUTPUT_TOKENS

Vanno rimosse a mano. Un grep su ~/.bashrc, ~/.zshrc, ~/.profile, $PROFILE di PowerShell, e poi reload della shell, conclude l’operazione.

7.5 Verifica “Claude Code mai installato”

Per verificare che non sia rimasto niente:

# Linux/macOS
find ~ -name ".claude*" -maxdepth 2 2>/dev/null
find ~ -path "*ClaudeCode*" 2>/dev/null
which claude

# Windows
Get-ChildItem -Path "$env:USERPROFILE" -Filter ".claude*" -ErrorAction SilentlyContinue
Get-Command claude -ErrorAction SilentlyContinue

Output vuoto su entrambe le invocazioni = pulizia completa. Le installazioni di sistema (managed policy CLAUDE.md su /Library/Application Support/ClaudeCode/ o /etc/claude-code/) sopravvivono a meno di rimuoverle separatamente come root/admin: in contesti enterprise sono di competenza del team IT.

---

8. Privacy, sicurezza e audit del dato locale

Tutto quello che scrivi a Claude Code finisce — almeno temporaneamente — sul tuo filesystem. Per audit interno, compliance GDPR o semplice igiene, vale la pena conoscere esattamente cosa viene scritto, dove e per quanto.

8.1 Telemetria e statsig

~/.claude/statsig/ e ~/.claude/telemetry/ raccolgono dati di utilizzo: nell’installazione osservata telemetry/ pesava 33 MB. Il dato è anonimo a livello di evento, ma resta sul filesystem locale finché non viene esportato o cancellato.

La doc ufficiale (code.claude.com/docs/en/settings e /en/monitoring-usage) descrive l’opt-in esplicito con CLAUDE_CODE_ENABLE_TELEMETRY=1 per ambienti enterprise; non documenta formalmente l’opposto. In assenza di opt-in la cartella si può cancellare a mano: se viene ricreata e popolata, significa che la telemetria è abilitata altrove (settings org-wide, variabile in profile, OTLP exporter).

Se l’organizzazione usa un export OpenTelemetry verso un endpoint OTLP (tipico setup enterprise), il dato lascia la macchina. La variabile OTEL_METRICS_EXPORTER=otlp controlla il transport; in assenza, i dati restano locali.

8.2 Credenziali e Keychain: matrice OS

Riassumendo il modello già introdotto in §2.6:

OS	Token Claude.ai	MCP OAuth	Plugin credentials
macOS	Keychain	Keychain	Keychain (system)
Linux	~/.claude/.credentials.json (mode 0600)	stesso file	stesso file
Windows	%USERPROFILE%\.claude\.credentials.json (ACL utente)	stesso file	stesso file

Su Linux e Windows la sync verso cloud commerciale espone i token in chiaro al provider. Lo scenario di rischio non è ipotetico: un repository di servizi cloud compromesso può accedere ai token di tutti i suoi utenti. Su sistemi sensibili, mantenere ~/.claude/ fuori da qualsiasi storage non controllato.

8.3 Hooks come superficie di attacco

Gli hook in ~/.claude/hooks/ (o nel settings.json come campo hooks) sono shell command eseguiti automaticamente. Una repo clonata che porta con sé hook in .claude/settings.local.json può potenzialmente eseguire codice arbitrario alla prima sessione di Claude Code se si accettano gli approval. La regola operativa: prima di accettare .claude/settings.local.json o .mcp.json di una repo non propria, leggerli con un editor.

8.4 Conversation log: cosa contengono i JSONL

I file ~/.claude/projects/<encoded>/<uuid>.jsonl contengono il transcript completo di ogni sessione: prompt utente, tool call (con argomenti), risultati dei tool (inclusi file letti). Se durante una sessione Claude legge /etc/passwd, quel contenuto finisce nel JSONL. Lo stesso vale per snippet .env letti per debug, output di git diff che includono codice proprietario, query SQL.

Per audit GDPR su una macchina condivisa o aziendale, va trattata projects/ come dato sensibile alla pari di un dump di chat interno. cleanupPeriodDays (vedi §9.1) limita la finestra di esposizione ma non è un wipe sicuro: i file vengono semplicemente unlink, recuperabili da forensic standard.

8.5 Checklist GDPR per repository con dati sensibili

• Aggiungere */.claude/.credentials.json al .gitignore globale dell’utente (e ai backup exclude)
• Disattivare auto-memory per progetti con dati di clienti (autoMemoryEnabled: false nel CLAUDE.md di progetto)
• Considerare CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 per disabilitare il write di history.jsonl per la sessione corrente
• Impostare cleanupPeriodDays: 7 o anche 1 per progetti con dati legali sensibili
• Audit periodico di ~/.claude/statsig/ e telemetry/ se l’org ha vincoli sul dato anonimo trasmesso

---

9. Maintenance: pulizia, backup e archiviazione

Il filesystem di Claude Code è auto-igienico ma fino a un certo punto. Senza una manutenzione attiva la home cresce di centinaia di MB all’anno e qualche operazione (boot della CLI, MCP server list) inizia a essere visibilmente lenta.

9.1 Auto-deletion sessioni e cleanupPeriodDays

Di default Claude Code elimina i file di sessione più vecchi di 30 giorni allo startup. L’opzione cleanupPeriodDays in settings.json lo controlla:

{
  "cleanupPeriodDays": 14
}

Dal v2.1.117 il sweep copre anche ~/.claude/tasks/, ~/.claude/shell-snapshots/ e ~/.claude/backups/ — non solo projects/. Setting 0 viene rifiutato (validation error). Setting 1 è il minimo accettato.

9.2 Strategia backup tier-1

Cosa includere in un backup periodico (giornaliero o pre-update):

• ~/.claude/CLAUDE.md (se esiste)
• ~/.claude/commands/, agents/, skills/, rules/, hooks/
• ~/.claude/settings.json
• Una snapshot di ~/.claude.json (utile per ricostruire la lista MCP user-scope)

Frequenza consigliata: prima di ogni npm update -g @anthropic-ai/claude-code e una volta a settimana per le custom. Formato: tar/zip incrementale verso storage personale (non cloud commerciale per le credenziali).

9.3 Archiviazione long-term dei JSONL

Per chi vuole tenere uno storico delle conversazioni oltre cleanupPeriodDays:

# Archivia tutti i JSONL più vecchi di 30 giorni prima del prossimo cleanup
find ~/.claude/projects -name "*.jsonl" -mtime +25 \
  -exec tar -rf ~/claude-archive-$(date +%Y%m).tar {} \;

$cutoff = (Get-Date).AddDays(-25)
Get-ChildItem "$env:USERPROFILE\.claude\projects\" -Filter "*.jsonl" -Recurse |
  Where-Object { $_.LastWriteTime -lt $cutoff } |
  Compress-Archive -DestinationPath "$env:USERPROFILE\claude-archive-$(Get-Date -Format yyyyMM).zip" -Update

9.4 Cartelle cancellabili senza side-effect

Per recuperare rapidamente spazio su disco, queste cartelle si possono cancellare senza conseguenze: vengono ricreate al prossimo lancio:

• ~/.claude/cache/, ~/.claude/paste-cache/, ~/.claude/file-history/
• ~/.claude/shell-snapshots/, ~/.claude/debug/, ~/.claude/session-env/
• ~/.claude/statsig/, ~/.claude/telemetry/ (cresce di nuovo se non disattivata)
• ~/.claude/sessions/, ~/.claude/tasks/

Non cancellare invece: projects/ (perdita history), commands//agents//skills//rules//hooks/ (perdita personalizzazioni), .credentials.json (richiede re-login).

---

10. Troubleshooting: i casi reali

Cinque situazioni che capitano regolarmente con Claude Code, con il fix di ognuna.

10.1 “Ho rinominato la cartella e ho perso lo storico”

Sintomo: /resume o claude --continue non mostrano più le sessioni del progetto.

Causa: la cartella encoded in projects/ è ancora indicizzata col vecchio nome, ma history.jsonl cerca con il nuovo path.

Fix: rinominare la cartella encoded matchando il pattern del nuovo path (: e \// → -, _ → -):

mv ~/.claude/projects/old--encoded--name ~/.claude/projects/new--encoded--name

In alternativa, riportare la cartella di progetto al nome originale. Dalla v2.1.126 esiste anche claude project purge <path> per cancellare in un colpo tutto lo stato di un progetto (transcripts, tasks, file history, entry di config) — utile come reset pulito quando il fix di rinomina manuale non basta. Supporta --dry-run, -y, -i e --all.

10.2 Claude Code lento all’avvio: bloat di ~/.claude.json

Sintomo: claude --version impiega più di 1 secondo, claude parte lentamente.

Diagnosi:

wc -l ~/.claude.json
ls -lh ~/.claude.json

Soglia di attenzione: oltre 5.000 righe / 500 KB. Pulizia:

# Backup
cp ~/.claude.json ~/.claude.json.bak

# Elenca i path dei progetti registrati
jq -r '.projects | keys[]' ~/.claude.json

# Per ogni path che non esiste più sul disco, rimuovi la entry con
# jq 'del(.projects["<path>"])' (oppure editing manuale del JSON).
# Esempio (Linux/macOS):
jq 'del(.projects["/Users/me/old-project"])' ~/.claude.json > ~/.claude.json.new \
  && mv ~/.claude.json.new ~/.claude.json

In pratica conviene rimuovere a mano (con jq o editor) le entry sotto projects.<path> di progetti che non esistono più.

10.3 MCP server “disconnected” dopo aggiornamento

Sintomo: dopo npm update -g @anthropic-ai/claude-code, /mcp mostra server in stato failed o disconnected.

Cause comuni:

• Token OAuth scaduto: clicca “Authenticate” su quel server in /mcp
• Path del comando stdio cambiato: claude mcp get <name> per verificare il comando, claude mcp remove <name> && claude mcp add ... per riconfigurare
• MCP_TIMEOUT troppo basso per server che richiedono boot lungo: MCP_TIMEOUT=30000 claude

Sul retry MCP la documentazione distingue due livelli: il reconnect mid-session (5 tentativi con backoff esponenziale) per HTTP/SSE, sempre esistito, e il retry sulla connessione iniziale (3 tentativi) introdotto con la v2.1.121. Stdio non viene ritentato automaticamente. Se invece il problema è capire come strutturare un workflow MCP stabile da zero, ho documentato una pipeline reale con server MCP Schema.org usata in produzione per audit di dati strutturati.

10.4 --continue non trova sessioni

Verificare in sequenza:

1. cat ~/.claude/history.jsonl | grep $(pwd) — la sessione deve apparire nell’indice
2. ls ~/.claude/projects/<encoded>/ — i file JSONL devono esistere
3. Se history.jsonl è coerente ma projects/<encoded>/ è vuoto, è probabile che cleanupPeriodDays abbia fatto sweep

10.5 Sync conflict su Dropbox/iCloud

Sintomo: file con suffissi (conflicted copy ...) accanto a settings.json o .credentials.json.

Causa: due macchine hanno scritto contemporaneamente.

Fix: smettere di sincronizzare i file ad alta frequenza (.credentials.json, ~/.claude.json, history.jsonl, projects/*.jsonl). Limitare la sync ai file statici via symlink mirati (vedi §5.3).

---

11. Schema JSONL delle sessioni: parsing e analytics

I file ~/.claude/projects/<encoded>/<uuid>.jsonl sono accessibili in lettura e contengono dati utili per analytics: usage di modelli, distribuzione tool call, durata sessioni, conteggio token. Lo schema non è documentato ufficialmente e può cambiare tra versioni della CLI: gli script che parsano questi file vanno trattati come scratch tool, non come integrazione stabile. Per chi è già a suo agio con la pipeline shell, vale lo stesso approccio descritto nella guida ai comandi CLI per parsing e audit: jq, awk e poche righe bastano per estrarre metriche.

11.1 Anatomia di una riga

Ogni riga è un evento JSON. I tipi principali (type field):

• user — messaggio dell’utente
• assistant — risposta del modello, con usage.input_tokens, usage.output_tokens, model
• tool_use — chiamata a un tool
• tool_result — risultato di un tool
• system — messaggi di sistema (compaction, errori)

Ogni evento ha un timestamp ISO 8601 e un sessionId UUID.

11.2 Estrarre metriche con jq

Token consumati per sessione:

jq -s 'map(select(.type=="assistant") | .usage.input_tokens + .usage.output_tokens) | add' \
  ~/.claude/projects/d--python-script-wordpress-api/*.jsonl

Distribuzione modelli usati:

jq -r 'select(.type=="assistant") | .model' ~/.claude/projects/**/*.jsonl | sort | uniq -c

Numero medio tool call per sessione:

jq -s 'group_by(.sessionId) | map(map(select(.type=="tool_use")) | length) | add / length' \
  ~/.claude/projects/<encoded>/*.jsonl

11.3 Tool dell’ecosistema

Per chi vuole evitare di scrivere parser da zero (i due tool sotto sono progetti di terze parti, non distribuiti da Anthropic):

• ccusage (npm) — report di utilizzo token e costo stimato, naviga projects/ in automatico
• claude-history — viewer browser-based delle conversazioni passate
• Custom Python: la libreria jsonlines su PyPI è il modo più rapido per scrivere analytics ad hoc

---

12. Reference rapido

Path principali per OS

	macOS / Linux / WSL2	Windows
Cartella user	~/.claude/	%USERPROFILE%\.claude\
Config runtime	~/.claude.json	%USERPROFILE%\.claude.json
Memory user	~/.claude/CLAUDE.md	%USERPROFILE%\.claude\CLAUDE.md
Auto-memory	~/.claude/projects/<enc>/memory/MEMORY.md	idem
Credenziali	Keychain (macOS) / ~/.claude/.credentials.json	%USERPROFILE%\.claude\.credentials.json
Managed policy	/etc/claude-code/ (Linux) / /Library/Application Support/ClaudeCode/ (macOS)	C:\Program Files\ClaudeCode\

Comandi essenziali

claude --version                      # Versione installata
claude mcp list                       # Lista MCP server
claude mcp reset-project-choices      # Reset approvazioni .mcp.json
/memory                               # UI gestione memoria
/mcp                                  # UI MCP server e auth
/clear                                # Reset sessione corrente
/compact                              # Riassumi sessione per liberare context
/login                                # Re-autenticazione account Claude.ai

Variabili d’ambiente rilevanti

Variabile	Effetto
CLAUDE_CONFIG_DIR	Sposta tutta la config altrove
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1	Disattiva auto-memory
CLAUDE_CODE_ENABLE_TELEMETRY=0	Disattiva telemetria
CLAUDE_CODE_SKIP_PROMPT_HISTORY=1	Non scrivere su history.jsonl
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1	Carica CLAUDE.md da --add-dir
MCP_TIMEOUT	Timeout startup MCP (ms)
MAX_MCP_OUTPUT_TOKENS	Limite output MCP (default 25.000)
ENABLE_TOOL_SEARCH	Controllo del deferral MCP tools
DISABLE_AUTOUPDATER	Disabilita auto-update

Documentazione ufficiale

• Memoria: code.claude.com/docs/en/memory
• Settings: code.claude.com/docs/en/settings
• MCP: code.claude.com/docs/en/mcp
• CHANGELOG: github.com/anthropics/claude-code

---

In sintesi

Tre regole pratiche da portarsi a casa:

1. CLAUDE_CONFIG_DIR e autoMemoryDirectory rispondono a esigenze diverse — il primo sposta tutto, il secondo sposta solo la auto-memory. Per work/personal usa CLAUDE_CONFIG_DIR; per sync della sola memoria tra macchine usa autoMemoryDirectory
2. Non sincronizzare mai ~/.claude/ interamente su cloud commerciale — credenziali in chiaro su Linux/Windows e conflict garantiti su ~/.claude.json. Usa symlink mirati sui pochi file statici (commands, skills, agents, rules, CLAUDE.md)
3. Configura cleanupPeriodDays consapevolmente — il default 30 giorni va bene per uso personale, ma per progetti con dati clienti riduci a 7 o anche 1

Se gestisci Claude Code in team o su progetti enterprise e vuoi un’analisi del setup attuale, dei rischi privacy o del sync multi-macchina, contattami per una consulenza — o iscriviti alla newsletter per ricevere gli approfondimenti tecnici successivi su Claude Code, MCP server e agent workflow.