Tutorial Claude Opus 4.5: crie um agente de Wiki do GitHub

Repositórios modernos no GitHub muitas vezes não têm documentação clara e estruturada — especialmente as wikis.

Criar essas páginas manualmente pode levar horas lendo código, entendendo a arquitetura e organizando o conteúdo.

Um agente de IA para Wiki do GitHub resolve esse problema.

Neste tutorial, vou te guiar na construção de um GitHub Wiki AI Agent totalmente automatizado — uma ferramenta de linha de comando que usa Claude Opus 4.5 e o Claude Agent SDK para gerar wikis completas de repositórios do GitHub com um único comando. 

Em vez de escrever documentação manualmente, a ferramenta analisa seu código, entende sua estrutura e produz conteúdo limpo para wiki, em várias páginas, que é automaticamente commitado e publicado no seu repositório. 

Tudo roda por uma CLI interativa pensada para ser rápida, inteligente e amigável para desenvolvedores.

Neste guia, vamos seguir um processo simples em três passos para configurar o ambiente, construir o GitHub Wiki AI Agent e testá-lo em repositórios reais:

1. Configurar o ambiente: instalar dependências, instalar e autenticar o Claude Code, configurar tokens do GitHub e ativar o recurso de Wiki.
2. Construir a aplicação: criar a ferramenta de CLI, configurar o Claude Agent, integrar ferramentas MCP do GitHub, adicionar controle de custos e implementar a lógica de geração da wiki (Home, Guia de início, Arquitetura & Ferramentas).
3. Testar o agente: executá-lo em repositórios reais (ECom-Intel e Issue-Analyzer) para verificar o clone, a análise, a criação da wiki e o push automático.

Se você está começando com agentes de IA e quer aprender mais, recomendo conhecer a trilha de habilidades AI Agent Fundamentals. Vale também ler nosso tutorial sobre o Claude Cowork e nosso guia do novo Claude Opus 4.6.

Configurando seu ambiente para o tutorial do GitHub Wiki com Claude Opus 4.5

Antes de construir o GitHub Wiki Agent com o Opus 4.5, garanta que seu ambiente esteja configurado corretamente. Esta seção cobre todos os pré-requisitos e passos de configuração.

1. Pré-requisitos para rodar o Wiki Agent com Claude Opus 4.5

• Python 3.11 ou superior (exigido pelo Python Claude Agent SDK).
• Node.js e npm (necessários para instalar o Claude Code), que é a base da nossa aplicação e oferece agentes, ferramentas e integrações para servidores MCP.

2. Instale e autentique o Claude Code

Abra o terminal (Prompt de Comando, PowerShell ou Terminal do macOS) e rode o comando a seguir para instalar a CLI do Claude Code:

npm install -g @anthropic-ai/claude-code

Digite claude no terminal para iniciar o Claude Code. Depois, dentro do chat do Claude, digite /login para autenticar e acessar o modelo Opus 4.5 e suas ferramentas, como mostrado abaixo.

Você pode aprender mais sobre o Claude Code no nosso tutorial prático. 

3. Gere um GitHub Personal Access Token de escopo refinado

Para gerar um GitHub Personal Access Token com escopo refinado, acesse o GitHub e vá até: 

Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens. 

Crie um novo token e selecione o repositório que você vai usar na seção Repository. Em seguida, configure as permissões. Por segurança, é recomendado definir uma validade curta para o token.

Depois, defina o Personal Access Token como variável de ambiente:

export GITHUB_PAT="your-github-personal-access-token"

4. Inicialize sua Wiki do GitHub

Atualmente, o GitHub não permite criar uma Wiki localmente primeiro.

Portanto, você precisa inicializar a wiki manualmente:

1. Abrindo o seu repositório no GitHub
2. Clicando na aba Wiki
3. Clicando em “Create the first page”
4. Salvando a página (qualquer título funciona)

5. Instale o Claude Agent SDK

Vamos instalar o framework agentic do Claude, que cuida de tudo — do uso de MCP à chamada de ferramentas, criação de arquivos e push das mudanças para o remoto.

pip install claude-agent-sdk

Construindo o Auto Wiki Agent com Claude Opus 4.5

Agora vamos criar um aplicativo de CLI em Python chamado gh_wiki_cli.py. Esse arquivo vai reunir configurações, agentes, ferramentas, um cliente MCP, prompts de sistema, a própria aplicação de CLI e funções auxiliares. 

Esses componentes garantem que você possa fornecer o link do repositório e que o agente saiba como lidar com ele corretamente para publicar a wiki no GitHub.

1. Imports

Aqui importamos módulos da biblioteca padrão do Python, auxiliares de tipagem e o Claude Agent SDK.

• asyncio para I/O assíncrono (chat + streaming).
• os, sys para variáveis de ambiente e encerramento.
• dataclass para controlar estatísticas.
• Imports do Claude Agent SDK para conversar com o agente + ferramentas MCP.

import asyncio
import os
import sys
from dataclasses import dataclass
from typing import Dict

# --- SDK Imports ---
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    McpSdkServerConfig,
    ResultMessage,
    TextBlock,
    ToolResultBlock,
    ToolUseBlock,
)

2. Prompt de sistema

Este é o “cérebro” do agente. Vamos instruir o modelo Opus 4.5 sobre como se comportar e como usar as ferramentas.

SYSTEM_PROMPT = """
        You are an expert Technical Writer and GitHub Wiki specialist.

        TOOLS
        - Read, Write, Glob, Grep:
        - Use these to inspect files and folders in the project directory (e.g. /tmp/Issue-Analyzer) and in wiki_clone/.
        - Use them to list files, read contents, and search for patterns.
        - Write:
        - Use this ONLY to write or update three wiki pages inside wiki_clone/:
            - wiki_clone/Home.md
            - wiki_clone/Getting-Started.md
            - wiki_clone/Architecture-and-Tools.md
        - Bash:
        - Bash is ONLY allowed for git commands, never for inspection or editing.
        - Allowed commands (with cd wiki_clone/ when needed):
            - git clone <repo>.wiki.git wiki_clone  (if wiki_clone does not already exist)
            - git status
            - git add .
            - git commit -m \"Update wiki\"
            - git push
        - Do NOT use Bash for ls, cat, grep, find, python, or any other way of reading/writing files.

        WORKFLOW
        1. When the user gives a GitHub repo URL:
        - Use Bash to clone the wiki if wiki_clone/ does not already exist:
            git clone <repo>.wiki.git wiki_clone
        2. Use Read/Glob/Grep (and any GitHub MCP tools) to explore the project:
        - Read important files in the project folder (e.g. README, docs/, src/).
        - Use that information to generate documentation.
        3. Use Write to create or update ONLY:
        - wiki_clone/Home.md
        - wiki_clone/Getting-Started.md
        - wiki_clone/Architecture-and-Tools.md
        4. When the wiki pages are ready:
        - Use Bash from wiki_clone/ to:
            git add .
            git commit -m \"Update wiki\"
            git push

        RULES
        - You may READ from the whole project directory and wiki_clone/.
        - You may WRITE only to the three wiki pages inside wiki_clone/.
        - Never use Bash to inspect or edit files; only use it for git commands.
        - Keep documentation clear, concise, and in GitHub Wiki style.
        """

3. Cores na CLI

Isso deixa a saída da CLI mais agradável, mas o script funciona mesmo se o colorama não estiver instalado.

• Tenta usar colorama para texto colorido.
• Se não houver, faz fallback para MockColors para o script rodar (sem cores, sem erro).

try:
    from colorama import Fore, Style, init

    init()
except ImportError:

    class MockColors:
        def __getattr__(self, name):
            return ""

    Fore = Style = MockColors()

4. Acompanhando estatísticas da sessão

Uma dataclass simples para controlar custo, interações e duração.

• total_cost: soma do custo em $ reportado pelo Claude SDK.
• total_turns: quantas consultas você enviou.
• duration_ms: duração acumulada em milissegundos.

@dataclass
class SessionStats:
    total_cost: float = 0.0
    total_turns: int = 0
    duration_ms: int = 0

5. Criando as opções do agente

Em seguida, vamos criar o objeto ClaudeAgentOptions e conectar aos nossos servidores MCP. A função abaixo valida as variáveis de ambiente obrigatórias, configura o servidor MCP do GitHub se estiver disponível e restringe as ferramentas que o agente pode usar.

Restringimos deliberadamente as allowed_tools para que o Opus 4.5 possa: usar Bash para operações com Git, chamar o servidor MCP do GitHub para inspecionar conteúdos do repositório e usar Read/Write (junto com Glob e Grep) para trabalhar e validar arquivos Markdown locais.

def create_agent_options() -> ClaudeAgentOptions:
    """Validates env vars and configures the agent options."""
    anthropic_key = os.getenv("ANTHROPIC_API_KEY")
    github_pat = os.getenv("GITHUB_PAT")

    if not anthropic_key:
        print(
            f"{Fore.RED}Error: ANTHROPIC_API_KEY environment variable is required.{Style.RESET_ALL}"
        )
        sys.exit(1)

    # Configure MCP servers
    mcp_servers: Dict[str, McpSdkServerConfig] = {}
    if github_pat:
        mcp_servers["github"] = {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": {"Authorization": f"Bearer {github_pat}"},
        }

    return ClaudeAgentOptions(
        model="claude-opus-4-5",
        system_prompt=SYSTEM_PROMPT,
        mcp_servers=mcp_servers,
        permission_mode="bypassPermissions",
        allowed_tools=[
            "Read",
            "Write",
            "Glob",
            "Grep",
            "Bash",
            "mcp__github__*",
        ],
    )

6. Processando a resposta em streaming

Esta função escuta o stream e imprime texto, uso de ferramentas e saídas das ferramentas.

• Usa client.receive_response() como stream assíncrono.
• Imprime o texto do assistente conforme chega.
• Quando uma ferramenta é invocada → imprime [Tool Use: ...].
• Quando uma ferramenta retorna saída → trunca e imprime uma prévia curta em uma linha.
• Quando chega uma ResultMessage → atualiza o SessionStats com custo + duração.

async def process_response_stream(client: ClaudeSDKClient, stats: SessionStats):
    """Handles the stream of messages from the agent."""
    async for message in client.receive_response():
        # 1. Handle Assistant Content (Text & Tool Requests)
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="", flush=True)
                elif isinstance(block, ToolUseBlock):
                    print(f"\n{Fore.CYAN}[Tool Use: {block.name}]{Style.RESET_ALL}")

        # 2. Handle Tool Results (Outputs)
        if hasattr(message, "content") and isinstance(message.content, list):
            for block in message.content:
                if isinstance(block, ToolResultBlock):
                    # Truncate output for cleaner CLI
                    raw_output = str(block.content)
                    clean_output = raw_output.replace("\n", " ")
                    short_output = (
                        clean_output[:200] + "..."
                        if len(clean_output) > 200
                        else clean_output
                    )
                    print(
                        f"{Fore.YELLOW}  -> [Output]: {short_output}{Style.RESET_ALL}"
                    )

        # 3. Handle Result Metrics (Cost & Usage)
        if isinstance(message, ResultMessage):
            if message.total_cost_usd:
                stats.total_cost += message.total_cost_usd
            if message.duration_ms:
                stats.duration_ms += message.duration_ms

7. Imprimindo um resumo no final

Estatísticas de fim de sessão para a CLI, mostrando interações, duração e custo em dólares.

• Converte duration_ms para segundos.
• Mostra o custo total com 4 casas decimais.

def print_summary(stats: SessionStats):
    """Prints the final session statistics."""
    print(f"\n\n{Fore.GREEN}=== Session Summary ==={Style.RESET_ALL}")
    print(f"Total Turns:   {stats.total_turns}")
    print(f"Duration:      {stats.duration_ms / 1000:.2f}s")
    print(f"Total Cost:    ${stats.total_cost:.4f}")
    print(f"{Fore.GREEN}======================={Style.RESET_ALL}")

8. Função assíncrona principal

Este é o fluxo de controle central do app: faz a configuração, conecta aos serviços, lê a entrada do usuário e envia consultas. A função chama create_agent_options() e inicializa as estatísticas. Ela imprime um banner de boas-vindas e informa quais servidores MCP estão habilitados. Também cria um ClaudeSDKClient usando um contexto assíncrono.

A aplicação roda um REPL simples (Read-Eval-Print Loop):

1. Digite 'exit' ou 'quit' para sair da aplicação.
2. Cada consulta válida incrementa stats.total_turns em 1.
3. await client.query(user_input) envia a mensagem do usuário.
4. await process_response_stream(...) imprime o resultado em streaming.
5. Quaisquer exceções são capturadas e exibem uma mensagem de erro em vermelho.
6. Por fim, a função sempre chama print_summary(stats).

async def main():
    options = create_agent_options()
    stats = SessionStats()

    # Welcome message
    print(f"{Fore.GREEN}=== GitHub Wiki AI Agent (Auto-Mode) ==={Style.RESET_ALL}")
    print(
        f"MCP Servers: {', '.join(options.mcp_servers.keys()) if options.mcp_servers else 'None'}"
    )
    print("Ask me to help with a GitHub wiki by mentioning the repository URL!")
    print("Type 'exit' to quit.\n")

    async with ClaudeSDKClient(options=options) as client:
        try:
            await client.connect()

            while True:
                try:
                    user_input = input(f"\n{Fore.BLUE}>> {Style.RESET_ALL}").strip()
                except EOFError:
                    break

                if not user_input:
                    continue

                if user_input.lower() in ["exit", "quit"]:
                    break

                stats.total_turns += 1

                # Send query
                await client.query(user_input)
                print()  # Spacer

                # Process response stream using helper function
                await process_response_stream(client, stats)

        except Exception as e:
            print(f"\n{Fore.RED}Session Error: {e}{Style.RESET_ALL}")
        finally:
            print_summary(stats)

9. Ponto de entrada do script

Por fim, definimos o ponto de entrada do script para que a CLI rode quando o arquivo for executado diretamente. O bloco abaixo inicia o loop assíncrono principal e faz o encerramento correto:

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nSession interrupted.")
        sys.exit(0)

Testando o Auto Wiki Agent

Depois de instalar tudo, inicie o app de chat da CLI e verifique se o seu Claude Code CLI está funcionando:

python gh_wiki_cli.py

Agora você pode interagir com o agente como em uma interface de chat. Faça perguntas gerais ou peça diretamente para ele criar a wiki do seu repositório:

create the github wiki for https://github.com/kingabzpro/ECom-Intel

Se o usuário pedir para criar uma wiki, o agente executa automaticamente:

1. Clonagem da wiki: Cria ou reutiliza uma pasta wiki_clone/ e baixa o conteúdo mais recente da wiki.
2. Inspeção do repositório: Lê arquivos-chave do repositório no GitHub usando as ferramentas MCP. 
3. Geração de páginas: Cria e escreve automaticamente páginas como:
• Home.md
• Getting-Started.md
• Architecture-and-Tools.md
4. Commit e push: O agente prepara as novas páginas, faz o commit e envia as atualizações para: <your-repo>.wiki.git
5. Exemplo de saída bem-sucedida: Ao concluir, você verá uma mensagem de confirmação limpa. E a wiki ficará no ar em: https://github.com/kingabzpro/ECom-Intel/wiki

Fiquei realmente impressionado com a forma como o agente reuniu imagens de demonstração, gráficos e outras informações essenciais e montou uma home coerente para a wiki.

A wiki agora inclui um índice decente, explicações sobre o assistente e as ferramentas, além de instruções claras de “primeiros passos”.

No fim da execução, o resumo da sessão mostrou que essa única sessão custou quase 1 USD, o que é caro para gerar uma wiki de três páginas. Se o repositório fosse maior e precisássemos, por exemplo, de uma wiki com 12 páginas, o custo aumentaria bastante.

=== Session Summary ===
Total Turns:   1
Duration:      282.99s
Total Cost:    $0.9047
=======================

No segundo teste, pedi ao agente para criar a wiki de outro repositório:

create the github wiki for https://github.com/kingabzpro/Issue-Analyzer

O resultado foi ainda melhor. A wiki gerada, disponível em https://github.com/kingabzpro/Issue-Analyzer/wiki, agora traz documentação adequada explicando o que o projeto faz e como começar. 

Ela inclui tabelas bem estruturadas, um diagrama de arquitetura e outras seções essenciais que permitem entender o projeto inteiro em cerca de cinco minutos — em vez de passar dias lendo código.

Considerações finais

Quando ouvi pela primeira vez que o Opus 4.5 estava sendo apontado como o melhor modelo do mundo para código e agentes, fiquei realmente empolgado — ainda mais por ter preço semelhante aos modelos Sonnet. 

Porém, o ânimo caiu quando percebi que experimentar e construir uma aplicação pequena acabou custando cerca de US$ 15 em uso de API.

O Opus 4.5 é potente, mas caro. Também tentei reproduzir o mesmo fluxo com Haiku e Sonnet, mas a experiência foi visivelmente inferior para esse tipo de tarefa agentic, com muita documentação. 

Ambos frequentemente voltavam a usar ferramentas Bash, mesmo quando eu pedia explicitamente para usar as ferramentas MCP para leitura de arquivos no GitHub. Além disso, geralmente seguiam caminhos mais longos e menos diretos para resolver os problemas.

Se você prioriza precisão, confiabilidade e geração de código e documentação de alta qualidade, o Opus 4.5 vale a consideração. 

Mas, se o seu caso de uso for menos crítico ou se o custo for um fator decisivo, talvez seja melhor ficar com o Sonnet ou até modelos open source mais baratos. Os custos do Opus 4.5 podem escalar rápido, especialmente em fluxos agentic com várias etapas em repositórios grandes.

Se tiver interesse no projeto, você encontra o código-fonte completo aqui — é só clonar e rodar localmente: kingabzpro/GitHub-Wiki-Agent.

Se você quer continuar criando agentes de IA, recomendo o curso de sistemas multiagentes com LangGraph.