ghuntley/how-to-build-a-coding-agent: a Go workshop that builds six agents in sequence

The gap between using a coding agent and knowing how one works

Most engineers meet coding agents as finished products. Cursor, Cline, Amp and OpenCode present a chat box, and the machinery underneath stays hidden. The workshop in ghuntley/how-to-build-a-coding-agent exists to remove that box. It walks through connecting to the Anthropic Claude API, defining tools, handling tool requests and errors, and growing a program one capability at a time.

The audience is narrow and specific. The README says you do not need to be an AI expert, but the code is Go and the six stages are six separate programs, so you need enough Go to read struct tags and function signatures. The README also points to a longer blog post at ghuntley.com/agent for a detailed overview. This is a workshop for people who want to build a coding agent from scratch and see the event loop, not for people who want an assistant installed by lunchtime.

Six programs, one event loop, and a tool registry

The repository is organized as a progression, not a single application. The README lists six entry points: chat.go, read.go, list_files.go, bash_tool.go, edit_tool.go and code_search_tool.go. Each adds one tool, and the tool sets are cumulative. chat.go has no tools. read.go adds read_file. list_files.go adds list_files. bash_tool.go adds bash. edit_tool.go adds edit_file. code_search_tool.go adds code_search. The top-level directory listing matches the README, so the files are there rather than described.

The shared loop is documented as an event loop. The agent waits for input, sends the conversation to Claude, and Claude either answers directly or asks for a tool. If a tool is requested, the agent finds it by name, executes the function, captures the result or the error, appends it to the tool results, and sends those results back to Claude. That cycle repeats until Claude returns text instead of a tool request. The README calls this the agent's heartbeat, and the diagram in it shows the loop returning to runInference after each tool round.

Tools are declared, not hardcoded into the loop. The README's example shows a ToolDefinition with a Name, a Description, an InputSchema and a Function. The schema is generated from a Go struct through GenerateSchema, and go.mod lists github.com/invopop/jsonschema v0.13.0 for that purpose, alongside github.com/anthropics/anthropic-sdk-go v1.26.0. So the design is: describe the tool as a struct, let the schema library produce JSON Schema, and let the event loop dispatch by name.

Installing the workshop and running chat.go

The README gives two setup paths. devenv is recommended, and manual setup is the fallback. Both require Go 1.24.2 or later and an Anthropic API key. The README does not list a package registry, so there is nothing to install from one; you clone the repository and run the files.

With devenv, the README says the shell loads everything you need:

devenv shell  # Loads everything you need

Without devenv, resolve the module dependencies first. go.mod pins the Anthropic SDK and the schema library, so this step fetches them:

go mod tidy

The API key is read from the environment. The README exports it under the name ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="your-api-key-here"

Then run the first stage. The README's suggested first message is "Hello!", and --verbose is documented as the flag that shows detailed logs:

go run chat.go

What you should see is a prompt for input, a reply from Claude, and nothing else unless you pass --verbose. If the key is missing or the quota is exhausted, the README's troubleshooting section points at echo $ANTHROPIC_API_KEY and the Anthropic dashboard. The later stages follow the same shape: go run read.go, then go run list_files.go, then go run bash_tool.go, then go run edit_tool.go, then go run code_search_tool.go. The README suggests trying "Read fizzbuzz.js" against read.go, "Run git status" against bash_tool.go, and "Search for TODO comments" against code_search_tool.go. The repository ships fizzbuzz.js, riddle.txt and AGENT.md as sample files for those prompts.

A Makefile that builds five binaries, not six

The Makefile is worth reading before you trust the build. Its BINARIES variable lists bash_tool, chat, edit_tool, list_files and read. code_search_tool is absent from both the variable and the build target, and the check target runs go vet on the same five files. So make all formats, vets and builds five of the six stages. The sixth is only reachable through go run code_search_tool.go.

That mismatch is small, but it is the kind of detail that decides whether you can wire the workshop into a script. The check target also runs go vet per file rather than per package, which is consistent with the repository being a set of standalone main programs in one module named chat.

make all

Running that gives you formatted sources, vet output for the five listed files, and five binaries in the repository root. If you expect a code_search_tool binary afterwards, you will not get one.

Where the workshop stops being the right tool

The README states that bash_tool.go allows Claude to run "safe terminal commands", but it does not define what makes a command safe, and it does not document a confirmation step, an allowlist or a sandbox. The same gap applies to edit_tool.go, which the README describes as adding safety checks without naming them. There is no documented rollback or undo for an edit, and the README does not mention version control integration. Anyone who has watched an agent rewrite a file it should not have touched will read that as the central limitation of the workshop rather than a footnote.

There is also no licence file in the top-level listing, and the README does not state terms. That matters more here than in a normal dependency, because the point of the workshop is to copy patterns into your own program. Without a stated licence, the safe assumption is that you cannot treat the code as reusable until you confirm terms with the author.

The third boundary is scope. This is a teaching sequence, not a maintained agent. The last push to the repository was on 2026-09-05. It is not archived. It also has no releases, so there is no version to pin and no changelog to read. If you need an agent with a support path, this is the wrong repository, and the README does not claim otherwise.

How this differs from Cline, Roo Code and the other finished agents

The README names Roo Code, Cline, Amp, Cursor, Windsurf and OpenCode as similar tools, which makes the comparison fair game. The difference is not features. It is where the code lives.

Cline and Roo Code ship as editor extensions, so the tool loop, the approval prompts and the model plumbing are maintained by someone else. You configure them and you get updates. Here, the loop is a file you read and run. When you want to change how a tool result is fed back to the model, you edit the event loop rather than wait for a release. When you want an approval gate before bash runs, you write it, because the README does not describe one.

A second real difference is the dependency surface. go.mod pulls the Anthropic SDK and a JSON Schema generator, and the workshop is bound to the Claude API. The README's prerequisites name an Anthropic API key and nothing else. An agent built on this pattern inherits that coupling, so swapping providers is a code change, not a setting.

Maintenance cost, upgrades and what the licence does not say

The repository carries a renovate.json file, which indicates dependency updates are intended to be automated, and a devenv.lock, which pins the development environment. Those two files are the maintenance story the repository actually tells. There is no release history, so upgrades happen at the commit level, and the last push was on 2026-09-05.

On licensing, no licence identifier appears and the top-level listing shows no LICENSE file. The README does not state terms for reuse. That is a question to settle with the author before you copy a tool definition or the event loop into a product, and it is not a question this article can answer.

The practical cost of following along is low: Go 1.24.2, an API key, and the willingness to run six programs one after another. The cost of depending on it is different. You would be depending on a workshop whose Makefile covers five of six stages and whose safety claims are undefined, so the honest framing is that you adopt the pattern and not the code.

Editorial conclusion

Adopt this if you want the tool-calling loop in your hands rather than behind a vendor API, and you are comfortable reading Go. Skip it if you need an agent to use today, a supported library, or a licence you can verify: the repository carries no licence file, and the README documents no rollback or undo for edit_tool.go. Verify the licence and the Go 1.24.2 toolchain requirement before you copy any file into your own tree.

Frequently asked questions

Official sources

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