Modos de uso: interativo, não-interativo, pipe e headless

# Modo interativo: interface TUI (Text User Interface) completa
cd meu-projeto
claude

# O que você obtém:
# - Histórico de conversa na sessão
# - Visualização de cada ação de ferramenta antes de executar
# - Comandos /help, /clear, /compact, /cost, /model
# - Confirmação explícita de comandos Bash perigosos
# - Modo de edição multi-linha (Enter: nova linha, Ctrl+Enter: enviar)

# Fluxo típico de uma sessão interativa:
# 1. Você descreve o problema ou tarefa
# 2. Claude lê os arquivos relevantes (você vê: "Reading src/auth.ts...")
# 3. Claude propõe ações (edições, novos arquivos, comandos)
# 4. Para Bash: mostra o comando, você aprova ou recusa
# 5. Claude executa, reporta resultado, sugere próximos passos

# Para retomar contexto de uma sessão anterior:
claude --continue   # retoma a última sessão
claude --resume     # lista sessões recentes para escolher

# Modo não-interativo: -p / --print
# Processa um prompt único e retorna em stdout. Zero TUI.

claude -p "liste os arquivos TypeScript que importam de @/lib/auth"
# → saída vai para stdout, pode ser capturada ou redirecionada

# Opção --output-format para saída estruturada
claude -p "analise o arquivo package.json e retorne um JSON com: nome, versão, dependências principais"   --output-format json
# → retorna JSON parseável (útil para pipelines que processam a saída)

# Desabilitar confirmações para automação segura
claude -p "atualize a versão no package.json para 2.1.0"   --allowedTools Edit   --print
# Claude só pode usar Edit — não pode rodar Bash ou Write

# Exemplo completo: script de análise de código
#!/bin/bash
for file in src/**/*.ts; do
  echo "=== Analisando: $file ==="
  claude -p "encontre problemas de segurança neste arquivo: $(cat "$file")"     --allowedTools Read     --print >> security_report.txt
done

# Modo pipe: Claude como processador de texto/código no pipeline Unix
# Input via stdin + -p + resultado em stdout

# Exemplos práticos:

# Sumarizar saída de comando longo
npm run build 2>&1 | claude -p "resuma os erros de build em português, lista de bullets"

# Revisar diff antes de commit
git diff --staged | claude -p "revise este diff: há problemas, edge cases não tratados ou violações de convenção?"

# Analisar logs de erro
tail -100 /var/log/nginx/error.log | claude -p "identifique o padrão de erros mais frequente e sugira causa raiz"

# Converter formato de dados
cat dados.csv | claude -p "converta este CSV para JSON, um objeto por linha, sem explicação"

# Gerar mensagem de commit a partir do diff
git diff HEAD | claude -p "gere uma mensagem de commit no estilo Conventional Commits para este diff"
# → feat(auth): add JWT expiration validation

# Com múltiplos inputs (heredoc):
claude -p "$(cat <<'EOF'
Você vai receber um trecho de código Python.
Refatore para usar list comprehension onde aplicável.
Código:
$(cat meu_script.py)
EOF
)"

# Nota: pipe funciona com -p. Sem -p, Claude tenta abrir o TUI mesmo com stdin piped
echo "analise isso" | claude    # ❌ abre TUI, pode travar
echo "analise isso" | claude -p # ✅ processa via stdin e responde em stdout

# Modo headless: Claude Code como ferramenta em pipelines CI/CD

# Exemplo: GitHub Actions que revisa PRs
# .github/workflows/review.yml
name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @anthropic-ai/claude-code
      - name: Revisar PR com Claude
        env:
          ANTHROPIC_API_KEY: ${'$'}{{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD > pr_diff.txt
          claude -p "$(cat <<'EOF'
            Revise este diff de PR. Retorne JSON com:
            { "aprovado": bool, "problemas": ["lista"], "sugestoes": ["lista"] }
            Diff: $(cat pr_diff.txt)
            EOF
          )" --output-format json > review.json
          cat review.json

# Usar o SDK do Claude Code (para integração em Node.js):
import ClaudeCode from "@anthropic-ai/claude-code";

const client = new ClaudeCode.ClaudeCode();

// Rodar uma tarefa e capturar mensagens
for await (const message of client.processMessages({
  prompt: "Explique a arquitetura do projeto",
  options: {
    cwd: "/caminho/do/projeto",
    allowedTools: ["Read", "Glob"],
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

# Opção 1: --allowedTools (recomendado para scripts)
# Especifica exatamente quais ferramentas Claude pode usar SEM confirmar
# Ferramentas fora da lista: Claude pergunta antes de usar (ou não usa)

claude -p "leia o README e gere um resumo"   --allowedTools Read,Glob
# Claude só pode ler — não pode editar, criar ou rodar comandos

claude -p "adicione type hints nos arquivos Python em src/"   --allowedTools Edit,Read,Glob
# Claude pode editar mas não rodar npm/python ou criar arquivos novos

# Opção 2: --dangerously-skip-permissions (use com extremo cuidado)
# Desabilita TODAS as confirmações — Claude executa qualquer ação sem perguntar
# SOMENTE em ambientes isolados (container descartável, sandbox)

# ❌ Errado em ambiente local:
claude -p "instale dependências e execute os testes"   --dangerously-skip-permissions
# Claude pode deletar arquivos, instalar pacotes, rodar qualquer comando

# ✅ Correto: ambiente Docker isolado
docker run --rm -v $(pwd):/workspace anthropic/claude-code   -p "rode os testes e corrija os que falharem"   --dangerously-skip-permissions

# Regra geral:
# - Desenvolvimento local interativo → confirmações habilitadas (padrão)
# - Scripts seguros → --allowedTools com lista mínima
# - Automação total em sandbox → --dangerously-skip-permissions em container

# /batch — paraleliza grandes mudanças em 5-30 worktrees + PRs simultâneos
# Ideal para migrações e refactorings que tocam dezenas de arquivos
/batch "migrar todos os useState para useReducer em src/features/"
# → Claude abre worktrees paralelos, executa em cada um, abre PRs separados

# /loop — executa o mesmo prompt em intervalo regular (ou auto-paced)
/loop 5m /status                      # roda /status a cada 5 minutos
/loop "verifique se o deploy terminou"  # auto-paced: Claude decide quando checar
# Útil para polling de builds, deploys, CI/CD

# /schedule — cria triggers recorrentes (cron remoto na infra Anthropic)
/schedule "Toda sexta 14h: gerar relatório de PRs mergeados da semana"
/schedule "Diariamente 9h: revisar issues abertas e priorizar"
# Rodam em cloud mesmo quando seu terminal está fechado

# /ultraplan — spawn session em modo "planning mode" na web (máxima capacidade)
/ultraplan "Arquitetura para multi-tenancy do sistema de pagamentos"
# → Abre sessão web com contexto 1M, retorna o plano final

# /ultrareview [PR] — code review multi-agente em cloud sandbox
/ultrareview 1234
# → 3-5 agentes especializados (security, performance, style, tests)
#   analisam em paralelo e consolidam em 1 review

# /autofix-pr [prompt] — spawn web session que assiste o PR + pushes fixes
/autofix-pr "aplique sugestões de review e corrija CI até passar"

# --effort — controla profundidade de raciocínio (Opus 4.7 suporta max)
claude -p "..." --effort max            # raciocínio máximo (mais caro, melhor)
claude -p "..." --effort xhigh          # quase-máximo
claude -p "..." --effort low            # rápido e barato

# --max-budget-usd — para automaticamente quando custo atinge limite
claude -p "migrar arquitetura" --max-budget-usd 5.00

# --fork-session — usa com --resume: cria novo session-id (não sobrescreve)
claude --resume "migration-v2" --fork-session
# Útil para experimentar sem destruir a sessão original

# --bare — pula discovery de hooks/skills/plugins/MCP/CLAUDE.md (boot rápido)
claude --bare "pergunta simples sem contexto de projeto"
# 10x mais rápido pra queries one-shot em repos grandes

# --from-pr <num> — retoma sessões linkadas a um PR específico
claude --from-pr 123

# --worktree <nome> — isolamento automático em git worktree
claude --worktree feature-auth --tmux   # cria branch + dir + tmux session

# --agents — define subagents via JSON inline (override de config)
claude --agents '{"reviewer":{"prompt":"Foque em segurança"}}'

# --fallback-model — se modelo padrão estiver sobrecarregado (modo print)
claude -p "..." --model opus --fallback-model sonnet

# --json-schema — saída estruturada validada (modo print)
claude -p "extraia nome e email deste texto" \
  --json-schema '{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}}'

# --teleport — puxa uma sessão web de volta pro terminal local
claude --teleport

# Variáveis de ambiente importantes:
export CLAUDE_CODE_EFFORT_LEVEL=high    # default de effort
export CLAUDE_CODE_USE_BEDROCK=1        # roda via Amazon Bedrock
export CLAUDE_CODE_USE_VERTEX=1         # roda via Google Vertex AI
export MAX_THINKING_TOKENS=10000        # limite de thinking (legacy models)
export CLAUDE_CODE_NO_FLICKER=1         # rendering smooth em terminais problematic