O Claude pode usar uma ferramenta de editor de texto definida pela Anthropic para visualizar e modificar arquivos de texto, ajudando você a depurar, corrigir e melhorar seu código ou outros documentos de texto. Isso permite que o Claude interaja diretamente com seus arquivos, fornecendo assistência prática em vez de apenas sugerir mudanças.

Antes de usar a ferramenta de editor de texto

Use um modelo compatível

A ferramenta de editor de texto da Anthropic está disponível para vários modelos Claude:

  • Claude 4 Opus & Sonnet: text_editor_20250429
  • Claude Sonnet 3.7: text_editor_20250124
  • Claude Sonnet 3.5: text_editor_20241022

A versão mais recente text_editor_20250429 para modelos Claude 4 não inclui o comando undo_edit. Se você precisar dessa funcionalidade, precisará usar o Claude 3.7 ou Sonnet 3.5 com suas respectivas versões de ferramentas.

Avalie a adequação ao seu caso de uso

Alguns exemplos de quando usar a ferramenta de editor de texto são:

  • Depuração de código: Peça ao Claude para identificar e corrigir bugs em seu código, desde erros de sintaxe até problemas de lógica.
  • Refatoração de código: Deixe o Claude melhorar a estrutura, legibilidade e desempenho do seu código através de edições direcionadas.
  • Geração de documentação: Peça ao Claude para adicionar docstrings, comentários ou arquivos README ao seu código.
  • Criação de testes: Peça ao Claude para criar testes unitários para seu código com base em seu entendimento da implementação.

Use a ferramenta de editor de texto

Forneça a ferramenta de editor de texto (chamada str_replace_based_edit_tool) ao Claude usando a API Messages:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        {
            "role": "user", 
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?"
        }
    ]
)

A ferramenta de editor de texto pode ser usada da seguinte maneira:

1

Forneça ao Claude a ferramenta de editor de texto e um prompt do usuário

  • Inclua a ferramenta de editor de texto em sua solicitação de API
  • Forneça um prompt do usuário que possa exigir examinar ou modificar arquivos, como “Você pode corrigir o erro de sintaxe no meu código?”
2

Claude usa a ferramenta para examinar arquivos ou diretórios

  • Claude avalia o que precisa examinar e usa o comando view para examinar o conteúdo do arquivo ou listar o conteúdo do diretório
  • A resposta da API conterá um bloco de conteúdo tool_use com o comando view
3

Execute o comando view e retorne os resultados

  • Extraia o caminho do arquivo ou diretório da solicitação de uso da ferramenta do Claude
  • Leia o conteúdo do arquivo ou liste o conteúdo do diretório e retorne-os ao Claude
  • Retorne os resultados ao Claude continuando a conversa com uma nova mensagem user contendo um bloco de conteúdo tool_result
4

Claude usa a ferramenta para modificar arquivos

  • Após examinar o arquivo ou diretório, Claude pode usar um comando como str_replace para fazer alterações ou insert para adicionar texto em um número de linha específico.
  • Se Claude usar o comando str_replace, ele construirá uma solicitação de uso da ferramenta formatada corretamente com o texto antigo e o novo texto para substituí-lo
5

Execute a edição e retorne os resultados

  • Extraia o caminho do arquivo, o texto antigo e o novo texto da solicitação de uso da ferramenta do Claude
  • Realize a substituição de texto no arquivo
  • Retorne os resultados ao Claude
6

Claude fornece sua análise e explicação

  • Após examinar e possivelmente editar os arquivos, Claude fornece uma explicação completa do que encontrou e quais alterações fez

Comandos da ferramenta de editor de texto

A ferramenta de editor de texto suporta vários comandos para visualizar e modificar arquivos:

view

O comando view permite que o Claude examine o conteúdo de um arquivo ou liste o conteúdo de um diretório. Ele pode ler o arquivo inteiro ou um intervalo específico de linhas.

Parâmetros:

  • command: Deve ser “view”
  • path: O caminho para o arquivo ou diretório a ser visualizado
  • view_range (opcional): Uma matriz de dois inteiros especificando os números das linhas inicial e final a serem visualizadas. Os números de linha começam em 1, e -1 para a linha final significa ler até o final do arquivo. Este parâmetro se aplica apenas ao visualizar arquivos, não diretórios.

str_replace

O comando str_replace permite que o Claude substitua uma string específica em um arquivo por uma nova string. Isso é usado para fazer edições precisas.

Parâmetros:

  • command: Deve ser “str_replace”
  • path: O caminho para o arquivo a ser modificado
  • old_str: O texto a ser substituído (deve corresponder exatamente, incluindo espaços em branco e indentação)
  • new_str: O novo texto a ser inserido no lugar do texto antigo

create

O comando create permite que o Claude crie um novo arquivo com conteúdo especificado.

Parâmetros:

  • command: Deve ser “create”
  • path: O caminho onde o novo arquivo deve ser criado
  • file_text: O conteúdo a ser escrito no novo arquivo

insert

O comando insert permite que o Claude insira texto em um local específico em um arquivo.

Parâmetros:

  • command: Deve ser “insert”
  • path: O caminho para o arquivo a ser modificado
  • insert_line: O número da linha após a qual inserir o texto (0 para o início do arquivo)
  • new_str: O texto a ser inserido

undo_edit

O comando undo_edit permite que o Claude reverta a última edição feita em um arquivo.

Este comando está disponível apenas no Claude Sonnet 3.7 e Claude Sonnet 3.5. Ele não é suportado nos modelos Claude 4 usando o text_editor_20250429.

Parâmetros:

  • command: Deve ser “undo_edit”
  • path: O caminho para o arquivo cuja última edição deve ser desfeita

Exemplo: Corrigindo um erro de sintaxe com a ferramenta de editor de texto

Este exemplo demonstra como o Claude 4 usa a ferramenta de editor de texto para corrigir um erro de sintaxe em um arquivo Python.

Primeiro, seu aplicativo fornece ao Claude a ferramenta de editor de texto e um prompt para corrigir um erro de sintaxe:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        {
            "role": "user", 
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?"
        }
    ]
)

print(response)

Números de linha

No exemplo acima, o resultado da ferramenta view inclui conteúdo de arquivo com números de linha prefixados em cada linha (por exemplo, “1: def is_prime(n):”). Os números de linha não são obrigatórios, mas são essenciais para usar com sucesso o parâmetro view_range para examinar seções específicas de arquivos e o parâmetro insert_line para adicionar conteúdo em locais precisos.

O Claude usará a ferramenta de editor de texto primeiro para visualizar o arquivo:

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

Seu aplicativo deve então ler o arquivo e retornar seu conteúdo ao Claude:

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        # Previous messages...
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "name": "str_replace_based_edit_tool",
                    "input": {
                        "command": "view",
                        "path": "primes.py"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "content": "1: def is_prime(n):\n2:     \"\"\"Check if a number is prime.\"\"\"\n3:     if n <= 1:\n4:         return False\n5:     if n <= 3:\n6:         return True\n7:     if n % 2 == 0 or n % 3 == 0:\n8:         return False\n9:     i = 5\n10:     while i * i <= n:\n11:         if n % i == 0 or n % (i + 2) == 0:\n12:             return False\n13:         i += 6\n14:     return True\n15: \n16: def get_primes(limit):\n17:     \"\"\"Generate a list of prime numbers up to the given limit.\"\"\"\n18:     primes = []\n19:     for num in range(2, limit + 1)\n20:         if is_prime(num):\n21:             primes.append(num)\n22:     return primes\n23: \n24: def main():\n25:     \"\"\"Main function to demonstrate prime number generation.\"\"\"\n26:     limit = 100\n27:     prime_list = get_primes(limit)\n28:     print(f\"Prime numbers up to {limit}:\")\n29:     print(prime_list)\n30:     print(f\"Found {len(prime_list)} prime numbers.\")\n31: \n32: if __name__ == \"__main__\":\n33:     main()"
                }
            ]
        }
    ]
)

O Claude identificará o erro de sintaxe e usará o comando str_replace para corrigi-lo:

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "str_replace",
        "path": "primes.py",
        "old_str": "    for num in range(2, limit + 1)",
        "new_str": "    for num in range(2, limit + 1):"
      }
    }
  ]
}

Seu aplicativo deve então fazer a edição e retornar o resultado:

response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250429",
            "name": "str_replace_based_edit_tool"
        }
    ],
    messages=[
        # Previous messages...
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "name": "str_replace_based_edit_tool",
                    "input": {
                        "command": "str_replace",
                        "path": "primes.py",
                        "old_str": "    for num in range(2, limit + 1)",
                        "new_str": "    for num in range(2, limit + 1):"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "content": "Successfully replaced text at exactly one location."
                }
            ]
        }
    ]
)

Finalmente, o Claude fornecerá uma explicação completa da correção:

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit."
    }
  ]
}

Implementar a ferramenta de editor de texto

A ferramenta de editor de texto é implementada como uma ferramenta sem esquema. Ao usar esta ferramenta, você não precisa fornecer um esquema de entrada como com outras ferramentas; o esquema está incorporado no modelo do Claude e não pode ser modificado.

O tipo de ferramenta depende da versão do modelo:

  • Claude 4: type: "text_editor_20250429"
  • Claude Sonnet 3.7: type: "text_editor_20250124"
  • Claude Sonnet 3.5: type: "text_editor_20241022"
1

Inicialize sua implementação do editor

Crie funções auxiliares para lidar com operações de arquivo como leitura, escrita e modificação de arquivos. Considere implementar funcionalidade de backup para recuperar de erros.

2

Manipule chamadas de ferramenta do editor

Crie uma função que processa chamadas de ferramenta do Claude com base no tipo de comando:

def handle_editor_tool(tool_call, model_version):
    input_params = tool_call.input
    command = input_params.get('command', '')
    file_path = input_params.get('path', '')
    
    if command == 'view':
        # Ler e retornar conteúdo do arquivo
        pass
    elif command == 'str_replace':
        # Substituir texto no arquivo
        pass
    elif command == 'create':
        # Criar novo arquivo
        pass
    elif command == 'insert':
        # Inserir texto na localização
        pass
    elif command == 'undo_edit':
        # Verificar se é um modelo Claude 4
        if 'str_replace_based_edit_tool' in model_version:
            return {"error": "undo_edit command is not supported in Claude 4"}
        # Restaurar do backup para Claude 3.7/3.5
        pass
3

Implemente medidas de segurança

Adicione validação e verificações de segurança:

  • Valide caminhos de arquivo para evitar travessia de diretório
  • Crie backups antes de fazer alterações
  • Trate erros com elegância
  • Implemente verificações de permissões
4

Processe as respostas do Claude

Extraia e manipule chamadas de ferramenta das respostas do Claude:

# Processe o uso de ferramenta na resposta do Claude
for content in response.content:
    if content.type == "tool_use":
        # Execute a ferramenta com base no comando
        result = handle_editor_tool(content)
        
        # Retorne o resultado ao Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

Ao implementar a ferramenta de editor de texto, tenha em mente:

  1. Segurança: A ferramenta tem acesso ao seu sistema de arquivos local, então implemente medidas de segurança adequadas.
  2. Backup: Sempre crie backups antes de permitir edições em arquivos importantes.
  3. Validação: Valide todas as entradas para evitar alterações não intencionais.
  4. Correspondência única: Certifique-se de que as substituições correspondam exatamente a um local para evitar edições não intencionais.

Lidar com erros

Ao usar a ferramenta de editor de texto, vários erros podem ocorrer. Aqui está uma orientação sobre como lidar com eles:

Siga as melhores práticas de implementação


Preços e uso de tokens

A ferramenta de editor de texto usa a mesma estrutura de preços que outras ferramentas usadas com o Claude. Ela segue o preço padrão de tokens de entrada e saída com base no modelo Claude que você está usando.

Além dos tokens base, os seguintes tokens de entrada adicionais são necessários para a ferramenta de editor de texto:

FerramentaTokens de entrada adicionais
text_editor_20250429 (Claude 4)700 tokens
text_editor_20250124 (Claude Sonnet 3.7)700 tokens
text_editor_20241022 (Claude Sonnet 3.5)700 tokens

Para informações mais detalhadas sobre preços de ferramentas, consulte Preços de uso de ferramentas.

Integre a ferramenta de editor de texto com o uso do computador

A ferramenta de editor de texto pode ser usada junto com a ferramenta de uso do computador e outras ferramentas definidas pela Anthropic. Ao combinar essas ferramentas, você precisará:

  1. Incluir o cabeçalho beta apropriado (se estiver usando com uso do computador)
  2. Combinar a versão da ferramenta com o modelo que você está usando
  3. Considerar o uso adicional de tokens para todas as ferramentas incluídas em sua solicitação

Para mais informações sobre o uso da ferramenta de editor de texto em um contexto de uso do computador, consulte Uso do computador.

Registro de alterações

DataVersãoAlterações
29 de abril de 2025text_editor_20250429Lançamento da ferramenta de editor de texto para Claude 4. Esta versão remove o comando undo_edit, mas mantém todas as outras capacidades. O nome da ferramenta foi atualizado para refletir sua arquitetura baseada em str_replace.
13 de março de 2025text_editor_20250124Introdução da documentação independente da ferramenta de editor de texto. Esta versão é otimizada para Claude Sonnet 3.7, mas tem capacidades idênticas à versão anterior.
22 de outubro de 2024text_editor_20241022Lançamento inicial da ferramenta de editor de texto com Claude Sonnet 3.5. Fornece capacidades para visualizar, criar e editar arquivos através dos comandos view, create, str_replace, insert e undo_edit.

Próximos passos

Aqui estão algumas ideias de como usar a ferramenta de editor de texto de maneiras mais convenientes e poderosas:

  • Integre com seu fluxo de trabalho de desenvolvimento: Incorpore a ferramenta de editor de texto em suas ferramentas de desenvolvimento ou IDE
  • Crie um sistema de revisão de código: Peça ao Claude para revisar seu código e fazer melhorias
  • Construa um assistente de depuração: Crie um sistema onde o Claude possa ajudá-lo a diagnosticar e corrigir problemas em seu código
  • Implemente conversão de formato de arquivo: Deixe o Claude ajudá-lo a converter arquivos de um formato para outro
  • Automatize a documentação: Configure fluxos de trabalho para que o Claude documente automaticamente seu código

À medida que você constrói aplicativos com a ferramenta de editor de texto, estamos ansiosos para ver como você aproveita as capacidades do Claude para melhorar seu fluxo de trabalho de desenvolvimento e produtividade.