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. Everything else in this repo: the tools, skills, the permission layer, sandbox, steering queue, memory, compaction, session recording & replay, 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 Modal serverless functions running N copies in parallel, fired by CLI, webhook, or cron.

<p align="center"> <img src="assets/architecture.png" alt="Diagram of a coding agent harness: two interfaces (Interactive TUI with steering queue and priority gate; Remote Modal runtime running N headless harnesses via CLI, webhook, or cron) drive one Headless Harness made of a Context Window with compaction, an LLM-to-Tools Agent Loop, and six modules (LLM Providers, Memory, Skills, Sandbox, Permissions, LSP Server). An Evals and Observability layer (benchmarks, regressions, replays via Opik and Kitaru) sits underneath." width="620"> </p> <p align="center"><i>The architecture of the harness of the coding agent you will build during this course.</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> <p align="center"> And the infra that powers the agents. </p> <table> <tr> <td width="50%"> <img src="assets/kitaru-replay.png" alt="An agent run recorded step by step as a Kitaru Session"/> <p align="center"><b>Record & 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> — replay it on a Kitaru Worker with the model swapped, then compare the two runs</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
• Deploy the headless harness on Modal and fire N parallel attempts at one task from the CLI, a webhook, or a cron job
• Record every run with Kitaru and replay it with the model or prompt swapped, tool outputs served from the recording, against the original as baseline
• 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

<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).
• Session Recording & Replays: Kitaru
• Observability & Evals: Opik
• Sandboxing: local Docker & remote Modal sandboxes
• Deploying: Modal as headless agents (fired by hand, by cron, or by webhook)

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 record every run, and what a replay buys you that a re-run doesn't.
• What guardrails are actually useful.
• Why compaction fires at ~80% of the window instead of at the limit.
• Why you need both benchmarks and regression tests.

📚 Course Outline

<table> <tr> <th align="center">Lesson</th> <th align="center">Written Lesson</th> <th align="center">Video Lesson</th> <th align="center">Running the code</th> </tr> <tr> <td align="center"><b>1</b><br/>Building a Coding Agent From Scratch</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="300" alt="Lesson 1 — the harness architecture"/></a><br/><i><a href="https://www.decodingai.com/p/building-a-coding-agent-from-scratch-system-design" target="_blank">Article 1</a></i></td> <td align="center" rowspan="2"><a href="https://www.youtube.com/watch?v=sJpop1juVBQ" target="_blank"><img src="assets/thumbnail_video_1.jpg" width="600" alt="Video 1 — the video version of lessons 1 and 2"/></a><br/><i><a href="https://www.youtube.com/watch?v=sJpop1juVBQ" target="_blank">Video 1</a></i></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_endp