decode Free open-source course

Building a Coding Agent From Scratch

Learn harness engineering by building Claude Code from scratch.

From a bare-bones agent loop to a swarm of cloud agents.

Open-source harness engineering course
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 (the tools, skills, permission layer, sandbox, steering queue, memory, compaction, session recording & replay, remote execution, subagent fan-out, and evals) is the harness.

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. Six Videos.

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

What the essential components of a coding agent are, and what is optional.

Why we have a headless harness and two interface modes: TUI + Remote.

Why we plugged in 9 tools, no more, no less.

What guardrails are actually useful.

Why compaction fires at ~80% of the window instead of at the limit.

Why subagents are context engineering: scoped windows instead of one bloated context.

Why your agents should keep working after you close your laptop lid.

Why you need both benchmarks and regression tests.

Why we record every run, and what a replay buys you that a re-run doesn't.

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/                    # benchmark tasks + regression cases + the Opik harness
├── scripts/                  # operator scripts: Kitaru bootstrap + eval table generation
├── 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/              # plain headless decode run + the Recording Seam
    ├── remote/               # decode remote deploy|run|attempts|logs — the Modal Headless App (CLI, webhook, cron)
    ├── context/              # compaction + conversation log (JSONL)
    ├── memory/               # AGENTS.md / MEMORY.md loading + write-back
    ├── observability/        # Opik tracing
    └── config/, entities/    # settings singleton · shared models