ghuntley/how-to-build-a-coding-agent: a six-stage Go workshop for building a Claude tool loop
A workshop that teaches you how to build your own coding agent. Similar to Roo code, Cline, Amp, Cursor, Windsurf or OpenCode.
At a glance
- What is it?
- The repository is a teaching sequence, not a library. It walks from a bare Claude chat loop to a six-tool coding assistant across six standalone Go files, and the value is in that progression rather than in any one artifact.
- Who is it for?
- 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.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- ghuntley/how-to-build-a-coding-agent5,923 ★ · +98
| Repository | 2026-09-12 | 2026-11-15 |
|---|---|---|
| ghuntley/how-to-build-a-coding-agent | 5.8k | 5.9k |
98 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
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 its diagram shows the agent executing tools and collecting their results. 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, the workshop path table lists error capture as a focus of the bash_tool.go stage. 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 schema 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. How GenerateSchema handles nested structs, optional fields or validation is a separate question. 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. The README lists three sample files: 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. A Makefile provides build, fmt and check targets, but go run needs no separate build step. 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. 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: the workshop path table lists safety checks as the focus of stage five. The repository has no licence file, so the terms under which the code can be reused are unknown. 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
The direct dependencies in go.mod are anthropic-sdk-go v1.26.0 and invopop/jsonschema v0.13.0, and there is 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. GitHub reports no licence for the repository, and there is no LICENSE file at the repository root. 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, and whether the bash tool implementation in bash_tool.go does anything beyond the README's phrase about safe terminal commands.
Frequently asked questions
What exactly is a coding agent in ghuntley's workshop?
In this workshop a coding agent is a Go program that holds a conversation with Claude through a six step event loop: read your input, send it, run any tool Claude asks for, send the result back, and print the final answer. The tool side grows from read_file in read.go to file listing, shell commands, file editing, and ripgrep backed pattern search in code_search_tool.go.
How do I build my own agent with this Go workshop?
Install Go 1.24.2 or use devenv, run go mod tidy, export ANTHROPIC_API_KEY, and start with go run chat.go. Each of the next five files adds one tool to the same loop, and the phase table maps each file to its focus, from tool system and schema generation in read.go to file editing and safety checks in edit_tool.go.
How much does a coding agent cost to run?
The repository states no price. Running these programs costs Anthropic API usage on the key you export, and the walkthrough's answer to a failing key is to check your quota on Anthropic's dashboard. anthropic-sdk-go v1.26.0 and invopop/jsonschema v0.13.0 are the only direct dependencies in go.mod.
huntley how to build a coding agent
That is this repository: ghuntley/how-to-build-a-coding-agent, written in Go on the trunk branch, with the long form write up at ghuntley.com/agent. The top level files are chat.go, read.go, list_files.go, bash_tool.go, edit_tool.go and code_search_tool.go, plus Makefile, go.mod and devenv.nix. The last push was 2026-10-30 and there are no GitHub releases.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ghuntley-how-to-build-a-coding-agent)Star history chart for your README
[](https://hysenlabs.com/projects/ghuntley-how-to-build-a-coding-agent)Was this useful?