Ferramenta de editor de texto

O Claude pode usar uma ferramenta de editor de texto com esquema da 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 alterações.

Para suporte de modelos, consulte a Referência de ferramentas.

Quando usar a ferramenta de editor de texto

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 no seu código, desde erros de sintaxe até problemas de lógica.
• Refatoração de código: Deixe o Claude melhorar a estrutura, a legibilidade e o desempenho do seu código por meio de edições direcionadas.
• Geração de documentação: Peça ao Claude para adicionar docstrings, comentários ou arquivos README à sua base de código.
• Criação de testes: Peça ao Claude para criar testes unitários para o seu código com base na análise 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 Messages API.

Opcionalmente, você pode especificar um parâmetro max_characters para controlar o truncamento ao visualizar arquivos grandes.

client = anthropic.Anthropic()

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

print(response)

Use a ferramenta de editor de texto da seguinte forma:

1. 1

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

   • Inclua a ferramenta de editor de texto na sua requisição à 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. 2

   O Claude usa a ferramenta para examinar arquivos ou diretórios

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

   Execute o comando view e retorne os resultados

   • Extraia o caminho do arquivo ou diretório da requisição de uso de ferramentas do Claude
   • Leia o conteúdo do arquivo ou liste o conteúdo do diretório
   • Se um parâmetro max_characters foi especificado na configuração da ferramenta, trunque o conteúdo do arquivo para esse comprimento
   • Retorne os resultados ao Claude continuando a conversa com uma nova mensagem user contendo um bloco de conteúdo tool_result
4. 4

   O Claude usa a ferramenta para modificar arquivos

   • Após examinar o arquivo ou diretório, o 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 o Claude usar o comando str_replace, ele constrói uma requisição de uso de ferramentas devidamente formatada com o texto antigo e o novo texto pelo qual substituí-lo
5. 5

   Execute a edição e retorne os resultados

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

   O Claude fornece sua análise e explicação

   • Após examinar e possivelmente editar os arquivos, o Claude fornece uma explicação completa do que encontrou e das alterações que 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): Um array de dois inteiros especificando os números das linhas inicial e final a serem visualizadas. Os números de linha são indexados a partir de 1, e -1 para a linha final significa ler até o fim do arquivo. Este parâmetro se aplica apenas ao visualizar arquivos, não diretórios.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "view",
    "path": "primes.py"
  }
}

{
  "type": "tool_use",
  "id": "toolu_02B19r91rw91mr917835mr9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "view",
    "path": "src/"
  }
}

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

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "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):"
  }
}

create

O comando create permite que o Claude crie um novo arquivo com o 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

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "create",
    "path": "test_primes.py",
    "file_text": "import unittest\nimport primes\n\nclass TestPrimes(unittest.TestCase):\n    def test_is_prime(self):\n        self.assertTrue(primes.is_prime(2))\n        self.assertTrue(primes.is_prime(3))\n        self.assertFalse(primes.is_prime(4))\n\nif __name__ == '__main__':\n    unittest.main()"
  }
}

insert

O comando insert permite que o Claude insira texto em um local específico de 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)
• insert_text: O texto a ser inserido

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "insert",
    "path": "primes.py",
    "insert_line": 0,
    "insert_text": "\"\"\"Module for working with prime numbers.\n\nThis module provides functions to check if a number is prime\nand to generate a list of prime numbers up to a given limit.\n\"\"\"\n"
  }
}

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

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

Primeiro, sua aplicação fornece ao Claude a ferramenta de editor de texto e um prompt para corrigir um erro de sintaxe:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "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)

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

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-5",
  "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"
      }
    }
  ]
}

Sua aplicação deve então ler o arquivo e retornar seu conteúdo ao Claude:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "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?",
        },
        {
            "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()',
                }
            ],
        },
    ],
)

print(response)

O Claude identifica o erro de sintaxe e usa o comando str_replace para corrigi-lo:

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-5",
  "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):"
      }
    }
  ]
}

Sua aplicação deve então fazer a edição e retornar o resultado:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        # Mensagens anteriores...
        {
            "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.",
                }
            ],
        },
    ],
)

print(response)

Por fim, o Claude fornece uma explicação completa da correção:

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-5",
  "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."
    }
  ]
}

Implemente 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 em outras ferramentas; o esquema está incorporado ao modelo do Claude e não pode ser modificado.

O tipo da ferramenta é type: "text_editor_20250728" para modelos Claude 4 e posteriores.

1. 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 uma funcionalidade de backup para se recuperar de erros.

2. 2

   Lide com as chamadas da ferramenta de editor

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   def handle_editor_tool(tool_call):
       input_params = tool_call.input
       command = input_params.get("command", "")
       file_path = input_params.get("path", "")
   
       if command == "view":
           # Ler e retornar o 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 posição
           pass

3. 3

   Implemente medidas de segurança

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

   • Valide os caminhos de arquivo para evitar travessia de diretórios
   • Crie backups antes de fazer alterações
   • Lide com erros de forma adequada
   • Implemente verificações de permissões
4. 4

   Processe as respostas do Claude

   Extraia e lide com as chamadas de ferramenta das respostas do Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

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

Lide com erros

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: File not found",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Found 3 matches for replacement text. Please provide more context to make a unique match.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: No match found for replacement. Please check your text and try again.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Permission denied. Cannot write to file.",
      "is_error": true
    }
  ]
}

Siga as melhores práticas de implementação

def backup_file(file_path):
    """Create a backup of a file before editing."""
    backup_path = f"{file_path}.backup"
    if os.path.exists(file_path):
        with open(file_path, "r") as src, open(backup_path, "w") as dst:
            dst.write(src.read())

def safe_replace(file_path, old_text, new_text):
    """Replace text only if there's exactly one match."""
    with open(file_path, "r") as f:
        content = f.read()

    count = content.count(old_text)
    if count == 0:
        return "Error: No match found"
    elif count > 1:
        return f"Error: Found {count} matches"
    else:
        new_content = content.replace(old_text, new_text)
        with open(file_path, "w") as f:
            f.write(new_content)
        return "Successfully replaced text"

def verify_changes(file_path):
    """Run tests or checks after making changes."""
    try:
        # Para arquivos Python, verifique erros de sintaxe
        if file_path.endswith(".py"):
            import ast

            with open(file_path, "r") as f:
                ast.parse(f.read())
            return "Syntax check passed"
    except Exception as e:
        return f"Verification failed: {str(e)}"

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 os preços 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:

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 outras ferramentas

Você pode usar a ferramenta de editor de texto junto com outras ferramentas do Claude. Ao combinar ferramentas, certifique-se de:

• Combinar a versão da ferramenta com o modelo que você está usando
• Considerar o uso adicional de tokens para todas as ferramentas incluídas na sua requisição

Registro de alterações

Próximos passos

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

• Integre ao seu fluxo de trabalho de desenvolvimento: Incorpore a ferramenta de editor de texto às 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 em que o Claude possa ajudar você a diagnosticar e corrigir problemas no seu código
• Implemente conversão de formatos de arquivo: Deixe o Claude ajudar você a converter arquivos de um formato para outro
• Automatize a documentação: Configure fluxos de trabalho para que o Claude documente seu código automaticamente

A ferramenta de editor de texto permite que o Claude trabalhe diretamente com sua base de código, dando suporte a fluxos de trabalho que vão da depuração à documentação automatizada.