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

ghuntley/how-to-build-a-coding-agent – Workshop to Build a Local Claude‑powered Coding Assistant

What it is – A step‑by‑step tutorial (with ready‑to‑run Go source files) that shows you how to turn Anthropic’s Claude model into a local “coding agent”. The repo walks you through six incremental versions, each adding a new tool (file reading, directory listing, shell execution, file editing, code search) and demonstrates the classic agent‑tool loop.

Why it matters – It gives a concrete, hands‑on example of the emerging pattern where a large‑language model is kept lightweight and the heavy lifting (file system access, command execution, grep‑style search) is performed by explicit, sandboxed tools. Readers can see the full architecture, the Go‑based tool‑registry, and how to wire Claude’s JSON‑structured tool calls to real functions.

---

Key Features (as described in the README)

Feature	What you get
Claude integration	Simple Go client that sends user messages to the Anthropic API and receives responses.
Incremental agents	Six ready‑to‑run programs (chat.go, read.go, list_files.go, bash_tool.go, edit_tool.go, code_search_tool.go) each adding a new capability.
Tool system	Uniform definition of tools (name, description, input schema, Go function) that Claude can invoke via its tool‑use protocol.
File operations	Read arbitrary files, list directory contents, edit/create files safely.
Shell command execution	Run limited bash commands and return stdout/stderr to Claude.
Code search	Pattern‑based search across a codebase using ripgrep.
Verbose logging	--verbose flag shows the full event loop, tool dispatch, and error details.
Sample data	Small demo files (fizzbuzz.js, riddle.txt, AGENT.md) to try the tools immediately.
Development environment	Optional devenv configuration that provisions Go, Node, Python, Rust, .NET, and common dev tools.

---

Architecture Overview (from the README)

1. User input → sent to Claude via the Anthropic client.
2. Claude replies directly or with a tool request (e.g., read_file).
3. The agent looks up the requested tool in a registry, executes the Go function, captures the result or error.
4. The result is fed back to Claude, which can then produce the final answer or request more tools.
5. This loop repeats until Claude returns a plain text response.

The diagrams in the README illustrate two views:

• Application progression – how each successive program adds a new tool.
• Event loop – the runtime flow of messages, tool dispatch, and result handling.

---

Getting Started (as per the README)

1. Prerequisites
   • Go 1.24.2 or newer (or use the provided devenv setup).
   • Anthropic API key (export ANTHROPIC_API_KEY=…).
2. Setup
   • Recommended: devenv shell to load the environment.
   • Or manually run go mod tidy after cloning.
3. Run the first version

   go run chat.go          # basic Claude chat
   go run read.go          # adds file‑reading tool
   go run list_files.go    # adds directory listing
   go run bash_tool.go     # adds shell command tool
   go run edit_tool.go     # adds file‑editing tool
   go run code_search_tool.go  # adds ripgrep‑based search
   

   • Use --verbose for detailed logs.
   • Try the sample prompts shown in the README (e.g., “Read fizzbuzz.js”, “Run git status”).
4. Troubleshooting – check the API key, run go mod tidy, use --verbose, verify file permissions.

---

Tech Stack

• Language – Go (leveraging Go structs for JSON schema generation).
• LLM – Anthropic Claude accessed via its public API.
• Tooling – ripgrep for fast code search, standard OS shell for command execution.
• Optional dev environment – devenv (provides multi‑language runtimes and tooling).

---

Who Should Use This

• Developers curious about LLM‑driven agents and how to safely expose system capabilities.
• Go programmers who want a concrete example of tool‑use integration with Claude.
• Educators or workshop leaders looking for a ready‑made, incremental tutorial.

---

Next Steps Suggested by the Author

• Add custom tools (e.g., HTTP API callers, web scrapers).
• Chain tools together for more complex workflows.
• Implement persistent memory across sessions.
• Build a web UI front‑end.
• Experiment with other LLM providers.

---

Bottom line – This repository is a practical, hands‑on guide for building a local AI coding assistant using Claude and Go, illustrating the modern agent‑tool pattern in a clear, incremental fashion.