Preface

You are a software engineer who is skeptical of AI hype.

You have seen the demos. You have tried the frameworks. You have watched your LangChain app hallucinate its way into deleting a production database. And you thought: “There has to be a better way.”

There is. This book is for developers who want to understand what is actually happening when an AI agent runs. Not the marketing diagrams. Not the “Reasoning Engine” abstractions. The actual HTTP requests. The actual while loop.

If you can read Python and have built a web app or CLI tool before, you have everything you need.

Nanocode is a coding agent that runs in your terminal. By the end of this book, it will:

• Read and write files in your codebase
• Execute shell commands
• Search code using pure Python
• Remember context across sessions
• Ask for permission before dangerous operations
• Search the web for documentation and answers

You will build it from scratch using only requests, subprocess, and pytest. No LangChain. No vector databases. No “orchestration frameworks.” Just Python you can debug with print().

The one exception: Chapter 11 adds ddgs for web search—a single lightweight dependency.

This book uses a test-alongside approach. For each feature:

1. We introduce the concept (why we need this)
2. We show the test first (what success looks like)
3. We implement the code (make the test pass)
4. We verify with pytest (prove it works)

This teaches Test-Driven Development thinking without tedious red-green-refactor cycles in print. More importantly, it solves a critical problem: you cannot test an LLM-powered application by actually calling the LLM. API calls are slow, expensive, and non-deterministic.

Starting in Chapter 3, we introduce the FakeBrain pattern—a test double that returns predictable responses. This lets you run your entire test suite without making a single API call or spending a single cent.

This book follows a “Code First” approach. Each chapter builds on the previous one, and every code example is extracted from working files.

To get the code:

• GitHub: Clone or download from GitHub.¹
• Leanpub: The complete source code is also included in the downloadable resources with your purchase.

The code is organized by chapter (ch01/, ch02/, etc.). Each folder contains:

• nanocode.py — The complete, runnable agent for that chapter
• test_nanocode.py — Tests that verify the code works without API calls

You can copy any chapter folder and pick up from there. Run pytest to verify your code matches the expected behavior.

Throughout the book, you will see three types of callouts:

Code walkthroughs follow a consistent pattern: first the context (why we need this code), then the code itself, then a line-by-line explanation of the important parts.

Let’s build.