decode Free open-source course

Building a Coding Agent From Scratch

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.

By Decoding AI, in collaboration with Modal, Opik (by Comet), and Kitaru (by ZenML).

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

That's the entire tool-calling agent. Everything else in this repo is the harness: tools, skills, permissions, sandbox, steering, memory, compaction, durable runtime, subagents, evals.

That's what you're here to build.

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)

Eight Lessons. Four Videos.

From designing the harness to deploying a swarm of remote agents.

Why a headless harness with two interface modes, TUI and 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.

One Module Per Concept.

One Python package; each module maps to one part of the architecture.

.
├── docs/
│   ├── adr/                  # Architecture Decision Records — the "why" of every choice
│   ├── glossary.md           # one canonical name per concept
│   └── evals.md              # the four-track eval suite, mapped
├── evals/                    # benchmark + regression probes + demo skills
├── tests/{unit,integration}/ # mirrors src/ 1:1; milestone capstones prove each milestone
└── src/decode/
    ├── cli.py                # Click entrypoint → launches the TUI
    ├── tui/                  # input: prompt_toolkit · output: Rich
    ├── harness/              # message queue + priority gate around the loop
    ├── agent/                # the Pydantic-AI ReAct loop (LLM ⇄ tools)
    ├── agents/               # agents catalog: Build / Plan / Code-Reviewer + Explore subagent
    ├── tools/                # file I/O, bash, web, todo, skills dispatch, LSP, ask_user
    ├── permissions/          # allow/ask/deny · modes · settings.json
    ├── sandbox/              # bash + file tools seam: none (host) / docker / modal
    ├── services/lsp/         # hand-rolled stdio LSP client (ty)
    ├── runtime/              # Kitaru durable flow: decode run / replay / HITL
    ├── context/              # compaction + conversation log (JSONL)
    ├── memory/               # AGENTS.md / MEMORY.md loading + write-back
    ├── observability/        # Opik tracing
    └── config/, entities/    # settings singleton · shared models