ghuntley/how-to-build-a-coding-agent: a six-stage Go workshop for building a Claude tool loop

What the workshop is actually for

Most people meet coding agents as products. They install an extension, point it at a repository, and watch it edit files. The mental model stays opaque. This repository targets the gap between using one of those products and understanding why it behaves the way it does. The README frames the goal directly: build a coding assistant that starts as a basic chatbot and gains file reading, shell execution and code searching. The intended audience is stated just as plainly, since the README says you do not need to be an AI expert. That is a real constraint on the material. It means the workshop explains the tool-call loop rather than transformer internals, and it means the code is meant to be read in order rather than dropped into a production tree. If you already know how a tool-use loop works, the first three stages will teach you very little. The last three are where the interesting design questions live, because that is where the agent stops describing your code and starts changing it.

The six-file progression and why it is ordered that way

The repository ships six Go programs, each a superset of the previous one. chat.go talks to Claude with no tools attached. read.go adds a read_file tool. list_files.go adds directory listing alongside it. bash_tool.go adds shell command execution. edit_tool.go adds file modification. code_search_tool.go adds pattern search backed by ripgrep. The README's own diagram maps each file to the tool set it exposes, so the progression is additive and the tool registry grows by one entry per stage. That ordering is the pedagogical content. A reader who jumps straight to edit_tool.go sees a tool definition and a function, but not the intermediate step where a tool returns an error and the loop has to hand that error back to the model. The README's stated learning outcomes include handling tool requests and errors, and the only place that becomes concrete is in the middle of the sequence. The six stages are also six separate main packages, which means each one runs on its own with go run and no shared library to configure. That is convenient for teaching and inconvenient for anyone who wants to reuse the code, since there is no module to import.

The event loop, as the README describes it

The architecture section describes a loop with a clear shape. The agent waits for input, sends it to Claude, and Claude either answers in text or asks to use a tool. If a tool is requested, the agent runs it, collects the result, sends that result back to Claude, and runs inference again. The README calls this the event loop and diagrams it separately from what it calls the tool execution loop, which finds a tool by name, executes its function, captures either a result or an error, appends it to a list of tool results, and repeats if more tools were requested. Two details in that description matter more than the rest. First, the loop is recursive rather than single-pass: after tool results go back, inference runs again, so a single user turn can involve several rounds of tool calls. Second, errors are captured into the same result channel as successes, which is what lets the model see a failed file read and try a different path. The diagram also shows an empty-input check that returns to the prompt rather than sending an empty message, and a verbose logging flag threaded through the agent. Those are small choices, but they are the difference between a demo that works once and one you can debug.

Tool definitions and schema generation from Go structs

The README shows the tool shape directly. A ToolDefinition carries a Name, a Description, an InputSchema and a Function. The example given is read_file, with the description "Reads the contents of a file" and a schema produced by GenerateSchema[ReadFileInput](), a generic call over a Go struct type. That is the mechanism worth noting. Instead of hand-writing JSON Schema for each tool, you declare an input struct and let the generic function derive the schema from it. For a workshop this removes a whole category of boilerplate and keeps the reader focused on the loop. It also means the tool contract is expressed once, in Go, and the model-facing description is generated from it. The README states that schema generation uses Go structs so definitions are easy to define and reuse, which is a fair summary of the approach. What the material does not show is how GenerateSchema handles nested structs, optional fields or validation. If you extend the workshop with a tool that takes a complex input, that is the first thing you will have to read the source to understand.

Getting it running: prerequisites, commands and config

The prerequisites are Go 1.24.2 or later, or devenv, plus an Anthropic API key. The README recommends devenv and gives devenv shell as the way to load everything, with go mod tidy as the manual alternative. The API key is exported as ANTHROPIC_API_KEY, and the troubleshooting section suggests echo $ANTHROPIC_API_KEY to confirm it is set. Each stage runs with a plain go run command: go run chat.go, go run read.go, go run list_files.go, go run bash_tool.go, go run edit_tool.go, go run code_search_tool.go. The --verbose flag is available for detailed logs, and the README points to it again in troubleshooting for full error logs. Three sample files ship with the repository: fizzbuzz.js for reading and editing, riddle.txt as a text file to explore, and AGENT.md describing the project environment. The workshop also lists prompt suggestions per stage, such as "Read fizzbuzz.js" for stage two and "Run git status" for stage four. There is no configuration file, no build step and no install target. Everything is a flat set of Go programs driven by one environment variable.

Where the workshop stops short

The bash tool is the sharpest limitation. The README describes it as running safe terminal commands, and the suggested exercise is to run git status. Nothing in the supplied material explains what makes a command safe, whether there is a command allowlist, whether the agent asks for confirmation before executing, or whether the working directory is constrained. Given that the same sequence later adds file editing, a reader could reasonably end up with a program that both runs shell commands and rewrites files, with no described guardrail beyond the word safe. The edit tool is similarly thin in the material: the workshop path table lists safety checks as the focus of stage five, but the README does not say what those checks are. There is also no licence file retrieved with the repository, so the terms under which the code can be reused are unknown from this material alone. Finally, the repository has no releases, which fits a workshop that is meant to be read at a point in time, but it also means there is no versioned artifact to pin. Treat the trunk branch as the only reference.

How this differs from adopting a finished agent

The honest comparison is with the tools the README names as similar: Roo Code, Cline, Amp, Cursor, Windsurf and OpenCode. Those are applications. You install them, they own the tool implementations, the permission prompts and the context management, and your job is to configure and use them. This repository is the opposite arrangement. It hands you the loop and the six tool definitions and expects you to assemble them. The difference in approach shows up at the first extension point. With a finished agent, adding a tool means writing against that product's extension API and inheriting its permission model. Here, adding a tool means adding a ToolDefinition with a name, a description, a schema and a function, then registering it. You get complete control over what the agent can do and no inherited safety net. That trade is the entire point of the workshop, and it is also why this is not a substitute for any of those products in day-to-day work.

Maintenance, licence and what to check before you commit

There is no dependency surface to maintain beyond the Go standard library and whatever the Anthropic client pulls in through go mod tidy, and no release cadence to track. Upgrades are whatever happens on the trunk branch between the last push and now. For a workshop that is acceptable, because the reader is expected to finish the sequence and move on. For anyone tempted to fork one of the six files into a real tool, the maintenance burden transfers entirely to you. The licence is the open question. The repository metadata supplied here does not include a licence identifier, and no LICENSE file is mentioned in the README. That does not mean there is no licence, only that it cannot be confirmed from this material. Check the repository root before you copy code into anything you intend to distribute. The other thing to verify is the bash tool's actual implementation, since the README's description of safe commands is a claim about behaviour rather than a specification of it.

Editorial conclusion

Adopt this if you want to understand the mechanics of a coding agent rather than install one, and if you are comfortable reading Go and wiring an ANTHROPIC_API_KEY into a shell session. Skip it if you need a maintained tool with a security model, or if you want a package to import rather than a sequence to type out. Before starting, check two things in the repository itself: whether a LICENSE file exists on the trunk branch, since the licence was not retrieved here, and whether the bash tool implementation in bash_tool.go does anything beyond the README's phrase about safe terminal commands.

Official sources

1. ghuntley/how-to-build-a-coding-agent on GitHub
2. Issues
3. Project website
4. README