Preface

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

You have tried the frameworks—and watched your LangChain app hallucinate its way into deleting a production database. And you think: “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
• Separate planning from execution with a safety mode
• Search the web for documentation and answers

You will build it from scratch using requests, python-dotenv, and pytest; shell access comes from Python’s standard-library subprocess module. No LangChain. No vector databases. No “orchestration frameworks.” Just Python you can debug with print().

Chapter 11 adds ddgs for web search. The Snake capstone also uses pygame-ce, which supplies import pygame; it is separate from the agent’s dependencies. Use Python 3.15 for this edition, with 3.12 as the tested minimum. The setup pins the package versions used to verify these examples.

This book uses a “test-alongside” approach. For most features:

1. We introduce the concept—why we need this
2. We show the test first, so you know what success looks like
3. We implement the code to make the test pass
4. We verify with pytest

This teaches Test-Driven Development thinking without the full red-green-refactor ceremony in print. Live API calls make unit tests slow, expensive, and unpredictable. Keep those calls for separate integration tests and model evaluations.

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/, ch03/, ch04/, etc.) plus an appendix/ folder. Most folders contain:

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

Two exceptions: ch02/ contains only a standalone test_api.py script (used once and discarded), and ch12/’s agent snapshot is functionally the same as ch11/. You generate the capstone game while working through Chapter 12.

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.

Sample sessions are illustrative. Thinking and progress messages may be shortened, and bracketed tool labels annotate actions rather than reproduce the exact console format. Tool results shown in a session explain what the model receives; the non-streaming agent does not print every tool’s returned content directly.

Time to write some code.