Claude Opus 4.5-tutorial: bouw een GitHub Wiki-agent

Moderne GitHub-repositories missen vaak duidelijke, gestructureerde documentatie, vooral wikis.

Het handmatig maken van deze pagina's kan uren kosten: code lezen, de architectuur begrijpen en content organiseren.

Een GitHub Wiki AI-agent kan dit probleem oplossen.

In deze tutorial laat ik je stap voor stap zien hoe je een volledig geautomatiseerde GitHub Wiki AI-agent bouwt: een command-line tool die Claude Opus 4.5 en de Claude Agent SDK gebruikt om complete wikis voor GitHub-repositories te genereren met één instructie. 

In plaats van documentatie handmatig te schrijven, analyseert deze tool je codebase, begrijpt de structuur en produceert schone wiki-content met meerdere pagina's die automatisch wordt gecommit en gepubliceerd naar je repository. 

Alles draait via een interactieve CLI-app die snel, slim en developer-vriendelijk aanvoelt.

In deze gids volgen we een eenvoudig proces in drie stappen om de omgeving in te richten, de GitHub Wiki AI-agent te bouwen en deze te testen op echte repositories:

1. Richt de omgeving in: installeer dependencies, installeer en verifieer Claude Code, configureer GitHub-tokens en schakel de Wiki-functie in.
2. Bouw de applicatie: maak de CLI-tool, configureer de Claude Agent, integreer MCP GitHub-tools, voeg kostentracking toe en implementeer de wiki-generatielogica (Home, Aan de slag, Architectuur & Tools).
3. Test de agent: voer hem uit op echte repositories (ECom-Intel en Issue-Analyzer) om klonen, analyse, wikicreatie en automatische push te verifiëren.

Als je nieuw bent met AI-agents en meer wilt leren, raad ik je aan om de AI Agent Fundamentals skill track te bekijken. Lees ook onze tutorial over Claude Cowork en onze gids voor de nieuwe Claude Opus 4.6.

Je omgeving instellen voor de Claude Opus 4.5 GitHub Wiki-tutorial

Voordat je de GitHub Wiki-agent met Opus 4.5 gaat bouwen, zorg je dat je omgeving correct is geconfigureerd. In dit deel nemen we alle vereisten en stappen voor de setup door.

1. Vereisten om de Claude Opus 4.5 Wiki-agent te draaien

• Python 3.11 of hoger (vereist door de Python Claude Agent SDK).
• Node.js en npm (vereist om Claude Code te installeren), de ruggengraat van onze applicatie die agents, tools en integraties voor MCP-servers levert.

2. Installeer en verifieer Claude Code

Open je terminal (Command Prompt, PowerShell of macOS Terminal) en voer de volgende opdracht uit om de Claude Code CLI te installeren:

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

Typ claude in je terminal om Claude Code te starten. Typ vervolgens in de Claude-chat /login om je te authenticeren en toegang te krijgen tot het Opus 4.5-model en de tools, zoals hieronder getoond.

Je kunt meer leren over Claude Code in onze hands-on tutorial. 

3. Genereer een fijnmazige GitHub Personal Access Token

Ga naar GitHub om een fijnmazige Personal Access Token te genereren en navigeer naar: 

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

Maak een nieuw token aan en selecteer onder Repository de repository die je gaat gebruiken. Configureer vervolgens de Permissions. Stel om veiligheidsredenen bij voorkeur een korte vervaltijd in voor het token.

Stel daarna de Personal Access Token in als omgevingsvariabele:

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

4. Initialiseer je GitHub-wiki

GitHub ondersteunt momenteel niet dat je eerst lokaal een wiki maakt.

Je moet de wiki dus handmatig initialiseren door:

1. Je repository te openen op GitHub
2. Op het tabblad Wiki te klikken
3. Te klikken op “Create the first page”
4. De pagina op te slaan (elke titel is goed)

5. Installeer de Claude Agent SDK

We installeren het Claude Agentic-framework dat alles afhandelt: van het gebruiken van MCP tot het aanroepen van tools, het maken van bestanden en het pushen van wijzigingen naar de remote.

pip install claude-agent-sdk

De Auto Wiki-agent bouwen met Claude Opus 4.5

We maken nu een Python CLI-applicatie met de naam gh_wiki_cli.py. Dit bestand bevat configuraties, agents, tools, een MCP-client, systeemprompts, de CLI-app zelf en helperfuncties. 

Deze componenten zorgen ervoor dat de gebruiker de link naar de repository kan aanleveren en dat de agent weet hoe hij deze correct moet verwerken om de GitHub-wiki te publiceren.

1. Imports

Dit deel haalt Python-stdlib-modules, typing-helpers en de Claude Agent SDK binnen.

• asyncio voor async I/O (chat + streaming).
• os, sys voor omgevingsvariabelen en afsluiten.
• dataclass om statistieken bij te houden.
• Claude Agent SDK-imports om met de agent + MCP-tools te praten.

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. Systeemprompt

Dit is het “brein” van de agent. We instrueren het Opus 4.5-model hoe het zich moet gedragen en hoe het de tools moet gebruiken.

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. Kleurverwerking voor de CLI

Dit maakt de CLI-uitvoer mooier, maar werkt ook als colorama niet is geïnstalleerd.

• Probeert colorama te gebruiken voor gekleurde tekst.
• Valt terug op MockColors zodat het script blijft draaien (geen kleuren, geen crash).

try:
    from colorama import Fore, Style, init

    init()
except ImportError:

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

    Fore = Style = MockColors()

4. Sessiestatistieken bijhouden

Een kleine dataclass om kosten, beurten en duur bij te houden.

• total_cost: som van de $-kosten uit de Claude SDK.
• total_turns: hoeveel gebruikersvragen je hebt verstuurd.
• duration_ms: opgetelde duur in milliseconden.

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

5. Agentopties aanmaken

Vervolgens maken we het ClaudeAgentOptions-object en verbinden we met onze MCP-servers. De onderstaande functie valideert de vereiste omgevingsvariabelen, configureert de GitHub MCP-server als die beschikbaar is en beperkt de tools die de agent mag gebruiken.

We beperken bewust de allowed_tools zodat Opus 4.5: Bash kan gebruiken voor Git-operaties, de GitHub MCP-server kan aanroepen om repository-inhoud te inspecteren en Read/Write (samen met Glob en Grep) kan gebruiken om met lokale Markdown-bestanden te werken en deze te valideren.

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. De streamingrespons verwerken

Deze functie luistert naar de stream en print tekst, toolgebruik en tool-uitvoer.

• Gebruikt client.receive_response() als een async stream.
• Print assistant-tekst zodra die binnenkomt.
• Wanneer een tool wordt aangeroepen → print [Tool Use: ...].
• Wanneer een tool uitvoer retourneert → wordt de uitvoer ingekort en als een korte, éénregelige preview geprint.
• Wanneer een ResultMessage binnenkomt → wordt SessionStats bijgewerkt met kosten + duur.

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. Aan het eind een samenvatting printen

Mooie sessiestatistieken voor de CLI-app die beurten, duur en kosten in dollars tonen.

• Zet duration_ms om naar seconden.
• Toont totale kosten geformatteerd op 4 decimalen.

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. Hoofdfunctie (async)

Dit is de kern van de app: handelt de setup af, maakt verbinding met services, leest gebruikersinvoer en verstuurt queries. De functie roept create_agent_options() aan en initialiseert statistieken. Hij print een introductiebanner en geeft aan welke MCP-servers zijn ingeschakeld. Ook maakt hij een ClaudeSDKClient aan met een asynchrone context.

De applicatie draait een eenvoudige REPL (Read-Eval-Print Loop):

1. Typ 'exit' of 'quit' om de applicatie te verlaten.
2. Elke geldige query verhoogt stats.total_turns met 1.
3. await client.query(user_input) verstuurt het bericht van de gebruiker.
4. await process_response_stream(...) print de gestreamde respons.
5. Eventuele uitzonderingen worden opgevangen en getoond als foutmelding in rood.
6. Tot slot roept de functie altijd print_summary(stats) aan.

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. Script entry point

Tot slot definiëren we het entry point van het script zodat de CLI draait wanneer het bestand direct wordt uitgevoerd. Het onderstaande blok start de asynchrone hoofdlus en zorgt voor een nette afsluiting:

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

De Auto Wiki-agent testen

Als alles is geïnstalleerd, start je de CLI-chatapp en controleer je of je Claude Code CLI-app werkt:

python gh_wiki_cli.py

Je kunt nu met de agent communiceren zoals in een chatinterface. Stel algemene vragen of geef direct de opdracht om de wiki voor je repository te bouwen:

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

Als de gebruiker vraagt om een wiki te maken, voert de agent automatisch het volgende uit:

1. Wiki klonen: Maakt of hergebruikt een map wiki_clone/ en haalt de nieuwste wiki-inhoud op.
2. Repository inspecteren: Leest kernbestanden uit de GitHub-repository met de MCP-tools. 
3. Pagina's genereren: Stelt automatisch concepten op en schrijft pagina's zoals:
• Home.md
• Getting-Started.md
• Architecture-and-Tools.md
4. Committen en pushen: De agent staged de nieuwe pagina's, commit ze en pusht updates naar: <your-repo>.wiki.git
5. Voorbeeld van geslaagde uitvoer: Na afloop zie je een duidelijke bevestiging. En de wiki staat live op: https://github.com/kingabzpro/ECom-Intel/wiki

Ik was oprecht onder de indruk van hoe goed de agent demo-afbeeldingen, grafieken en andere kerninfo wist te verzamelen en vervolgens een samenhangende homepage voor de wiki maakte.

De wiki bevat nu een nette inhoudsopgave, uitleg over de assistant en tools, en duidelijke “aan de slag”-instructies.

Aan het eind van de run liet de sessiesamenvatting zien dat deze ene sessie bijna 1 USD kostte, wat best prijzig is voor het genereren van een wiki met drie pagina's. Als de repository groter was en we bijvoorbeeld een wiki met 12 pagina's nodig hadden, zouden de kosten aanzienlijk oplopen.

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

In de tweede test vroeg ik de agent om een wiki te maken voor een andere repository:

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

Het resultaat was nog beter. De gegenereerde wiki, beschikbaar op https://github.com/kingabzpro/Issue-Analyzer/wiki, bevat nu nette documentatie die uitlegt wat het project doet en hoe je aan de slag gaat. 

Er staan goed gestructureerde tabellen in, een architectuurdiagram en andere kernsecties, zodat je het hele project in zo'n vijf minuten begrijpt in plaats van dagen door de code te ploegen.

Tot slot

Toen ik voor het eerst hoorde dat Opus 4.5 werd bestempeld als het beste coding- en agentic-model ter wereld, was ik echt enthousiast, zeker omdat de prijs vergelijkbaar is met die van de Sonnet-modellen. 

Mijn enthousiasme nam echter af toen ik merkte dat experimenteren en een kleine applicatie bouwen zo'n $15 aan API-gebruik kostte.

Opus 4.5 is krachtig maar duur. Ik heb ook geprobeerd dezelfde workflow te repliceren met Haiku en Sonnet, maar de ervaring was merkbaar minder voor dit soort agentische, documentatie-intensieve taken. 

Beide vielen vaak terug op Bash-tools, zelfs wanneer ik expliciet vroeg om MCP-tools te gebruiken voor het lezen van GitHub-bestanden. Bovendien kozen ze vaak langere, minder directe routes om problemen op te lossen.

Als je nauwkeurigheid, betrouwbaarheid en hoge kwaliteit van code- en documentatiegeneratie prioriteit geeft, is Opus 4.5 zeker het overwegen waard. 

Maar als je use-case minder kritisch is of je zeer kostenbewust bent, kun je beter bij Sonnet blijven of zelfs goedkopere open-sourcemodellen gebruiken. De kosten van Opus 4.5 kunnen snel oplopen, vooral bij meerstaps, agentische workflows over grote repositories.

Als je geïnteresseerd bent in het project, vind je hier de volledige broncode, die je kunt clonen en lokaal draaien: kingabzpro/GitHub-Wiki-Agent.

Als je graag verder wilt bouwen aan AI-agents, raad ik de cursus Multi-Agent Systems with LangGraph aan.