Tutorial su Claude Opus 4.5: crea un agente per la wiki di GitHub

I repository GitHub moderni spesso mancano di una documentazione chiara e strutturata, in particolare delle wiki.

Creare queste pagine manualmente può richiedere ore di lettura del codice, comprensione dell’architettura e organizzazione dei contenuti.

Un GitHub Wiki AI Agent può risolvere questo problema.

In questo tutorial ti guiderò nella creazione di un GitHub Wiki AI Agent completamente automatizzato, uno strumento da riga di comando che usa Claude Opus 4.5 e il Claude Agent SDK per generare wiki completi dei repository GitHub con un’unica istruzione. 

Invece di scrivere la documentazione a mano, questo strumento analizza il tuo codebase, ne comprende la struttura e produce contenuti wiki puliti e multi-pagina che vengono automaticamente aggiunti al commit e pubblicati nel tuo repository. 

Il tutto gira in una CLI interattiva pensata per essere veloce, intelligente e a misura di sviluppatore.

In questa guida seguiremo un semplice processo in tre passaggi per configurare l’ambiente, costruire il GitHub Wiki AI Agent e testarlo su repository reali:

1. Configura l’ambiente: installa le dipendenze, installa e autentica Claude Code, configura i token GitHub e abilita la funzione Wiki.
2. Crea l’applicazione: crea lo strumento CLI, configura il Claude Agent, integra gli strumenti MCP per GitHub, aggiungi il tracking dei costi e implementa la logica di generazione della wiki (Home, Guida introduttiva, Architettura & strumenti).
3. Testa l’agente: eseguilo su repository reali (ECom-Intel e Issue-Analyzer) per verificare clonazione, analisi, creazione della wiki e push automatico.

Se sei alle prime armi con gli agenti AI e vuoi saperne di più, ti consiglio di dare un’occhiata allo skill track AI Agent Fundamentals. Ti consigliamo anche il nostro tutorial su Claude Cowork e la guida al nuovo Claude Opus 4.6.

Configurare l’ambiente per il tutorial su Claude Opus 4.5 e la wiki di GitHub

Prima di costruire il GitHub Wiki Agent con Opus 4.5, assicurati che l’ambiente sia configurato correttamente. Questa sezione ti guida attraverso prerequisiti e passaggi di setup.

1. Prerequisiti per eseguire il Wiki Agent con Claude Opus 4.5

• Python 3.11 o superiore (richiesto dal Python Claude Agent SDK).
• Node.js e npm (necessari per installare Claude Code), l’ossatura della nostra applicazione, che fornisce agenti, strumenti e integrazioni per server MCP.

2. Installa e autentica Claude Code

Apri il terminale (Command Prompt, PowerShell o Terminale su macOS) ed esegui il seguente comando per installare la CLI di Claude Code:

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

Digita claude nel terminale per avviare Claude Code. Poi, dentro la chat di Claude, digita /login per autenticarti e ottenere l’accesso al modello e agli strumenti di Opus 4.5, come mostrato qui sotto.

Puoi saperne di più su Claude Code nel nostro tutorial pratico. 

3. Genera un token di accesso personale GitHub con permessi granulari

Per generare un token di accesso personale GitHub con permessi granulari, vai su GitHub e naviga in: 

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

Crea un nuovo token e seleziona il repository che userai nella sezione Repository. Poi configura i permessi. Per sicurezza, è consigliabile impostare una scadenza breve per il token.

Poi imposta il Personal Access Token come variabile d’ambiente:

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

4. Inizializza la tua wiki di GitHub

Attualmente GitHub non supporta la creazione di una wiki prima in locale.

Quindi devi inizializzare manualmente la wiki:

1. Apri il tuo repository su GitHub
2. Clicca sulla scheda Wiki
3. Clicca “Create the first page”
4. Salva la pagina (va bene qualsiasi titolo)

5. Installa il Claude Agent SDK

Installeremo il framework agentico di Claude che gestisce tutto: dall’uso di MCP all’invocazione degli strumenti, alla creazione di file e al push delle modifiche sul remoto.

pip install claude-agent-sdk

Creare l’Auto Wiki Agent con Claude Opus 4.5

Ora creeremo un’applicazione CLI in Python chiamata gh_wiki_cli.py. Questo file includerà configurazioni, agenti, strumenti, un client MCP, system prompt, l’app CLI stessa e funzioni di supporto. 

Questi componenti faranno in modo che l’utente possa fornire il link al repository e che l’agente sappia come gestirlo correttamente per pubblicare la wiki di GitHub.

1. Import

Questa parte importa moduli della libreria standard di Python, helper per il typing e il Claude Agent SDK.

• asyncio per I/O asincrono (chat + streaming).
• os, sys per variabili d’ambiente e uscita.
• dataclass per tracciare le statistiche.
• Import dal Claude Agent SDK per comunicare con l’agente e gli strumenti 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. System prompt

Questo è il “cervello” dell’agente. Istruiremo il modello Opus 4.5 su come comportarsi e come usare gli strumenti.

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. Gestione dei colori per la CLI

Rende l’output della CLI più gradevole, ma funziona anche se colorama non è installato.

• Prova a usare colorama per il testo colorato.
• Ripiega su MockColors così lo script gira comunque (niente colori, nessun crash).

try:
    from colorama import Fore, Style, init

    init()
except ImportError:

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

    Fore = Style = MockColors()

4. Tracciare le statistiche di sessione

Una piccola dataclass per tenere traccia di costi, turni e durata.

• total_cost: somma del costo in $ dal Claude SDK.
• total_turns: quante richieste hai inviato.
• duration_ms: durata accumulata in millisecondi.

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

5. Creare le opzioni dell’agente

Ora creeremo l’oggetto ClaudeAgentOptions e ci connetteremo ai nostri server MCP. La funzione qui sotto convalida le variabili d’ambiente richieste, configura il server MCP di GitHub se disponibile e limita gli strumenti utilizzabili dall’agente.

Restringiamo volutamente gli allowed_tools in modo che Opus 4.5 possa: usare Bash per le operazioni Git, chiamare il server MCP di GitHub per ispezionare i contenuti del repository e usare Read/Write (insieme a Glob e Grep) per lavorare e validare i file Markdown locali.

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. Elaborare la risposta in streaming

Questa funzione ascolta lo stream e stampa testo, uso degli strumenti e output degli strumenti.

• Usa client.receive_response() come stream asincrono.
• Stampa il testo dell’assistente man mano che arriva.
• Quando uno strumento viene invocato → stampa [Tool Use: ...].
• Quando uno strumento restituisce output → tronca e stampa un’anteprima breve su una singola riga.
• Quando arriva un ResultMessage → aggiorna SessionStats con costo + durata.

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. Stampare un riepilogo finale

Statistiche di fine sessione per l’app CLI con turni, durata e costo in dollari.

• Converte duration_ms in secondi.
• Mostra il costo totale formattato a 4 decimali.

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. Funzione asincrona principale

Questo è il flusso di controllo principale dell’app: gestisce il setup, si connette ai servizi, legge l’input dell’utente e invia le richieste. La funzione chiama create_agent_options() e inizializza le statistiche. Stampa un banner introduttivo e indica quali server MCP sono attivi. Crea anche un ClaudeSDKClient usando un contesto asincrono.

L’applicazione esegue un semplice REPL (Read-Eval-Print Loop):

1. Digita 'exit' o 'quit' per uscire dall’applicazione.
2. Ogni richiesta valida incrementa stats.total_turns di 1.
3. await client.query(user_input) invia il messaggio dell’utente.
4. await process_response_stream(...) stampa il risultato in streaming.
5. Ogni eccezione viene intercettata e mostra un messaggio di errore in rosso.
6. Infine, la funzione chiama sempre 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. Entry point dello script

Infine, definiamo l’entry point dello script così la CLI parte quando il file viene eseguito direttamente. Il blocco seguente avvia il loop asincrono principale e gestisce l’arresto pulito:

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

Testare l’Auto Wiki Agent

Una volta installato tutto, avvia l’app di chat CLI e assicurati che la tua app CLI di Claude Code funzioni:

python gh_wiki_cli.py

Ora puoi interagire con l’agente proprio come in un’interfaccia di chat. Fai domande generali o digli direttamente di creare la wiki per il tuo repository:

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

Se l’utente chiede di creare una wiki, l’agente esegue automaticamente:

1. Clonazione della wiki: crea o riutilizza una cartella wiki_clone/ e scarica gli ultimi contenuti della wiki.
2. Ispezione del repository: legge i file chiave dal repository GitHub usando gli strumenti MCP. 
3. Generazione delle pagine: redige e scrive automaticamente pagine come:
• Home.md
• Getting-Started.md
• Architecture-and-Tools.md
4. Commit e push: l’agente prepara le nuove pagine, effettua il commit e invia gli aggiornamenti a: <your-repo>.wiki.git
5. Esempio di output riuscito: al termine, vedrai un chiaro messaggio di conferma. E la wiki sarà online su: https://github.com/kingabzpro/ECom-Intel/wiki

Sono rimasto davvero colpito da quanto bene l’agente sia riuscito a raccogliere immagini demo, grafici e altre informazioni chiave, per poi assemblare una home page coerente per la wiki.

La wiki ora include un vero sommario, spiegazioni sull’assistente e sugli strumenti, e chiare istruzioni per “iniziare”.

Al termine dell’esecuzione, il riepilogo di sessione ha mostrato che questa singola sessione è costata quasi 1 USD, piuttosto caro per generare una wiki di tre pagine. Se il repository fosse più grande e servisse, ad esempio, una wiki da 12 pagine, il costo aumenterebbe sensibilmente.

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

Nel secondo test, ho chiesto all’agente di creare una wiki per un altro repository:

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

Il risultato è stato ancora migliore. La wiki generata, disponibile su https://github.com/kingabzpro/Issue-Analyzer/wiki, ora contiene una documentazione adeguata che spiega cosa fa il progetto e come iniziare. 

Include tabelle ben strutturate, un diagramma dell’architettura e altre sezioni fondamentali che ti permettono di capire l’intero progetto in circa cinque minuti, invece di passare giorni a leggere il codice.

Considerazioni finali

Quando ho sentito per la prima volta che Opus 4.5 veniva definito il miglior modello al mondo per il coding e gli agenti, ero davvero entusiasta, soprattutto perché ha un prezzo simile ai modelli Sonnet. 

Tuttavia, l’entusiasmo è calato quando mi sono reso conto che sperimentare e creare una piccola applicazione è costato circa 15 $ di utilizzo API.

Opus 4.5 è potente ma costoso. Ho anche provato a replicare lo stesso flusso con Haiku e Sonnet, ma l’esperienza è risultata nettamente inferiore per questo tipo di attività agentica, ricca di documentazione. 

Entrambi ricorrevano spesso agli strumenti Bash, anche quando chiedevo esplicitamente di usare gli strumenti MCP per leggere i file di GitHub. Inoltre, impiegavano spesso percorsi più lunghi e meno diretti per risolvere i problemi.

Se per te contano accuratezza, affidabilità e generazione di codice e documentazione di alta qualità, Opus 4.5 vale sicuramente la pena di essere considerato. 

Se però il tuo caso d’uso è meno critico o hai un budget molto limitato, potresti restare su Sonnet o su modelli open source più economici. I costi di Opus 4.5 possono crescere rapidamente, soprattutto per workflow agentici multi-step su repository di grandi dimensioni.

Se il progetto ti interessa, trovi il codice sorgente completo qui, che puoi clonare ed eseguire in locale: kingabzpro/GitHub-Wiki-Agent.

Se non vedi l’ora di continuare a creare agenti AI, ti consiglio di dare un’occhiata al corso Multi-Agent Systems with LangGraph.