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

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.

📖 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