build-your-own-coding-agent // v0.4.2
[ES] ★ github →
v0.4.2-alpha / MIT licensed / 20 lessons · 3 how-tos · 6 exercises / github.com/betta-tech/byo-coding-agent

Build Your Own Coding Agent — a hands-on intro to harness engineering

Modern coding agents are mostly harness, not model. This repo walks you through every layer of that harness — provider wrappers, context budgets, memory, tools, MCP, subagents — as a sequence of small lessons with runnable code. Read the markdown. Edit the source. Watch the loop turn.

read the lessons→ $ clone & run see the harness↘
§00 What is harness engineering?

The model writes the code.
The harness decides what it sees, remembers, and can touch.

Swap the model in any popular coding agent and most of its character stays the same. The personality, the failure modes, the way it recovers — those live in the harness: the loop, the prompts, the tool surface, the budget rules. Harness engineering is the discipline of designing that scaffolding deliberately, instead of copying it from a tutorial.

You'll write

A working coding agent in Go — streaming, tool use, file edits, an MCP client, subagents, prompt caching, and a real TUI by the end.

You won't ship

A production system. The point is to see every wire. We trade robustness for legibility — every file is meant to be read end-to-end.

§01 Anatomy of the harness

A loop, four utilities, two outgoing channels.

This is the system you'll build, piece by piece. Hover any node to focus it — every box maps to a lesson, a file, and a few hundred lines of code.

fig.01 · signal flow
input
user / cli
§03
provider wrapper
anthropic · openai · local
§01
agent loop
prompt → call → tool → repeat
§06–07
context mgr
§19
memory
§09
tools
i/o
filesystem · shell
§14
MCP servers
fetch · search · custom
§11
subagents
reviewer · planner
§02 Curriculum

20 lessons, in four chapters.

Each lesson is a markdown file in /follow_along that walks through one part of the harness already living in the repo. The code is the final version — the lessons explain how each piece was built and why. Read in order for the full tour, or jump to whichever chapter you need.

§00–04
Foundations
The smallest thing that can call a model, take a turn, and run a tool.
§05–08
Conversation
Messages, budgets, and the bookkeeping that keeps a long session coherent.
§09–12
Tools & structure
A real tool surface, an opinionated layout, subagents, and a proper TUI.
§13+
Going further
Optional chapters — MCP, caching, diff approval, memory, and where to take it next.
§03 How-to guides

Short recipes for extending the harness.

Once you've read the lessons and want to add your own piece, these guides give you the step-by-step — what file to create, which interface to implement, what changes in main.go. Each assumes you already know the why; this is just the how.

how-to →
How to add a permission policy
replace "ask every time" with something smarter — auto-allow read_file, ask once per shell command, deny writes outside the working directory.
how-to →
How to add a new provider
run the harness against a different LLM backend — OpenAI, Bedrock, a local Ollama, or a mock for tests.
how-to →
How to add a new tool
give the model a new capability — say, fetching a URL or running git diff.
§04 Exercises

Five extensions to make the harness your own.

Each exercise is a self-contained task that builds on an existing extension point — Provider, Tool, Compaction, Memory, Subagent. There's no canonical solution; the value is in the trade-offs you make along the way.

§01 · exercise easy
Tool retry on error
when a tool call fails, give the model one or two structured retries before surfacing the failure to the user.
§02 · exercise medium
Markdown-defined subagents
define subagents as markdown files loaded from disk, instead of hand-rolled Go structs.
§03 · exercise medium
Pluggable memory backend
implement a second memory.Store and prove the existing harness doesn't know the difference.
§04 · exercise medium
Pluggable transcript renderer
turn the single RenderTranscript function into a Renderer interface with multiple implementations, and add an /export command.
§05 · exercise hard
Streaming responses
render the assistant's reply token by token as it streams from the model, instead of waiting for the full response.
§06 · exercise medium
Image inputs
let the user attach images to a turn so the model can describe screenshots, read diagrams, OCR text from a photo, or reason about a UI.
§05 Quickstart

Three commands. One key. Off you go.

~/projects $  bash byo-coding-agent · main 
# 1. clone the repo
git clone https://github.com/betta-tech/byo-coding-agent && cd byo-coding-agent

# 2. set a provider key (any will do)
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. run the harness
go run .

New to harness engineering? Start with §00 — what and why, then open 00-introduction and work forward.