Building a Coding Agent From Scratch

The harness, not the model, makes a coding agent good. Build one from scratch — from a bare agent loop to a swarm of cloud agents.

Open-source course by Decoding AI in collaboration with Modal, Opik (by Comet) and Kitaru (by ZenML).

Try the finished agent first — 5 minutes, $0:

# install uv first if you don't have it:  curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course.git
cd building-a-coding-agent-from-scratch-course
make install
cp .env.example .env   # set GEMINI_API_KEY — free at https://aistudio.google.com/apikey
uv run decode

Then type /demo- and pick a demo — see what they do below. Full guide: install_and_usage.md.

What opens: type /demo- and the six demos are one keystroke away.

📖 About This Course

In one public experiment by LangChain, changing only the harness — same model throughout — moved a coding agent from roughly 30th place into the top 5 on Terminal-Bench. The harness decides what the model sees, what it touches, and what happens when it's wrong. It's also the part nobody teaches.

The agent is ~20 lines. The course is everything else.

agent = Agent(
    build_model(settings.llm_provider),        # gemini | openrouter | modal
    deps_type=AgentDeps,                       # cwd, event sink, permission gate
    output_type=[str, DeferredToolRequests],   # final answer, or tools paused for approval
)
register_tools(agent)                          # read, edit, bash, grep, ...

async with agent.iter(prompt, message_history=history) as run:
    async for node in run:                     # model request → tool calls → repeat
        stream_events(node)

That's the entire tool-calling agent — the thing people call "the agent" ends here. Everything else in this repo — the permission gate, the sandbox, compaction, the steering queue, the durable runtime, the subagent fan-out, the evals — is the harness. That's what you're here to build.

We spent months under the hood of Claude Code (via its leaked source), OpenCode, Pi, and Aider, then distilled it into 8 lessons where, from an empty repo, you build decode, your own terminal coding agent. By lesson 2 it asks permission before running bash; by lesson 8 it's deployed to the cloud, building the same feature 5–10× in parallel and handing you back reviewed pull requests. One headless core, two ways to drive it: an interactive TUI wired to a live session, and a remote runtime running N copies in parallel.

Under the hood: a Pydantic AI ReAct loop on Gemini, OpenRouter, or an open model you serve on Modal; file / bash / web / LSP tools and parallel Explore subagents; Docker/Modal sandboxes; a durable Kitaru runtime; Opik tracing and evals.

You walk away with three things:

• The skill behind that leaderboard jump — engineering custom harnesses for your own AI products.
• No more magic — nothing Claude Code or Codex does is a mystery once you've built the code underneath.
• A working agent — point decode at your own repos the way you point Claude Code at them today.

Skip this layer and you're betting your work on tools you can't inspect.

The code tells you what. The lessons tell you why.

The whole repo is free: clone it, read it, ship it. But anyone can read an agent loop. The lessons cover what code can't — why steering input waits for the next model call instead of injecting mid-tool, why compaction fires at ~80% of the window instead of at the limit, why the sandbox may hold a git token while the model's context never does, why subagent fan-out caps at 6. Every component earns its place, and every lesson walks the reasoning.

Two interface modes on the left, the headless harness on the right, the evals plane underneath.

🎮 See It Work

The finished agent ships with demo skills under .decode/skills/. Open the TUI, type /demo-, pick one, and watch the harness you're about to build do real work:

A fresh session — Opik tracing on, a Modal-served Qwen, steering keys in the footer	/demo-1-terminal-arcade — one prompt, a playable Snake game
/demo-3-repo-pulse — live GitHub API data rendered as a dashboard	/demo-6-article-kg — web articles scraped into an interactive knowledge graph

And the machinery underneath is real infrastructure you'll stand up yourself, not a diagram:

Every run recorded step by step in Kitaru — kill it, resume it, replay it with the model swapped	The agent's bash runs in disposable Modal sandboxes — six live here, ~1.3s cold start
Your own Qwen3.6-35B served on an H200 via a Modal endpoint — same harness, your model	Every session traced in Opik — note the secrets scrubbed before they reach a log

🤖 You'll Walk Away Knowing How To

• Build one user turn end-to-end — prompt to streamed answer, with a y/n gate on every tool call.
• kill -9 a run mid-task and resume it — checkpoints never re-pay for finished work.
• Replay history with the model swapped — "what would gemini-2.5-pro have done from this exact point?"
• Contain the agent — four permission modes, then a Docker Workspace, then a remote Modal sandbox.
• Treat the context window as a budget — memory, compaction, skills, LSP; each a measured before/after experiment.
• Fan out parallel subagents — one call, N children, each with a budget and a report contract.
• Evaluate the thing you built — benchmarks, regression probes, online evals; a green test suite isn't enough.
• Run swarms of remote agents — a teammate labels a GitHub issue and receives a reviewed pull request.

Every lesson runs the same way: watch decode do it, then pull out the principle.

Plan mode, live: the agent breaks the Snake demo into a task list with the todo tool — [x] done, [~] in progress.

📚 Course Outline

Eight written lessons and four videos: video 2 covers lessons 2–3, video 3 covers lessons 4–6. The full codebase is already here; lessons publish progressively on Decoding AI and the links below light up as they go live.

Lesson	Written Lesson	Video Lesson	Description	Running the code
1 Building a Coding Agent From Scratch: Harness Architecture		🎬 Video 1 — coming soon	The map of every component before you write a single line of code.	install_and_usage.md
2 The Agent Loop Plugged Into the TUI (The Interactive Mode)	📄 Coming next week	🎬 Video 2 — coming soon	The ReAct loop, the core tools, and the human approving and steering every turn.	install_and_usage.md · modal_models.md
3 The Runtime: Durable Execution, HITL & Replays (The Headless Mode)	📄 Coming soon	🎬 Video 2 — coming soon	kill -9 a headless run, resume it from checkpoints, replay it with the model swapped.	runtime.md
4 Containing the Agent: Permissions & Sandbox	📄 Coming soon	🎬 Video 3 — coming soon	Four permission modes, then Docker and Modal sandboxes — nothing executes on your machine.	sandboxing.md
5 Context Engineering for Coding Agents	📄 Coming soon	🎬 Video 3 — coming soon	Memory, compaction, skills, and LSP — the context window treated as a budget.	install_and_usage.md
6 Agents Catalog, Subagents & Parallel Fan-out	📄 Coming soon	🎬 Video 3 — coming soon	One call fans out N parallel subagents, each with a budget and a report contract.	install_and_usage.md
7 Does It Work? Benchmarks, Regression & Online AI Evals	📄 Coming soon	🎬 Video 4 — coming soon	Benchmarks, regression probes, and online evals: does it work, still work, keep working?	evals.md
8 Running Swarms of Remote Agents	📄 Coming soon	No video	Deploy to GCP + Modal and build the same feature 5–10× in parallel — judged, winner merged.	credentials.md · infra.md

👥 Who Should Join?

For: engineers who learn by building. You finish with a working coding agent and patterns to steal for your own agentic applications.

🎓 Prerequisites

💰 Cost Structure

Running the code costs $0 if you stick to free tiers:

Reading-only? Everything's free!

⚙️ How It Works

Self-paced and project-based: no paywall, no certificate theater. Read the lesson on Decoding AI, run the matching code, then break it and fix it.

🏗️ Project Structure

One Python package; each module maps to one part of the architecture:

.
├── docs/
│   ├── adr/                  # Architecture Decision Records — the "why" of every choice
│   ├── glossary.md           # one canonical name per concept
│   └── evals.md              # the four-track eval suite, mapped
├── evals/                    # benchmark + regression probes + demo skills
├── tests/{unit,integration}/ # mirrors src/ 1:1; milestone capstones prove each milestone
└── src/decode/
    ├── cli.py                # Click entrypoint → launches the TUI
    ├── tui/                  # input: prompt_toolkit · output: Rich
    ├── harness/              # message queue + priority gate around the loop
    ├── agent/                # the Pydantic-AI ReAct loop (LLM ⇄ tools)
    ├── agents/               # agents catalog: Build / Plan / Code-Reviewer + Explore subagent
    ├── tools/                # file I/O, bash, web, todo, skills dispatch, LSP, ask_user
    ├── permissions/          # allow/ask/deny · modes · settings.json
    ├── sandbox/              # bash + file tools seam: none (host) / docker / modal
    ├── services/lsp/         # hand-rolled stdio LSP client (ty)
    ├── runtime/              # Kitaru durable flow: decode run / replay / HITL
    ├── context/              # compaction + conversation log (JSONL)
    ├── memory/               # AGENTS.md / MEMORY.md loading + write-back
    ├── observability/        # Opik tracing
    └── config/, entities/    # settings singleton · shared models

🚀 Running the Code

Everything lives under running_the_code/. One core guide, plus one focused guide per side quest:

🤝 Sponsors

Special thanks to Modal, Opik (by Comet), and Kitaru (by ZenML) for sponsoring this open-source course and keeping it free!

Opik and Kitaru are open source, too — star them: Opik on GitHub · Kitaru on GitHub.

💡 Questions and Troubleshooting

Open a GitHub issue for course questions, setup trouble, or concept clarifications. Known gotchas (macOS Kitaru daemon crash, non-tool-capable models, stale sandbox Workspaces) are documented inline in the running_the_code/ guides.

❓ FAQ

Do I need a paid API key?
No. The default Gemini provider has a free tier, OpenRouter routes across :free models, and Modal gives $30 in credits — see Cost Structure.

Why Python and not TypeScript or Go?
Accessibility: our audience knows Python. Claude Code, OpenCode, and Pi picked TypeScript; Go compiles to one tidy binary; and Aider proves Python can carry a serious coding agent. The course focuses on the design decisions, which transfer to any language.

Why build from scratch instead of extending Pi, DeepAgents, or an existing harness?
Because adding custom logic to an existing harness is the easy part — knowing what to add requires understanding the internals. That's the fundamentals, and it's what still makes AI engineers valuable. Build a coding agent once and you're equipped to build a custom agent for any use case.

Why is there no vector database or codebase index?
Deliberately. Memory is plain files — AGENTS.md for your instructions, MEMORY.md for what the agent learns — and the repo is explored just-in-time with grep. Fresh reads beat a stale index, and you get to see exactly what the agent knows.

🥂 Contributing

Found a bug and know the fix? Fork, fix, run make ci (no API key needed), and open a pull request. Future readers thank you 🤗

👨‍🏫 Course Author

Paul Iusztin — AI Engineer & Founder of Decoding AI After shipping 21 AI applications, Paul uses his best-selling LLM Engineer's Handbook, Decoding AI Magazine, and courses like this one to lead 160,000+ AI engineers out of demo purgatory and into production-grade engineering.

📬 Learn How to Build Coding Agents From Scratch

Join 40k+ engineers subscribed to the Decoding AI Magazine to learn to build coding agents from scratch.

⭐ One More Thing

If this course removes one layer of magic from the tools you use every day, star the repo — stars are how other engineers find it. And tell us which part of your coding agent is still a black box to you — open an issue; we read every one.

License

Released under Apache-2.0 — clone, fork, and build on it; keep the LICENSE and credit this repo.