> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Slash Commands no SDK

> Aprenda como usar slash commands para controlar sessões do Claude Code através do SDK

Slash commands fornecem uma maneira de controlar sessões do Claude Code com comandos especiais que começam com `/`. Esses comandos podem ser enviados através do SDK para executar ações como compactar contexto, listar uso de contexto ou invocar comandos personalizados. Apenas comandos que funcionam sem um terminal interativo são despachados através do SDK; a mensagem `system/init` lista os disponíveis em sua sessão.

<h2 id="discovering-available-slash-commands">
  Descobrindo Slash Commands Disponíveis
</h2>

O Claude Agent SDK fornece informações sobre slash commands disponíveis na mensagem de inicialização do sistema. Acesse essas informações quando sua sessão começar:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { query } from "@anthropic-ai/claude-agent-sdk";

  for await (const message of query({
    prompt: "Hello Claude",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      console.log("Available slash commands:", message.slash_commands);
      // Inclui comandos integrados mais skills agrupados, por exemplo:
      // ["clear", "compact", "context", "usage", "code-review", "verify", ...]
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage


  async def main():
      async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
          if isinstance(message, SystemMessage) and message.subtype == "init":
              print("Available slash commands:", message.data["slash_commands"])
              # Inclui comandos integrados mais skills agrupados, por exemplo:
              # ["clear", "compact", "context", "usage", "code-review", "verify", ...]


  asyncio.run(main())
  ```
</CodeGroup>

<h2 id="sending-slash-commands">
  Enviando Slash Commands
</h2>

Envie slash commands incluindo-os em sua string de prompt, assim como texto regular. Comandos que atuam no histórico de conversas, como `/compact`, precisam de mensagens anteriores para funcionar, então os exemplos abaixo fazem uma pergunta primeiro e depois enviam o comando como um acompanhamento para a mesma conversa:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { query } from "@anthropic-ai/claude-agent-sdk";

  // Construir histórico de conversa primeiro
  try {
    for await (const message of query({
      prompt: "What does the README in this directory cover?",
      options: { maxTurns: 2 }
    })) {
      if (message.type === "result" && message.subtype === "success") {
        console.log(message.result);
      }
    }
  } catch (error) {
    // Uma query() de um único disparo lança após produzir um resultado de erro,
    // então a query de acompanhamento abaixo ainda é executada.
    console.error(`Session ended with an error: ${error}`);
  }

  // Enviar um slash command como acompanhamento para a mesma conversa
  for await (const message of query({
    prompt: "/compact",
    options: { continue: true, maxTurns: 1 }
  })) {
    if (message.type === "result") {
      console.log("Command executed, result subtype:", message.subtype);
      // Exemplo de saída: Command executed, result subtype: success
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


  async def main():
      # Construir histórico de conversa primeiro
      try:
          async for message in query(
              prompt="What does the README in this directory cover?",
              options=ClaudeAgentOptions(max_turns=2),
          ):
              if isinstance(message, ResultMessage) and message.subtype == "success":
                  print(message.result)
      except Exception as error:
          # Uma query() de um único disparo lança após produzir um resultado de erro,
          # então a query de acompanhamento abaixo ainda é executada.
          print(f"Session ended with an error: {error}")

      # Enviar um slash command como acompanhamento para a mesma conversa
      async for message in query(
          prompt="/compact",
          options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
      ):
          if isinstance(message, ResultMessage):
              print("Command executed, result subtype:", message.subtype)
              # Exemplo de saída: Command executed, result subtype: success


  asyncio.run(main())
  ```
</CodeGroup>

<Note>
  Uma query pode terminar com um resultado de erro, por exemplo quando o limite `maxTurns` / `max_turns` é atingido antes do trabalho ser concluído. A mensagem de resultado final então tem `is_error: true` e um subtipo de erro como `error_max_turns` em vez de `success`.

  Após produzir essa mensagem de resultado final, o SDK lança um erro, porque o processo CLI sai com um código diferente de zero.

  Envolva o loop em um `try`/`catch` em TypeScript ou `try`/`except` em Python se seu comando puder atingir o limite, como mostrado em [Single Message Input](/pt/agent-sdk/streaming-vs-single-mode#single-message-input), ou defina `maxTurns` alto o suficiente para o trabalho ser concluído. Em Python, capture `Exception`: o SDK apresenta resultados de erro como uma `Exception` simples.
</Note>

<h2 id="common-slash-commands">
  Slash Commands Comuns
</h2>

<h3 id="/compact-compact-conversation-history">
  `/compact` - Compactar histórico de conversa
</h3>

O comando `/compact` reduz o tamanho do seu histórico de conversa resumindo mensagens antigas enquanto preserva contexto importante. A compactação precisa de uma conversa existente com pelo menos duas trocas anteriores para resumir. Este exemplo tem uma conversa primeiro, depois a compacta e lê a mensagem do sistema `compact_boundary` que relata o resultado:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { query } from "@anthropic-ai/claude-agent-sdk";

  // Compaction needs existing history, so have a conversation first
  try {
    for await (const message of query({
      prompt: "Explain what this project does",
      options: { maxTurns: 2 }
    })) {
      if (message.type === "result" && message.subtype === "success") {
        console.log(message.result);
      }
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result,
    // so the follow-up query below still runs.
    console.error(`Session ended with an error: ${error}`);
  }

  // Compact the same conversation
  for await (const message of query({
    prompt: "/compact",
    options: { continue: true, maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "compact_boundary") {
      console.log("Compaction completed");
      console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
      console.log("Trigger:", message.compact_metadata.trigger);
      // Example output:
      // Compaction completed
      // Pre-compaction tokens: 1842
      // Trigger: manual
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage


  async def main():
      # Compaction needs existing history, so have a conversation first
      try:
          async for message in query(
              prompt="Explain what this project does",
              options=ClaudeAgentOptions(max_turns=2),
          ):
              if isinstance(message, ResultMessage) and message.subtype == "success":
                  print(message.result)
      except Exception as error:
          # A single-shot query() raises after yielding an error result,
          # so the follow-up query below still runs.
          print(f"Session ended with an error: {error}")

      # Compact the same conversation
      async for message in query(
          prompt="/compact",
          options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
      ):
          if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
              print("Compaction completed")
              print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
              print("Trigger:", message.data["compact_metadata"]["trigger"])
              # Example output:
              # Compaction completed
              # Pre-compaction tokens: 1842
              # Trigger: manual


  asyncio.run(main())
  ```
</CodeGroup>

<Note>
  Uma mensagem `compact_boundary` só chega quando a compactação foi executada. Sem nada para resumir, `/compact` relata o motivo em vez de gerar um erro: a execução ainda termina com um resultado `success`, nenhuma mensagem `compact_boundary` é emitida, e o texto do resultado carrega a mensagem, por exemplo `Not enough messages to compact.` após uma única troca curta. Uma chamada `query()` única e nova começa com contexto vazio, então use este padrão em uma sessão com turnos anteriores, por exemplo no [modo de entrada em streaming](/pt/agent-sdk/streaming-vs-single-mode) ou ao retomar uma sessão.
</Note>

<h3 id="/clear-reset-conversation-context">
  `/clear` - Redefinir contexto de conversa
</h3>

O comando `/clear` redefine a conversa para um contexto vazio, para que os prompts subsequentes comecem sem nenhum histórico de conversa anterior. A conversa anterior permanece no disco e pode ser retomada passando seu ID de sessão para a [opção `resume`](/pt/agent-sdk/sessions#resume-by-id).

Isso é útil no [modo de entrada em streaming](/pt/agent-sdk/streaming-vs-single-mode), onde você envia múltiplos prompts em uma única conexão. Para chamadas `query()` únicas, cada chamada já começa com contexto vazio, então enviar `/clear` não tem efeito prático; inicie uma nova `query()` em vez disso.

<Note>
  `/clear` no SDK requer Claude Code v2.1.117 ou posterior. Em versões anteriores, ele é omitido de `slash_commands`.
</Note>

<h2 id="creating-custom-slash-commands">
  Criando Slash Commands Personalizados
</h2>

Além de usar slash commands integrados, você pode criar seus próprios comandos personalizados que estão disponíveis através do SDK. Comandos personalizados são definidos como arquivos markdown em diretórios específicos, similar a como subagentes são configurados.

<Note>
  O diretório `.claude/commands/` é o formato legado. O formato recomendado é `.claude/skills/<name>/SKILL.md`, que suporta a mesma invocação de slash command (`/name`) mais invocação autônoma pelo Claude. Veja [Skills](/pt/agent-sdk/skills) para o formato atual. O CLI continua suportando ambos os formatos, e os exemplos abaixo permanecem precisos para `.claude/commands/`.
</Note>

<h3 id="file-locations">
  Localizações de Arquivo
</h3>

Slash commands personalizados são armazenados em diretórios designados baseado em seu escopo:

* **Comandos de projeto**: `.claude/commands/` - Disponíveis apenas no projeto atual (legado; prefira `.claude/skills/`)
* **Comandos pessoais**: `~/.claude/commands/` - Disponíveis em todos seus projetos (legado; prefira `~/.claude/skills/`)

<h3 id="file-format">
  Formato de Arquivo
</h3>

Cada comando personalizado é um arquivo markdown onde:

* O nome do arquivo (sem extensão `.md`) se torna o nome do comando
* O conteúdo do arquivo define o que o comando faz
* Frontmatter YAML opcional fornece configuração

<h4 id="basic-example">
  Exemplo Básico
</h4>

Crie o diretório `.claude/commands` em seu projeto se ele não existir, então crie `.claude/commands/refactor.md`:

```markdown theme={null}
Refactor the selected code to improve readability and maintainability.
Focus on clean code principles and best practices.
```

Isso cria o comando `/refactor` que você pode usar através do SDK.

<h4 id="with-frontmatter">
  Com Frontmatter
</h4>

Crie `.claude/commands/security-check.md`:

```markdown theme={null}
---
allowed-tools: Read, Grep, Glob
description: Run security vulnerability scan
model: claude-opus-4-8
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations
```

<h3 id="using-custom-commands-in-the-sdk">
  Usando Slash Commands Personalizados no SDK
</h3>

Uma vez definidos no sistema de arquivos, comandos personalizados estão automaticamente disponíveis através do SDK:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { query } from "@anthropic-ai/claude-agent-sdk";

  // Use a custom command
  try {
    for await (const message of query({
      prompt: "/refactor src/auth/login.ts",
      options: { maxTurns: 3 }
    })) {
      if (message.type === "assistant") {
        console.log("Refactoring suggestions:", message.message);
      }
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result,
    // so the second query below still runs.
    console.error(`Session ended with an error: ${error}`);
  }

  // Custom commands appear in the slash_commands list
  for await (const message of query({
    prompt: "Hello",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      console.log("Available commands:", message.slash_commands);
      // Includes built-in commands plus bundled skills and your custom commands, for example:
      // ["clear", "compact", "context", "usage", "code-review", "verify", "refactor", "security-check", ...]
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, SystemMessage


  async def main():
      # Use a custom command
      try:
          async for message in query(
              prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3)
          ):
              if isinstance(message, AssistantMessage):
                  for block in message.content:
                      if hasattr(block, "text"):
                          print("Refactoring suggestions:", block.text)
      except Exception as error:
          # A single-shot query() raises after yielding an error result,
          # so the second query below still runs.
          print(f"Session ended with an error: {error}")

      # Custom commands appear in the slash_commands list
      async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)):
          if isinstance(message, SystemMessage) and message.subtype == "init":
              print("Available commands:", message.data["slash_commands"])
              # Includes built-in commands plus bundled skills and your custom commands, for example:
              # ["clear", "compact", "context", "usage", "code-review", "verify", "refactor", "security-check", ...]


  asyncio.run(main())
  ```
</CodeGroup>

<h3 id="advanced-features">
  Recursos Avançados
</h3>

<h4 id="arguments-and-placeholders">
  Argumentos e Placeholders
</h4>

Comandos personalizados suportam argumentos dinâmicos usando placeholders:

Crie `.claude/commands/fix-issue.md`:

```markdown theme={null}
---
argument-hint: [issue-number] [priority]
description: Fix a GitHub issue
---

Fix issue #$0 with priority $1.
Check the issue description and implement the necessary changes.
```

Use no SDK:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { query } from "@anthropic-ai/claude-agent-sdk";

  // Pass arguments to custom command
  for await (const message of query({
    prompt: "/fix-issue 123 high",
    options: { maxTurns: 5 }
  })) {
    // Command will process with $0="123" and $1="high"
    if (message.type === "result" && message.subtype === "success") {
      console.log("Issue fixed:", message.result);
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


  async def main():
      # Pass arguments to custom command
      async for message in query(prompt="/fix-issue 123 high", options=ClaudeAgentOptions(max_turns=5)):
          # Command will process with $0="123" and $1="high"
          if isinstance(message, ResultMessage):
              print("Issue fixed:", message.result)


  asyncio.run(main())
  ```
</CodeGroup>

<h4 id="bash-command-execution">
  Execução de Comando Bash
</h4>

Comandos personalizados podem executar comandos bash e incluir sua saída:

Crie `.claude/commands/git-commit.md`:

```markdown theme={null}
---
allowed-tools: Bash(git add *), Bash(git status *), Bash(git commit *)
description: Create a git commit
---

## Context

- Current status: !`git status`
- Current diff: !`git diff HEAD`

## Task

Create a git commit with appropriate message based on the changes.
```

<h4 id="file-references">
  Referências de Arquivo
</h4>

Inclua conteúdos de arquivo usando o prefixo `@`:

Crie `.claude/commands/review-config.md`:

```markdown theme={null}
---
description: Review configuration files
---

Review the following configuration files for issues:
- Package config: @package.json
- TypeScript config: @tsconfig.json
- Environment config: @.env

Check for security issues, outdated dependencies, and misconfigurations.
```

<h3 id="organization-with-namespacing">
  Organização com Namespacing
</h3>

Organize comandos em subdiretórios para melhor estrutura:

```bash theme={null}
.claude/commands/
├── frontend/
│   ├── component.md      # Creates /component (project:frontend)
│   └── style-check.md     # Creates /style-check (project:frontend)
├── backend/
│   ├── api-test.md        # Creates /api-test (project:backend)
│   └── db-migrate.md      # Creates /db-migrate (project:backend)
└── review.md              # Creates /review (project)
```

O subdiretório aparece na descrição do comando mas não afeta o nome do comando em si.

<h3 id="practical-examples">
  Exemplos Práticos
</h3>

<h4 id="pull-request-review-command">
  Comando de Revisão de Pull Request
</h4>

Crie `.claude/commands/review-pr.md`:

```markdown theme={null}
---
allowed-tools: Read, Grep, Glob, Bash(git diff *)
description: Comprehensive code review
---

## Changed Files
!`git diff --name-only HEAD~1`

## Detailed Changes
!`git diff HEAD~1`

## Review Checklist

Review the above changes for:
1. Code quality and readability
2. Security vulnerabilities
3. Performance implications
4. Test coverage
5. Documentation completeness

Provide specific, actionable feedback organized by priority.
```

<Note>
  Claude Code inclui skills `code-review` e `verify` agrupados. Se você nomear um comando personalizado após um deles, por exemplo `.claude/commands/code-review.md`, seu comando sobrescreve o skill agrupado e `slash_commands` lista o nome uma vez.
</Note>

<h4 id="test-runner-command">
  Comando Test Runner
</h4>

Crie `.claude/commands/test.md`:

```markdown theme={null}
---
allowed-tools: Bash, Read, Edit
argument-hint: [test-pattern]
description: Run tests with optional pattern
---

Run tests matching pattern: $ARGUMENTS

1. Detect the test framework (Jest, pytest, etc.)
2. Run tests with the provided pattern
3. If tests fail, analyze and fix them
4. Re-run to verify fixes
```

Use esses comandos através do SDK:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { query } from "@anthropic-ai/claude-agent-sdk";

  // Run code review
  try {
    for await (const message of query({
      prompt: "/review-pr",
      options: { maxTurns: 3 }
    })) {
      // Process review feedback
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result,
    // so the second query below still runs.
    console.error(`Session ended with an error: ${error}`);
  }

  // Run specific tests
  for await (const message of query({
    prompt: "/test auth",
    options: { maxTurns: 5 }
  })) {
    // Handle test results
  }
  ```

  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import query, ClaudeAgentOptions


  async def main():
      # Run code review
      try:
          async for message in query(prompt="/review-pr", options=ClaudeAgentOptions(max_turns=3)):
              # Process review feedback
              pass
      except Exception as error:
          # A single-shot query() raises after yielding an error result,
          # so the second query below still runs.
          print(f"Session ended with an error: {error}")

      # Run specific tests
      async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)):
          # Handle test results
          pass


  asyncio.run(main())
  ```
</CodeGroup>

<h2 id="see-also">
  Veja Também
</h2>

* [Slash Commands](/pt/skills) - Documentação completa de slash commands
* [Subagentes no SDK](/pt/agent-sdk/subagents) - Configuração similar baseada em sistema de arquivos para subagentes
* [Referência TypeScript SDK](/pt/agent-sdk/typescript) - Documentação completa da API
* [Visão geral do SDK](/pt/agent-sdk/overview) - Conceitos gerais do SDK
* [Referência CLI](/pt/cli-reference) - Interface de linha de comando