building-a-coding-agent-from-scratch-course

<div align="center"> <img src="assets/coding-agent-logo.png" alt="decode logo" width="140"> <h1>Building a Coding Agent From Scratch</h1> <h3>The harness, not the model, makes a coding agent good. Build one from scratch, from a bare-bones agent loop to a swarm of cloud agents.</h3> <p class="tagline">Open-source course by <a href="https://www.decodingai.com">Decoding AI</a> in collaboration with <a href="https://modal.com?source=decodingai&campaign=harnesseng">Modal</a>, <a href="https://www.comet.com/site/?utm_source=workshop&utm_medium=partner&utm_campaign=paul&utm_content=coding_agent_course">Opik (by Comet)</a> and <a href="https://www.zenml.io/product/kitaru?utm_source=decodingai&utm_medium=referral&utm_campaign=coding-agent-course&utm_content=brand">Kitaru (by ZenML)</a>.</p> </div> <p align="center"> <img src="https://img.shields.io/badge/type-open--source_course-8a2be2" alt="Open-source course"> <img src="https://img.shields.io/badge/cost_to_run-%240-2ea44f" alt="$0 to run"> <img src="https://img.shields.io/badge/articles-8-4c8eda" alt="8 articles"> <img src="https://img.shields.io/badge/videos-4-ff0000" alt="4 videos"> <img src="https://img.shields.io/badge/code-from_scratch-orange" alt="Code from scratch"> <img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey" alt="Apache-2.0 license"> </p> <p align="center"> <img src="assets/demo-frames.gif" alt="decode in the terminal" width="800"> </p>

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

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 LLM API key
uv run decode

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

<p align="center"> <img src="assets/demo-skills.png" alt="The demo skills listed inside the decode TUI after typing /demo-" width="800"> </p> <p align="center"><i>Type <code>/demo-</code> and the six demos are one keystroke away.</i></p>

📖 About This Course

In LangChain's Terminal-Bench experiment, changing only the harness (with the same model) moved a coding agent from ~30th place into the top 5: the harness, not the model, is what makes a coding agent good.

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 tools, skills, the permission layer, sandbox, steering queue, memory, compaction, durable runtime, remote execution, the subagent fan-out, the evals — is the harness. That's what you're here to build.

<p align="center"> <img src="assets/tui-session-start.png" alt="A fresh decode session: Opik tracing on, a Modal-served Qwen model, skill autocomplete, steering keys in the footer" width="90%"/> <br/> <i>A fresh session powered by Qwen 3.6 35B hosted on Modal</i> </p>

We spent months under the hood of Claude Code (via its leaked source), OpenCode, Pi, and Aider, then distilled it into 8 articles and 4 videos where you'll build decode, your own coding agent, from scratch — one headless core hooked to two modes: an interactive TUI and a remote runtime running N copies in parallel.

<p align="center"> <img src="assets/architecture.png" alt="decode architecture" width="620"> </p> <p align="center"><i>Two interface modes on the left, the headless harness on the right, the evals plane underneath.</i></p>

🎮 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:

<p align="center"> <img src="assets/demo-skills.png" alt="The demo skills listed inside the decode TUI after typing /demo-" width="90%"/> <br/> <b>Implement the Skills Standard</b> <br/> <i>Type <code>/demo-</code> and the six demos are one keystroke away.</i> </p> <table> <tr> <td width="50%"> <img src="assets/demo-snake-game.png" alt="A playable Snake game built by decode"/> <p align="center"><b>Capable of Creating Games</b><br/><i><code>/demo-1-terminal-arcade</code> — one prompt, a playable Snake game</i></p> </td> <td width="50%"> <img src="assets/demo-repo-pulse.png" alt="Live GitHub repo data rendered as a web dashboard"/> <p align="center"><b>Fetching Data & Creating Dashboards</b><br/><i><code>/demo-3-repo-pulse</code> — live GitHub API data rendered as a dashboard</i></p> </td> </tr> <tr> <td colspan="2" align="center"> <img src="assets/demo-knowledge-graph.png" alt="An interactive knowledge graph scraped from web articles" width="90%"/> <p align="center"><b>Extracting Ontologies & Rendering Graphs</b><br/><i><code>/demo-6-article-kg</code> — web articles scraped into an interactive knowledge graph</i></p> </td> </tr> </table>

And the infra that powers the agents:

<table> <tr> <td width="50%"> <img src="assets/kitaru-replay.png" alt="A durable run recorded step by step in Kitaru"/> <p align="center"><b>Durability & Replay for AI Agents</b><br/><i>Every run recorded step by step in <a href="https://www.zenml.io/product/kitaru?utm_source=decodingai&utm_medium=referral&utm_campaign=coding-agent-course&utm_content=brand">Kitaru</a> — kill it, resume it, replay it with the model swapped</i></p> </td> <td width="50%"> <img src="assets/modal-sandboxes.png" alt="Live Modal sandboxes executing the agent's tools"/> <p align="center"><b>Remote Sandboxing</b><br/><i>The agent's <code>bash</code> runs in disposable <a href="https://modal.com/docs/guide/sandboxes?source=decodingai&campaign=harnesseng">Modal sandboxes</a></i></p> </td> </tr> <tr> <td width="50%"> <img src="assets/modal-open-model.png" alt="A self-served open model endpoint on Modal"/> <p align="center"><b>Powered by Open Source Models</b><br/><i>Your own Qwen3.6-35B served on an H200 via a <a href="https://modal.com/docs/guide/endpoints?source=decodingai&campaign=harnesseng">Modal endpoint</a></i></p> </td> <td width="50%"> <img src="assets/opik-threads.png" alt="Sessions traced in Opik with secrets scrubbed"/> <p align="center"><b>Adding AI Evals & Observability</b><br/><i>Every session traced in <a href="https://www.comet.com/site/?utm_source=workshop&utm_medium=partner&utm_campaign=paul&utm_content=coding_agent_course">Opik</a></i></p> </td> </tr> </table>

🤖 You'll Walk Away Knowing How To

• Design a coding agent harness from scratch
• Implement a headless coding agent loop
• Attach the headless harness to multiple modes: TUI and remote
• Add a runtime for durable execution, human-in-the-loop and replays when running parallel agents
• Implement guardrails and safety nets for the agent's behavior by adding a permission layer and local & remote sandboxing
• Build essential context engineering techniques: memory, compaction, skills
• Hook up an LSP server for faster feedback loops
• Implement an agents catalog: build, plan, code reviewer and exploration agents
• Spawn parallel subagents via fan-out strategies
• Add observability
• Design an eval harness for benchmarking the agent and checking for regressions
• Deploy and run swarms of agents

<p align="center"> <img src="assets/tui-plan-mode-todo.png" alt="decode in plan mode breaking the Snake demo into a task list with the todo tool" width="800"> </p> <p align="center"><i>Plan mode, live: the agent breaks the Snake demo into a task list with the <code>todo</code> tool — <code>[x]</code> done, <code>[~]</code> in progress.</i></p>

Tech Stack

The code is written in Python, with the following frameworks and libraries:

• Agent Framework: Pydantic AI
• LLM Providers: Modal (open weights you serve yourself via SGLang), OpenRouter (open weights as a service), or Gemini (proprietary).
• Durable Runtime & Replays: Kitaru
• Observability & Evals: Opik
• Sandboxing: local Docker & remote Modal sandboxes
• Deploying: GCP & Modal

Otherwise, we build all the functionality from scratch, to teach you the foundations that last, not frameworks that abstract away the hard parts.

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

For the full experience, go through the articles and videos that cover what the code can't. The why behind every decision.

Why we have a headless harness and two interface modes: TUI + Remote. What the essential components of a coding agent are, and what is optional. Why we plugged in 9 tools, no more, no less. Why we need a durable runtime and replays. What guardrails are actually useful. Why compaction fires at ~80% of the window instead of at the limit. Why you need benchmarks, regression tests and online evals.

📚 Course Outline

<table> <tr> <th align="center">Lesson</th> <th align="center">Written Lesson</th> <th align="center">Video Lesson</th> <th align="center">Description</th> <th align="center">Running the code</th> </tr> <tr> <td align="center"><b>1</b><br/>Building a Coding Agent From Scratch: Harness Architecture</td> <td align="center"><a href="https://www.decodingai.com/p/building-a-coding-agent-from-scratch-system-design" target="_blank"><img src="assets/architecture.png" width="250" alt="Lesson 1 — the harness architecture"/></a></td> <td align="center">🎬 <i>Video 1 — coming soon</i></td> <td align="center">Designing the harness around the model, from the agent loop to a remote swarm.</td> <td align="center"><a href="running_the_code/01_install_and_usage.md">01_install_and_usage.md</a> · <a href="running_the_code/02_modal_endpoints.md">02_modal_endpoints.md</a></td> </tr> <tr> <td align="center"><b>2</b><br/>The Bare-Bones Coding Agent Loop</td> <td align="center"><a href="https://www.decodingai.com/p/the-coding-agent-loop" target="_blank"><img src="assets/architecture_lesson_2.png" width="250" alt="Lesson 2 — the bare-bones coding agent loop"/></a></td> <td align="center">🎬 <i>Video 2 — coming soon</i></td> <td align="center">One agent loop, 9 tools, and a terminal you can steer.</td> <td align="center"><a href="running_the_code/01_install_and_usage.md">01_install_and_usage.md</a> · <a href="running_the_code/02_modal_endpoints.md">02_modal_endpoints.md</a></td> </tr> <tr> <td align="center"><b>3</b><br/>The Runtime: Durable Execution, HITL & Replays (The Headless Mode)</td> <td align="center">📄 <i>Coming soon</i></td> <td align="center">🎬 <i>Video 2 — coming soon</i></td> <td align="center"><code>kill -9</code> a headless run, resume it from checkpoints, replay it with the model swapped.</