Claude Code CLI: Technischer Ueberblick auf Basis der offiziellen Anthropic-Dokumentation

Versão do conteúdo: outubro de 2026 Fontes: exclusivamente a documentação oficial da Anthropic ( code.claude.com/docs e support.claude.com ). A lista completa está em Fontes oficiais. Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e claude --help.

O Claude Code é uma ferramenta de programação agêntica da Anthropic. Ela lê o seu código, edita arquivos, executa comandos e se integra às suas ferramentas de desenvolvimento. O CLI é a versão de terminal: você roda claude dentro de uma pasta de projeto e conversa com um agente que trabalha nesse projeto.

Não é um autocomplete. O agente trabalha em ciclo:

O que ele faz, segundo a documentação oficial:

Onde o mesmo motor roda: terminal (CLI), VS Code/Cursor, JetBrains, aba Code do app desktop, web (claude.ai/code), app mobile e Slack. Arquivos CLAUDE.md, settings e servidores MCP do repositório valem em todas essas superfícies.

A página oficial de plataformas descreve o CLI como a superfície mais completa para trabalho no terminal e diz que scripting e o Agent SDK só existem nele.

# macOS, Linux, WSL — instalador nativo (recomendado) curl -fsSL https://claude.ai/install.sh | bash Enter fullscreen mode Exit fullscreen mode # Windows PowerShell irm https://claude.ai/install.ps1 | iex Enter fullscreen mode Exit fullscreen mode:: Windows CMD curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd Enter fullscreen mode Exit fullscreen mode # Alternativas brew install --cask claude-code # Homebrew (canal stable) brew install --cask claude-code@latest # Homebrew (canal latest) winget install Anthropic.ClaudeCode # WinGet npm install -g @anthropic-ai/claude-code # npm (Node.js 22+; nunca use sudo) Enter fullscreen mode Exit fullscreen mode Também há repositórios assinados para apt, dnf e apk (Debian, Fedora, RHEL, Alpine).

claude --version # imprime a versão, ex.: 2.1.211 (Claude Code) claude doctor # diagnóstico da instalação e das configurações, sem abrir sessão Enter fullscreen mode Exit fullscreen mode Atualizações Método de instalação Atualiza sozinho? Como atualizar Instalador nativo ✅ Sim, em segundo plano claude update para forçar Homebrew ❌ Não brew upgrade claude-code WinGet ❌ Não winget upgrade Anthropic.ClaudeCode apt / dnf / apk ❌ Não Pelo gerenciador do sistema npm ✅ Sim, se o diretório global do npm for gravável npm install -g @anthropic-ai/claude-code@latest (evite npm update -g ) O canal de atualização ( latest ou stable ) é definido pelo setting autoUpdatesChannel, ou em /config. O stable costuma estar cerca de uma semana atrás e pula versões com regressões graves.

claude # primeira execução: login pelo navegador claude auth login # login explícito (--console para cobrança via API) claude auth status # status em JSON; código de saída 0 = logado, 1 = não claude setup-token # gera um token OAuth de longa duração para CI e scripts Enter fullscreen mode Exit fullscreen mode claude setup-token exige assinatura Claude e abre o navegador uma vez para autorizar. O token é impresso no terminal e não fica salvo.

macOS: alguns atalhos com Option (como Option+P ) exigem configurar Option como Meta no terminal. Option+T funciona sem essa configuração.

! npm test Enter fullscreen mode Exit fullscreen mode O teste roda e o Claude explica as falhas sem você precisar de um segundo prompt.

Digite / para ver a lista completa e filtrar.

Pouca gente sabe: desde a v2.1.283, auto é o modo inicial das sessões interativas no terminal e no VS Code. E regras deny bloqueiam em qualquer modo, inclusive bypassPermissions.

O Claude Code tem dois sistemas de memória, e os dois são carregados como contexto, não como configuração obrigatória.

Se o repositório tem um AGENTS.md e nenhum CLAUDE.md (ou CLAUDE.local.md ), o Claude Code lê o AGENTS.md no lugar dele.

# Projeto - Build:./gradlew build - Testes:./gradlew test - Nunca editar arquivos em /generated - Convenções de API: @docs/api-conventions.md Enter fullscreen mode Exit fullscreen mode Boas práticas da documentação oficial:

Pegadinha: CLAUDE.md é contexto, não regra obrigatória. Para impedir uma ação de verdade, use regras deny de permissão ou hooks.

Em geral, o nível mais alto vence. Mas listas como permissions.allow e permissions.deny se somam entre os níveis, em vez de uma substituir a outra.

{ "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [ "Bash(npm run lint)", "Bash(npm run test *)" ], "deny": [ "Read(./.env)", "Read(./.env.*)" ] } } Enter fullscreen mode Exit fullscreen mode Detalhes que fazem diferença:

O que é: um comando seu (ou uma chamada HTTP, ferramenta MCP, prompt ou agente) que roda em pontos fixos do ciclo de vida da sessão. Ele não depende de o Claude decidir executá-lo.

Para que serve: formatar código depois de cada edição, bloquear comandos perigosos, registrar todo comando executado, notificar o time, carregar contexto no início da sessão.

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, PreCompact, PostCompact (a documentação lista dezenas de eventos).

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npm run format" } ] } ] } } Enter fullscreen mode Exit fullscreen mode Códigos de saída Código Efeito 0 Sucesso; a ação segue (salvo se o JSON de saída bloquear) 2 Erro bloqueante em eventos que podem bloquear. Em PreToolUse, bloqueia a ferramenta e devolve o stderr ao Claude como motivo Outros Erro não bloqueante; a ação segue e aparece um aviso Tipos de handler: command, http, mcp_tool, prompt e agent (este é experimental).

O que é: um assistente especializado que roda na sua própria janela de contexto, com prompt de sistema, ferramentas e permissões próprios. Ele devolve só um resumo, então logs e resultados de busca extensos não poluem a conversa principal.

Subagents nativos: Explore (busca rápida e só leitura), Plan (pesquisa no plan mode) e general-purpose (tarefas complexas com todas as ferramentas).

Arquivo em.claude/agents/ (projeto) ou ~/.claude/agents/ (todos os projetos):

--- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. Give specific, actionable feedback. Enter fullscreen mode Exit fullscreen mode Só name e description são obrigatórios. Outros campos: disallowedTools, model, permissionMode, skills, mcpServers, hooks, memory, isolation: worktree.

claude --agents '{"debugger": {"description": "Debugs errors", "prompt": "You are an expert debugger."}}' Enter fullscreen mode Exit fullscreen mode Recursos extras:

O que é: um arquivo SKILL.md com instruções (e arquivos de apoio opcionais) que ensina um procedimento. O Claude carrega a skill quando ela é relevante, ou você chama com /nome.

--- name: deploy description: Deploy the application to production disable-model-invocation: true --- Deploy $ARGUMENTS to production: 1. Run the test suite 2. Build the application 3.

Push to the deployment target Enter fullscreen mode Exit fullscreen mode disable-model-invocation: true: só você pode chamar (ideal para deploy). user-invocable: false: só o Claude pode chamar. $ARGUMENTS, $0, $1: recebem argumentos. Arquivos em.claude/commands/ continuam funcionando e também viram /nome; a skill acrescenta arquivos de apoio e controle de invocação. /skills lista as skills; /skill-doctor mostra o custo de contexto e o uso de cada uma. Custo de contexto: a descrição de cada skill fica sempre no contexto ( description + when_to_use são truncados em 1.536 caracteres na listagem).

O conteúdo completo só carrega quando a skill é usada.

Skills que já vêm prontas: /code-review, /batch, /debug, /loop, /claude-api, /verify, /run, /simplify, entre outras.

O que é: um diretório que empacota skills, agentes, hooks e servidores MCP para instalar como uma unidade.

Atenção: um plugin ativo entra em todas as sessões, consome contexto e roda com as suas permissões. Revise antes de instalar.

O MCP (Model Context Protocol) é um padrão aberto para conectar ferramentas de IA a fontes de dados externas.