# ghuntley/how-to-build-a-coding-agent architecture

> Architecture diagram of the GitHub repository ghuntley/how-to-build-a-coding-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghuntley/how-to-build-a-coding-agent
- Repository: https://github.com/ghuntley/how-to-build-a-coding-agent

## Overview

##### Project type and purpose
- This is an open-source workshop repository written in Go that demonstrates step-by-step how to build progressively more capable AI “agents.”
- It evolves from a basic chat client (chat.go) to a full-featured agent with file I/O, shell commands, file editing, and code search (code_search_tool.go).
- Core learning: event-driven agent loop, tool-calling pattern, schema-driven parameters, error handling, and progressive enhancement.

##### File structure
- Top-level .go files each represent one stage of the agent:
– chat.go
– read.go
– list_files.go
– bash_tool.go
– edit_tool.go
– code_search_tool.go
- Shared resources:
– AGENT.md (dev environment docs)
– prompts/ (sample prompt files)
– Makefile, devenv.* (environment setup), go.mod/go.sum
- No separate src directory; each agent is a standalone executable that imports common modules (tool definitions, schema generation, logging).
- Configuration and environment files (.envrc, .gitignore, renovate.json) sit at root.

##### README for architecture insights
– Overall agent architecture (Agent → Anthropic Client, Tool Registry, getUserMessage, Logging)
– Shared event loop (user input → inference → tool use loop → result → back to Claude)
– Tool execution loop (lookup by name → run → capture result → repeat)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation"
        Console["Console I/O"]:::io
    end

    %% Application Layer
    subgraph "Application"
        AgentCore["Agent Core\n(Event Loop)"]:::app
        ToolRegistry["Tool Registry"]:::app
        Logger["Logger"]:::app
    end

    %% Integration Layer
    subgraph "Integration"
        read["read_file Tool"]:::integration
        listfiles["list_files Tool"]:::integration
        bash["bash Tool"]:::integration
        edit["edit_file Tool"]:::integration
        codesearch["code_search Tool"]:::integration
        Claude["Anthropic Claude API"]:::external
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        FS["File System"]:::infra
        Shell["Shell Environment"]:::infra
        Ripgrep["Ripgrep CLI"]:::infra
    end

    %% Data Flow
    Console -->|user input| AgentCore
    AgentCore -->|runInference| Claude
    Claude -->|response| AgentCore
    AgentCore -->|invoke tool| ToolRegistry
    ToolRegistry -->|select| read
    ToolRegistry -->|select| listfiles
    ToolRegistry -->|select| bash
    ToolRegistry -->|select| edit
    ToolRegistry -->|select| codesearch
    read -->|reads| FS
    listfiles -->|lists| FS
    bash -->|executes| Shell
    edit -->|modifies| FS
    codesearch -->|searches| Ripgrep
    read -->|result| AgentCore
    listfiles -->|result| AgentCore
    bash -->|result| AgentCore
    edit -->|result| AgentCore
    codesearch -->|result| AgentCore
    AgentCore -->|logs| Logger
    AgentCore -->|output| Console

    %% Click Events
    click Console "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/chat.go"
    click AgentCore "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/chat.go"
    click read "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/read.go"
    click listfiles "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/list_files.go"
    click bash "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/bash_tool.go"
    click edit "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/edit_tool.go"
    click codesearch "https://github.com/ghuntley/how-to-build-a-coding-agent/blob/trunk/code_search_tool.go"

    %% Styles
    classDef io fill:#e3f2fd,stroke:#1e88e5
    classDef app fill:#c8e6c9,stroke:#2e7d32
    classDef integration fill:#fff9c4,stroke:#f9a825
    classDef external fill:#f3e5f5,stroke:#6a1b9a
    classDef infra fill:#ffe0b2,stroke:#e65100
```
