Building a Coding Agent From Scratch

$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. Full guide: install_and_usage.md.

##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.

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

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

##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.

##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.

##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!

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.

##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.

##FAQ

##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.