Introduction

“What I cannot create, I do not understand.” - Richard Feynman

If you follow AI news, you are drowning in options. It feels like every day someone drops a new agent framework, new harness, or a library that brings exciting features. Someone else builds cool demos and shows off how well it works. It is exhausting trying to keep up, and even worse is that relying on someone else’s frameworks and abstractions leaves a critical gap in your own knowledge.

I learned this the hard way. A couple of years ago, LangChain was the framework that everyone was talking about. I used it and built a project with it. But I wasn’t satisfied with just using it and wanted to know how it works. I rewrote the project without it, and not only did I learn a lot, but I also ended up with simpler code that was easier to read and debug.

That is exactly what this series is about: first-principle learning.

Instead of figuring out how to use a trending agent harness, we are going to learn how coding agents work by building one from scratch.

What You Will Build

By the end of this series, you will have built a terminal based agent similar to Claude Code, Codex, or Pi. In the process of coding it, you will learn about:

• How the agent loop works
• How an agent calls tools
• How to integrate skills and AGENTS.md
• How to persist sessions
• And much more

The Stack: Zero Dependencies

Because the goal of this series is deep understanding, we’ll not use any SDKs or frameworks.

• Language: Everything is written in Go. However, because we don’t use SDKs or frameworks, you can easily translate the concepts and build this in Python, Rust, TypeScript, or any language you prefer. It is actually a good exercise to convert it as you read along.
• Models: We are keeping everything local and free and that includes the models. We’ll use two local models via Ollama:
  • qwen3.6:27b or qwen3.6:27b-mlx on Mac
  • gemma4:e4b or gemma4:e4b-mlx on Mac

When you ready to start building loom, out coding agent, below is the list of lessons.

Table of Contents

1. Lesson 1: The Agent Loop What a coding agent actually is under the hood: a stateless LLM plus a loop that sends the conversation, acts on the reply, and appends the result. Builds loom’s skeleton: the send → act → append loop every later lesson builds on.

2. Lesson 2: Tool Calling Why a model can’t touch your filesystem on its own, and how tool calling turns token output into a structured request your code executes. Adds the first tool, read_file, wired through Ollama’s tool_calls protocol.

3. Lesson 3: The Tool Suite Why switch-statement dispatch breaks down as tools grow, and how a self-describing registry fixes it. Builds a tool registry, plus two new tools: list_files and bash.

4. Lesson 4: The Edit Tool The tradeoffs between whole-file rewrites, line-number edits, and diffs, and why exact-string replacement wins. Builds an edit_file tool that replaces old_string with new_string only when the match is unique.

5. Lesson 5: The System Prompt What real agents put in a system prompt (identity, environment, working rules) and why the model can’t infer any of it on its own.

6. Lesson 6: Streaming and UX Why silent multi-second waits make an agent feel broken, and how streaming changes that. Adds token-by-token streaming output from Ollama’s /api/chat.

7. Lesson 7: Safety and Permissions How an unchecked bash tool becomes an attack surface including prompt injection hidden in a file the agent reads. Builds a permission layer that gates unsafe tool calls behind user approval.

8. Lesson 8: Compaction Why a fixed-size context window silently drops old tokens (including the system prompt) once it fills up. Adds automatic compaction that summarizes and rewrites the conversation window before it overflows.

9. Lesson 9: Slash Commands) Why command handling belongs in the harness, not the model’s conversation. Adds /compact, /context, /help, and /clear, a command registry parallel to the tool registry.

10. Lesson 10: AGENTS.md, Skills, and The Trust Store How agents pick up project conventions (AGENTS.md) and on-demand procedures (skills), and why that requires a trust boundary. Builds AGENTS.md loading, a skills system, and a Trust Store that gates both before they reach the system prompt.

11. Lesson 11: Sessions and Persistence Why the in-memory conversation array isn’t the same thing as “the conversation,” and how to make sessions durable. Builds a JSONL event log per session, plus /resume and /fork to reload or branch past sessions.