Verificar e reparar

ccam doctor verifica a sua instalação do ccam: o binário do Claude Code, a pasta, o login e os links de compartilhamento de cada conta, os servidores MCP compartilhados, o endpoint de uso e os seus atalhos. ccam doctor --fix repara o que consegue sem perder dados e, antes, move para uma pasta de backup qualquer arquivo que substituir. Execute-o quando ccam <name> parar com um problema de link de compartilhamento, depois de restaurar arquivos manualmente ou depois de uma atualização do Claude Code.

Uso

ccam doctor                  # check everything, change nothing
ccam doctor --fix            # check, then repair what is safe to repair
ccam --dry-run doctor --fix  # report only: what --fix would repair

Cada resultado é uma linha com uma marca: ✓ OK, · informação, ! um aviso, ✗ um erro. Os resultados de contas começam com o nome da conta.

$ ccam doctor
✓ Claude Code 2.1.302 (Claude Code) (/home/me/.local/bin/claude)
! personal: folder permissions are 755 (should be 0700)
! personal: .credentials.json permissions are 644 (should be 0600)
✓ personal: login valid (me@example.com)
✗ personal: /home/me/.local/share/ccam/profiles/personal/settings.json: set to shared but is a real file, not a link
· personal: unknown entries (Claude Code layout may have changed): newthing
! work: not logged in → `ccam login work`
✓ work: share links OK
! missing shortcuts in /home/me/.local/bin: ccp

`ccam doctor --fix` repairs what it can.

Com --fix, cada resultado reparado termina em → fixed:

$ ccam doctor --fix
✓ Claude Code 2.1.302 (Claude Code) (/home/me/.local/bin/claude)
! personal: folder permissions are 755 (should be 0700) → fixed
! personal: .credentials.json permissions are 644 (should be 0600) → fixed
✓ personal: login valid (me@example.com)
✗ personal: /home/me/.local/share/ccam/profiles/personal/settings.json: set to shared but is a real file, not a link → fixed
· personal: unknown entries (Claude Code layout may have changed): newthing
! work: not logged in → `ccam login work`
✓ work: share links OK
! missing shortcuts in /home/me/.local/bin: ccp → fixed

Opções

ccam doctor não aceita argumentos. Ele respeita --dry-run: ccam --dry-run doctor --fix imprime os mesmos resultados que ccam doctor e não altera nada.

O código de saída é 1 quando sobra pelo menos um resultado ✗ sem reparo, e 0 nos outros casos. Avisos e informações nunca fazem a execução falhar. Quando a execução falha sem --fix, o ccam termina com uma linha em branco e `ccam doctor --fix` repairs what it can.. Uma configuração que não pode ser carregada também termina com 1 e um erro ccam:.

Como funciona

internal/cli/doctor.go carrega ~/.config/ccam/config.toml e chama doctor.Run em internal/doctor/doctor.go, que executa as verificações em uma ordem fixa e retorna os resultados. --fix é repassado como Options.Fix, definido como false em uma simulação.

O bloco do meio é executado uma vez por conta. As verificações, e o que --fix faz em cada uma:

1. Versão do Claude Code (checkClaude). Localiza o binário claude como o inicializador faz e executa claude --version. Se a versão não começar com 2.1.302, a versão contra a qual o layout de pastas do ccam foi verificado (doctor.LayoutVersion), ele adiciona · ccam was verified against the folder layout of Claude Code 2.1.302. Any 'unknown entries' below may mean the layout changed. Um binário ausente ou um --version que falha é um erro. Sem reparo.
2. Credenciais no ambiente (checkAuthEnv). Avisa quando CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY ou ANTHROPIC_AUTH_TOKEN está definida: toda conta iniciada nesse shell a herda, e o Claude Code a prefere ao login da própria conta. Sem reparo; remova a variável você mesmo.
3. Pasta (checkProfile). Uma pasta de conta ausente é um erro e encerra as verificações dessa conta. Permissões com qualquer bit de grupo ou de outros definido são um aviso; --fix executa chmod 0700.
4. Arquivo de login (checkCredentials). .credentials.json é verificado com lstat. Um link simbólico é um erro, porque cada conta precisa ter o próprio token, e não é reparado. Um modo diferente de 0600 é um aviso; --fix executa chmod 0600. Depois o login é lido (no macOS, primeiro do Acesso às Chaves). A falta de login é um aviso que indica ccam login <name>. Um token de renovação expirado é o erro login expired; um token de acesso expirado é apenas informação, já que o Claude Code o renova na próxima inicialização. Nenhum desses é reparado.
5. Links de compartilhamento (share.Check). Compara cada caminho de share.Layout com as configurações de compartilhamento da conta, usando só lstat e readlink. Ele informa quatro tipos: um link ausente, um link que aponta para outro lugar, um arquivo comum onde deveria haver um link e um link que sobrou de um item que agora é local. Um link ausente é um aviso; os outros são erros.
6. Entradas desconhecidas (checkUnknownEntries). Lista os nomes de primeiro nível na pasta da conta que o ccam não conhece (share.Known), como um indício de que o layout do Claude Code mudou. Apenas informação.
7. Caminhos de plugins (checkPlugins). Os registros de plugins (installed_plugins.json, known_marketplaces.json) armazenam caminhos absolutos. No plugins/ de cada grupo, caminhos que passam pela pasta de uma conta deixam de funcionar quando essa conta é removida ou renomeada. --fix os reescreve para a pasta do grupo com profile.RewritePluginPaths, uma gravação atômica do arquivo de registro.
8. Servidores MCP (checkMCP). Carrega o mcp.json de cada grupo uma vez. Um arquivo que não pode ser lido é um erro; um servidor que não passa em mcp.Validate é um aviso. Sem reparo.
9. Formato da resposta de uso (checkUsageFormat). Consulta o endpoint de uso, sem o cache e com o limite habitual de 3 segundos, para uma conta após a outra, até que uma responda. Se a resposta não puder mais ser interpretada, ele avisa que ccam usage passa a usar o cache da linha de status. Esta é a única verificação que usa a rede.
10. Atalhos (checkShims). Só quando uma conta tem um atalho. Links ausentes em ~/.local/bin são um aviso; --fix chama shim.Install, que só cria os links ausentes e nunca mexe em outros arquivos. Uma pasta bin que não está no PATH é um aviso e não é reparada.

Reparar links de compartilhamento

O caminho de inicialização cria na hora um link ausente, mas para diante de qualquer coisa que possa perder dados e indica este comando:

$ ccam work
ccam: stopped because of share link problems:
  /home/me/.local/share/ccam/profiles/work/CLAUDE.md: set to shared but is a real file, not a link
Repair them with `ccam doctor --fix`, then run again

Para qualquer problema de link de compartilhamento, --fix chama share.Build com as configurações de compartilhamento da conta como estado atual e como estado de destino, e depois Plan.Apply. Build deriva de novo cada etapa a partir do que está no disco, o mesmo plano que o ccam share usa, então o reparo segue as mesmas regras de ativar o compartilhamento.

Aqui, settings.json é um arquivo comum. Como o grupo já tem um settings.json diferente, o conflito usa a escolha padrão, KeepGroup, e a cópia do grupo permanece. O arquivo da conta vai para .ccam-backup/<time>/settings.json dentro da pasta da conta, e os.Symlink vincula o caminho ao grupo. Outros casos:

• Se o grupo ainda não tem uma cópia, o arquivo da conta vai para o grupo e se torna o primeiro conteúdo dele.
• No caso de uma pasta, os arquivos que o grupo não tem vão para o grupo; o resto vai para o backup.
• Para history.jsonl, o padrão é merge by line: as linhas do grupo e depois as suas novas. A cópia anterior do grupo é salva em .ccam-backup/<time>/group/.
• Um link para outro grupo é substituído. Um link para uma pasta fora do ccam vai para o backup, e o conteúdo dela inicia o grupo se ele estiver vazio.
• Um link que sobrou de um item que agora é local é removido, e a conta recebe uma cópia do conteúdo do grupo.

Exceto pela remoção de links, cada etapa move dados para o grupo ou para a pasta de backup. Nada é excluído.

Segurança e casos especiais

• Um ccam doctor simples nunca altera nada. Em scripts, use --dry-run com --fix para ter certeza.
• doctor --fix não verifica se uma conta está em execução. Encerre o Claude Code de uma conta antes de reparar os links de compartilhamento dela, porque a sessão continua gravando nesses arquivos.
• Se um reparo de compartilhamento falhar, o ccam informa could not repair share links: <error> para essa conta e pula a verificação de entradas desconhecidas dela. As outras contas continuam sendo verificadas.
• Se ccam share falhar no meio, ele salva antes as configurações de destino e pede que você conclua com ccam doctor --fix.
• Um .credentials.json com link simbólico, um login expirado e credenciais no ambiente são informados, mas nunca alterados.
• As reescritas dos registros de plugins são gravadas de forma atômica, mas não são copiadas para .ccam-backup/.

Relacionados

• Compartilhar servidores MCP, configurações e histórico
• Copiar uma configuração existente
• Limites de uso e troca de contas
• Comandos