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

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.

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

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.

🎮 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 infra that powers the agents:

🤖 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

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