Explore o diretório .claude

Claude Code lê instruções, configurações, skills, subagents e memória do seu diretório de projeto e de ~/.claude em seu diretório home. Confirme arquivos de projeto no git para compartilhá-los com sua equipe; arquivos em ~/.claude são configuração pessoal que se aplica em todos os seus projetos. No Windows, ~/.claude é resolvido para %USERPROFILE%\.claude. Se você definir CLAUDE_CONFIG_DIR, cada caminho ~/.claude nesta página fica sob esse diretório. A maioria dos usuários apenas edita CLAUDE.md e settings.json. Se seu repositório já tiver um AGENTS.md para outros agentes de codificação, Claude Code pode ler isso por conta própria ou junto com CLAUDE.md. O resto do diretório é opcional: adicione skills, rules ou subagents conforme necessário.

Explore o diretório

Clique em arquivos na árvore para ver o que cada um faz, quando carrega e um exemplo.

O que não é mostrado

O explorador cobre arquivos que você cria e edita. Alguns arquivos relacionados vivem em outro lugar:

Arquivo	Localização	Propósito
`managed-settings.json`	Nível do sistema, varia por SO	Configurações impostas pela empresa que você não pode substituir, exceto por exceções limitadas. Veja onde salvar o arquivo e qual fonte gerenciada Claude Code usa.
`CLAUDE.local.md`	Raiz do projeto	Suas preferências privadas para este projeto, carregadas junto com CLAUDE.md. Crie manualmente e adicione a `.gitignore`.
`AGENTS.md`	Raiz do projeto, `.claude/`, ou qualquer diretório	Instruções do projeto que você escreve para agentes de codificação de IA. Claude Code pode carregá-lo por conta própria ou junto com `CLAUDE.md`.
Plugins instalados	`~/.claude/plugins`	Marketplaces clonados, versões de plugins instalados, o registro de instalação `installed_plugins.json` e dados por plugin, gerenciados por comandos `claude plugin`. Plugins sincronizados da sua conta claude.ai são baixados em `~/.claude/plugins/synced/`. Para um plugin instalado de um marketplace com fonte `command` em modo de link, Claude Code armazena links aqui em vez de uma cópia, e os arquivos do plugin permanecem no diretório que o comando imprime. Uma fonte `command` requer Claude Code v2.1.229 ou posterior. Um plugin listado por caminho relativo em um marketplace de diretório local também carrega no local de seu diretório de origem em vez de uma cópia em cache. Veja cache de plugins para saber como versões órfãs são limpas.

~/.claude também contém dados que Claude Code escreve conforme você trabalha: transcrições, histórico de prompts, snapshots de arquivos, caches e logs. Veja dados da aplicação abaixo.

Escolha o arquivo certo

Diferentes tipos de personalização vivem em arquivos diferentes. Use esta tabela para encontrar onde uma mudança pertence.

Você quer	Editar	Escopo	Referência
Dar a Claude contexto e convenções do projeto	`CLAUDE.md`	projeto ou global	Memory
Permitir ou bloquear chamadas de ferramentas específicas	`settings.json` `permissions` ou `hooks`	projeto ou global	Permissions, Hooks
Executar um script antes ou depois de chamadas de ferramentas	`settings.json` `hooks`	projeto ou global	Hooks
Definir variáveis de ambiente para a sessão	`settings.json` `env`	projeto ou global	Settings
Manter substituições pessoais fora do git	`settings.local.json`	apenas projeto	Escopos de configurações
Adicionar um prompt ou capacidade que você invoca com `/name`	`skills/<name>/SKILL.md`	projeto ou global	Skills
Definir um subagent especializado com suas próprias ferramentas	`agents/*.md`	projeto ou global	Subagents
Orquestrar muitos subagents a partir de um script	`workflows/*.js`	projeto ou global	Dynamic workflows
Conectar ferramentas externas sobre MCP	`.mcp.json`	apenas projeto	MCP
Mudar como Claude formata respostas	`output-styles/*.md`	projeto ou global	Output styles

Referência de arquivos

Esta tabela lista cada arquivo que o explorador cobre. Arquivos de escopo de projeto vivem em seu repositório sob .claude/ (ou na raiz para CLAUDE.md, .mcp.json e .worktreeinclude). Arquivos de escopo global vivem em ~/.claude/ e se aplicam em todos os projetos.

Várias coisas podem substituir o que você coloca nesses arquivos:

Configurações gerenciadas implantadas por sua organização têm precedência sobre tudo, exceto pelas exceções sob Precedência de configurações
Flags CLI como --permission-mode ou --settings substituem settings.json para essa sessão
Algumas variáveis de ambiente têm precedência sobre sua configuração equivalente, mas isso varia: verifique a referência de variáveis de ambiente para cada uma

Veja precedência de configurações para a ordem completa.

Clique em um nome de arquivo para abrir esse nó no explorador acima.

Arquivo	Escopo	Confirmar	O que faz	Referência
`CLAUDE.md`	Projeto e global	✓	Instruções carregadas a cada sessão	Memory
`rules/*.md`	Projeto e global	✓	Instruções com escopo de tópico, opcionalmente com gate de caminho	Rules
`settings.json`	Projeto e global	✓	Permissões, hooks, variáveis de env, padrões de modelo	Settings
`settings.local.json`	Apenas projeto		Suas substituições pessoais, auto-gitignored quando Claude Code salva uma configuração nele	Escopos de configurações
`.mcp.json`	Apenas projeto	✓	Servidores MCP compartilhados pela equipe	Escopos MCP
`.worktreeinclude`	Apenas projeto	✓	Arquivos gitignored para copiar em novos worktrees	Worktrees
`skills/<name>/SKILL.md`	Projeto e global	✓	Prompts reutilizáveis invocados com `/name` ou auto-invocados	Skills
`commands/*.md`	Projeto e global	✓	Prompts de arquivo único; mesmo mecanismo que skills	Skills
`output-styles/*.md`	Projeto e global	✓	Seções de prompt do sistema personalizadas	Output styles
`agents/*.md`	Projeto e global	✓	Definições de subagents com seu próprio prompt e ferramentas	Subagents
`workflows/*.js`	Projeto e global	✓	Scripts de workflow dinâmicos escritos por Claude e salvos de `/workflows`; cada arquivo se torna um comando `/<name>`	Dynamic workflows
`agent-memory/<name>/`	Projeto e global	✓	Memória persistente para subagents	Memória persistente
`~/.claude.json`	Apenas global		Estado da aplicação, OAuth, toggles de UI, servidores MCP pessoais	Configuração global
`projects/<project>/memory/`	Apenas global		Auto memory: notas de Claude para si mesmo entre sessões	Auto memory
`keybindings.json`	Apenas global		Atalhos de teclado personalizados	Keybindings
`themes/*.json`	Apenas global		Temas de cores personalizados	Temas personalizados

Campos de frontmatter por arquivo

Skills, arquivos de comando, subagentes, estilos de saída e regras leem sua configuração do YAML frontmatter no topo do arquivo, e cada um aceita seu próprio conjunto de campos. Esta tabela lista os nomes dos campos para cada arquivo e vincula à referência que os descreve.

Arquivo	Campos de frontmatter	Referência
`skills/<name>/SKILL.md`	`name`, `description`, `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, `shell`, `metadata`, `license`, `compatibility`	Frontmatter de skill
`commands/*.md`	Os campos de skill exceto `name` e `paths`	Frontmatter de skill
`agents/*.md`	`name`, `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `maxTurns`, `skills`, `mcpServers`, `hooks`, `memory`, `background`, `effort`, `isolation`, `color`, `initialPrompt`, `omitClaudeMd`, `experimental`	Frontmatter de subagente
`output-styles/*.md`	`name`, `description`, `keep-coding-instructions`, `force-for-plugin`	Frontmatter de estilo de saída
`rules/*.md`	`paths`	Frontmatter de regra

Agentes fornecidos em um plugin honram um subconjunto dos campos de subagente.

Solucione problemas de configuração

Se uma configuração, hook ou arquivo não está tendo efeito, veja Debug your configuration para os comandos de inspeção e uma tabela de busca por sintoma.

Dados da aplicação

Além da configuração que você cria, ~/.claude contém dados que Claude Code escreve durante as sessões. Esses arquivos são texto simples. Qualquer coisa que passa por uma ferramenta é escrita em uma transcrição no disco: conteúdo de arquivos, saída de comandos, texto colado.

Limpeza automática

Claude Code deleta os arquivos nos caminhos abaixo uma vez que tenham mais de cleanupPeriodDays de idade, desde que possa determinar com segurança o período de retenção. O padrão é 30 dias e o mínimo é 1; definir 0 falha com um erro de validação. O mesmo limite de idade se aplica à remoção automática de worktrees órfãs.

Caminho sob `~/.claude/`	Conteúdo
`projects/<project>/<session>.jsonl`	Transcrição completa da conversa: cada mensagem, chamada de ferramenta e resultado de ferramenta
`projects/<project>/<session>.orphaned-<timestamp>-<suffix>.jsonl`, `projects/<project>/<session>.jsonl.superseded-<timestamp>`	Uma transcrição anterior da sessão que Claude Code separou em vez de sobrescrever ou deletar. Não aparece no seletor de sessão
`projects/<project>/<session>/subagents/`	Transcrições de conversa de Subagent, removidas com a transcrição da sessão pai quando envelhece
`projects/<project>/<session>/tool-results/`	Grandes saídas de ferramentas derramadas em arquivos separados, e cópias em tamanho completo de imagens que ferramentas MCP retornam
`file-history/<session>/`	Snapshots pré-edição de arquivos que Claude alterou, usados para restauração de checkpoint. Contém snapshots dos 100 checkpoints mais recentes; arquivos de snapshot que nenhum checkpoint retido referencia são deletados, exceto o primeiro snapshot de cada arquivo
`plans/`	Arquivos de plano escritos durante plan mode
`debug/`	Logs de debug por sessão, escritos enquanto o debug logging está ativado, como quando você inicia com `--debug` ou executa `/debug`
`paste-cache/`	Conteúdo de grandes colagens
`image-cache/<session>/`	Imagens anexadas salvas por Claude Code v2.1.274 e anteriores. Versões posteriores salvam imagens coladas e anexadas fora de `~/.claude`, em um diretório `images/` para cada sessão sob o diretório temporário que `CLAUDE_CODE_TMPDIR` controla. A varredura remove diretórios restantes de outras sessões aqui, independentemente da idade.
`uploads/<session>/`	Arquivos que você anexa da web ou do aplicativo móvel, e fotos que você anexa do aplicativo móvel, ao enviar mensagens para uma sessão de Remote Control. Um anexo a uma sessão em nuvem é salvo no próprio ambiente em nuvem dessa sessão, não na sua máquina.
`session-env/`	Metadados de ambiente por sessão
`tasks/`	Listas de tarefas escritas pelas ferramentas de tarefa, um diretório por lista
`shell-snapshots/`	Aliases, funções e opções de shell capturadas na inicialização e aplicadas pela ferramenta Bash a cada comando. Removidas na saída limpa. A varredura limpa qualquer uma deixada após um crash.
`backups/`	Versões anteriores de `~/.claude.json`, copiadas quando Claude Code reescreve o arquivo. Claude Code mantém as cinco mais novas, mais uma cópia de qualquer versão que não conseguiu analisar.
`feedback-bundles/`	Arquivos de transcrição reduzidos escritos por `/feedback` em provedores de terceiros ou quando nenhuma credencial Anthropic está configurada, para enviar à sua equipe de conta Anthropic
`feedback/drafts/`	Feedback redigido por Claude enfileirado aguardando sua revisão em `/feedback`. Varrido após `cleanupPeriodDays` ou 30 dias, o que for menor. Quando a fila está no seu limite de 10 rascunhos, Claude Code deleta o rascunho mais antigo para liberar espaço.
`usage-data/`	`report.html` e cópias de relatório com timestamp escritas por `/insights`, mais dados de análise em cache por sessão usados para construí-los
`skills/.trash/`, `plugins/.trash/`	Skills e plugins que a sincronização de claude.ai removeu, como depois que você desativa um em claude.ai ou para de sincronizar. Os arquivos ficam aqui para que você possa recuperá-los até a varredura deletá-los
`todos/`, `statsig/`, `logs/`	Diretórios legados de versões mais antigas. Não são mais escritos. A varredura remove seu conteúdo e depois o diretório vazio.

Arquivos de sessão em sessions/, memória automática, e transcrições de Claude Desktop e Cowork seguem cada uma sua própria regra de retenção:

sessions/: contém um pequeno arquivo por sessão em execução, usado para detectar sessões simultâneas e crashes. Não faz parte da varredura baseada em idade: Claude Code remove cada arquivo quando sua sessão sai e limpa resíduos de crash no próximo lançamento.
Memória automática: a varredura não deleta os arquivos de memória no diretório de memória automática de um projeto, projects/<project>/memory/. Claude Code remove esse diretório apenas se ele esteve vazio durante todo o período de retenção. Antes da v2.1.228, a varredura tratava pastas dentro do diretório de memória como dados de sessão e podia deletar arquivos antigos sob ele.
Transcrições de Claude Desktop e Cowork: Claude Code mantém a transcrição de uma sessão que você iniciou ou continuou mais recentemente em Claude Desktop ou Cowork em qualquer idade. Para dar a essas transcrições um limite de idade, defina desktopSessionCleanupPeriodDays. Quando configurações gerenciadas definem cleanupPeriodDays, Claude Code deleta essas transcrições após esse período em vez disso. Requer Claude Code v2.1.248 ou posterior; versões anteriores as deletam após cleanupPeriodDays.

Claude Code pula a varredura baseada em idade nestes casos:

Modo bare: quando você executa claude -p com --bare, Claude Code não executa a varredura nessa sessão.
Varredura pausada: se Claude Code não conseguir determinar com segurança o período de retenção, ele pausa a varredura de limpeza de retenção; o evento retention_sweep lista cada configuração que a pausa. Quando a causa é um arquivo de configurações que não pode ser lido ou analisado, ou erros de configurações com cleanupPeriodDays ou desktopSessionCleanupPeriodDays explicitamente definidos, Claude Code também mostra um aviso em /status até você corrigir os erros de configurações. Quando configurações gerenciadas fornecem cleanupPeriodDays, Claude Code executa a varredura no valor gerenciado em qualquer caso.

Diretório de bloco de notas por sessão

O bloco de notas é um diretório por sessão que Claude Code fornece a Claude para arquivos temporários: resultados intermediários, scripts auxiliares e rascunhos que não pertencem ao seu projeto. Quando Claude diz que salvou algo “no bloco de notas”, o arquivo está lá. Claude o usa em vez de /tmp, e pode criar, editar e ler arquivos nele sem um prompt de permissão. O bloco de notas fica sob o diretório temporário de Claude Code em vez de ~/.claude. Encontre o caminho da sessão atual para sua plataforma:

macOS: /private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/
Linux: /tmp/claude-<uid>/<project>/<session-id>/scratchpad/, ou a mesma forma sob $TMPDIR quando seu sistema define um
Windows: %TEMP%\claude\<project>\<session-id>\scratchpad\

<project> é o caminho do seu diretório de trabalho com cada caractere que não seja letra ou dígito substituído por -, como -Users-you-my-project. Se você definir CLAUDE_CODE_TMPDIR, a árvore se move sob esse diretório em vez disso. Hooks recebem o caminho da sessão atual como scratchpad_dir. Arquivos do bloco de notas duram enquanto a transcrição da sessão: a varredura de retenção deleta o diretório quando deleta a transcrição, e claude project purge não toca no diretório temporário. Como o diretório fica sob a localização temporária do sistema, seu sistema operacional também pode limpá-lo, como na reinicialização. Para manter algo que Claude escreveu lá, peça a Claude para movê-lo para seu projeto. Uma sessão tem um bloco de notas apenas quando todos estes se aplicam:

Você está conectado com uma conta claude.ai em vez de uma chave de API
A sessão usa a API Anthropic, não Amazon Bedrock, Google Cloud’s Agent Platform ou Microsoft Foundry
enableArtifact não está definido como false

Mantido até você deletar

A varredura de limpeza de retenção não remove os caminhos abaixo. Claude Code os mantém até você deletá-los, além dos dois caches que deleta quando você faz logout.

Caminho sob `~/.claude/`	Conteúdo
`history.jsonl`	Cada prompt que você digitou, com timestamp e caminho do projeto. Usado para recall de seta para cima, busca de histórico `Ctrl+R` e conclusão de comando shell `!`.
`stats-cache.json`	Contagens agregadas de token e custo mostradas por `/usage`
`remote-settings.json`	Cópia em cache de configurações gerenciadas pelo servidor para sua organização, ou `{}` quando sua organização não configurou nenhuma. Presente apenas quando a sessão as busca. Claude Code verifica atualizações na inicialização e a cada hora durante uma sessão. Claude Code a deleta quando você faz logout.
`cache/changelog.md`	Cópia em cache do changelog de Claude Code, mostrada por `/release-notes`. Atualizada em segundo plano.
`policy-limits.json`	Configurações de política de recursos em cache para sua organização. Presente apenas para alguns tipos de conta. Atualizada automaticamente. Um sidecar `policy-limits.json.stamp.json` registra qual conta ou chave de API o cache pertence. Claude Code deleta ambos os arquivos quando você faz logout.

Outros arquivos aparecem dependendo de quais recursos você usa. Caches e arquivos de lock são seguros para deletar. Mantenha esses arquivos de estado:

.credentials.json: suas credenciais de login
agent-memory/: memória de subagent
jobs/ e daemon/: estado de sessão em segundo plano

Armazenamento em texto simples

Transcrições e histórico não são criptografados em repouso. As permissões de arquivo do SO são a única proteção. Se uma ferramenta ler um arquivo .env ou um comando imprimir uma credencial, esse valor é escrito em projects/<project>/<session>.jsonl. Para reduzir a exposição:

Reduza cleanupPeriodDays para encurtar quanto tempo Claude Code mantém transcrições
Defina desktopSessionCleanupPeriodDays para dar também um limite de idade às transcrições de Claude Desktop e Cowork
Defina a variável de ambiente CLAUDE_CODE_SKIP_PROMPT_HISTORY para pular a escrita de transcrições e histórico de prompt em qualquer modo. Em modo não interativo, você pode passar --no-session-persistence junto com -p, ou definir persistSession: false no TypeScript Agent SDK; o Python SDK não tem opção equivalente.
Use regras de permissão para negar leituras de arquivos de credenciais

Limpar dados locais

Execute claude project purge para deletar o estado que Claude Code mantém para um projeto. Deleta:

Transcrições e memória automática sob projects/
Entradas de tasks/, debug/ e file-history/ por sessão
Linhas de prompt correspondentes em history.jsonl
A entrada do projeto em ~/.claude.json

Imagens que você colou ou anexou nas sessões do projeto e o bloco de notas de cada sessão são armazenados sob o diretório temporário de Claude Code em vez de ~/.claude, então a limpeza não as remove. A varredura de retenção ainda deleta as imagens uma vez que tenham mais de cleanupPeriodDays de idade; o bloco de notas de uma sessão purgada permanece até você deletá-lo ou seu sistema operacional limpar o diretório temporário. O comando imprime o plano completo de exclusão e pede confirmação antes de remover qualquer coisa. Os exemplos abaixo usam ~/work/my-repo como um espaço reservado. Substitua-o pelo caminho para seu projeto. Se nenhum estado corresponder ao caminho, o comando imprime um erro e sai com status 1. Visualize o plano sem deletar nada:

claude project purge ~/work/my-repo --dry-run

O plano lista cada item correspondente e por que está incluído:

Purge plan for /home/user/work/my-repo:

  dir:    /home/user/.claude/projects/-home-user-work-my-repo
           project transcripts (.jsonl) and memory/
  config: projects["/home/user/work/my-repo"]
           project entry in ~/.claude.json (trust, history, MCP servers)
  filter: /home/user/.claude/history.jsonl
           12 prompt(s) typed in this project

shell-snapshots/ are not project-scoped and will not be touched
backups/ may still contain this project entry in old .claude.json snapshots (/home/user/.claude/backups); at most 5 are kept and they rotate out automatically
Dry run: 3 item(s) would be deleted.

Delete com um único prompt de confirmação:

claude project purge ~/work/my-repo

O comando imprime o mesmo plano, depois pergunta Delete 3 item(s) for /home/user/work/my-repo? This cannot be undone. [y/N] e deleta apenas se você responder y. Omita o caminho para escolher um projeto de uma lista interativa. Pule o prompt de confirmação para uso em scripts:

claude project purge ~/work/my-repo --yes

Passe --all em vez de um caminho para limpar o estado de cada projeto de uma vez, o que deleta history.jsonl completamente em vez de filtrá-lo. Passe -i para percorrer o plano de exclusão um item por vez. O comando deixa shell-snapshots/ e backups/ sozinhos porque não têm escopo de projeto, e avisa sobre eles na saída do plano. Você também pode deletar qualquer um dos caminhos de dados da aplicação acima manualmente, além dos arquivos de estado para manter. Novas sessões não são afetadas. A tabela abaixo mostra o que você perde para sessões passadas.

Deletar	Você perde
`~/.claude/projects/`	Retomar, continuar e retroceder para sessões passadas, e memória automática para cada projeto
`~/.claude/history.jsonl`	Recall de prompt com seta para cima, busca de histórico `Ctrl+R` e conclusão de comando shell `!`
`~/.claude/paste-cache/`	Texto colado em prompts recuperados; veja colar conteúdo grande
`~/.claude/uploads/`	Anexos que sessões passadas de Remote Control referem por caminho
`~/.claude/file-history/`	Restauração de checkpoint para sessões passadas
`~/.claude/stats-cache.json`	Totais históricos mostrados por `/usage`
`~/.claude/usage-data/`	Relatórios passados de `/insights` e os dados de análise em cache usados para construí-los
`~/.claude/feedback-bundles/`	Feedback e arquivos de relatório de bug que você ainda não enviou à sua equipe de conta Anthropic
`~/.claude/feedback/drafts/`	Feedback redigido por Claude que você não enviou
`~/.claude/remote-settings.json`	Nada. Re-buscado no próximo lançamento.
`~/.claude/cache/changelog.md`	Nada. Atualizado em segundo plano.
`~/.claude/policy-limits.json`	Nada. Atualizado automaticamente.
`~/.claude/tasks/`	Listas de tarefas que uma sessão retomada pegaria
`~/.claude/skills/.trash/`, `~/.claude/plugins/.trash/`	A chance de recuperar skills sincronizadas e plugins sincronizados que Claude Code removeu
`~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/session-env/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/`	Nada voltado para o usuário
`~/.claude/todos/`, `~/.claude/statsig/`, `~/.claude/logs/`, `~/.claude/image-cache/`	Nada. Diretórios legados não escritos pelas versões atuais.

Não delete ~/.claude.json, ~/.claude/settings.json ou ~/.claude/plugins/: esses mantêm sua autenticação, preferências e plugins instalados.

Gerenciar memória de Claude: escrever e organizar CLAUDE.md, rules e auto memory
Configurar configurações: definir permissões, hooks, variáveis de ambiente e padrões de modelo
Criar skills: construir prompts e workflows reutilizáveis
Configurar subagents: definir agentes especializados com seu próprio contexto

Primeiros passos

Conceitos principais

Usar Claude Code

Plataformas e integrações