Building a Coding Agent From Scratch: An Open-Source Python Course on Agent Harness Design

The core thesis: the harness, not the model, makes a coding agent good

The course opens with a reference to LangChain's Terminal-Bench experiment, cited in the README: changing only the harness, while keeping the same model, moved a coding agent from approximately 30th place to the top 5. The course uses this as evidence that the harness (tools, permissions, memory, context engineering, sandboxing, and evals) is the primary determinant of coding agent quality, not the model.

This framing shapes the entire curriculum. The course teaches the harness layer, not the model layer. The 20-line agent loop at the core of decode is intentionally simple. The README shows the full agent definition:

agent = Agent(
    build_model(settings.llm_provider),
    deps_type=AgentDeps,
    output_type=[str, DeferredToolRequests],
)
register_tools(agent)

Everything else in the repository (tools, skills, permission layer, sandbox, memory, compaction, session recording and replay, remote execution, subagent fan-out, evals) is the harness. The course's job is to explain and build each of these components.

The course authors describe spending months studying the leaked Claude Code source code, OpenCode, Pi, and Aider before distilling their findings into the curriculum.

Quick start: running the finished agent before the first lesson

The README instructs learners to try the finished agent first before starting the course. This takes about five minutes and costs nothing if using the free Gemini tier:

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
uv run decode

The make install command installs the Python environment from pyproject.toml using uv and wires git hooks via pre-commit. After setting at least one LLM API key in .env, uv run decode launches the TUI. The .env.example documents three provider options: Gemini (GEMINI_API_KEY, free from Google AI Studio), OpenRouter (OPENROUTER_API_KEY, with a free router for zero-cost use), and Modal (for self-hosted open weights on an H200).

Inside the TUI, typing /demo- and selecting from the six demo options runs the agent on a pre-defined task. The README demonstrates that the first demo, /demo-1-terminal-arcade, produces a playable Snake game from a single prompt.

The decode agent architecture and what you will build

The finished agent has two operating modes: an interactive TUI and a headless remote mode on Modal. The headless mode runs N copies of the agent in parallel, fired by CLI, webhook, or cron job.

The course teaches the full harness: a permission layer that gates tool calls before execution, local and remote sandboxing (the agent's bash tool can run in a disposable Modal sandbox), memory and context compaction to keep sessions within model context limits, skills (reusable prompt sets the agent can load for specific task types), session recording and replay via Kitaru, parallel subagent fan-out strategies, LSP server integration for faster feedback on code edits, and an eval harness for benchmarking and regression testing.

The README describes an agents catalog built during the course: build agents, plan agents, code reviewer agents, and exploration agents. The Makefile exposes eval commands:

make eval-benchmark
make eval-regression-dataset

The eval harness integrates with Opik by Comet for observability: every session trace is logged, and regression cases can be run against an Opik dataset with configurable pass/fail thresholds.

The six demo skills and what the agent can do out of the box

The finished decode agent ships six demo skills in .decode/skills/. The README describes what each demonstrates.

Demo 1 (/demo-1-terminal-arcade): implements a playable Snake game in the terminal from a single prompt. Demo 3 (/demo-3-repo-pulse): fetches live GitHub API data and renders it as a dashboard. Demo 6 (/demo-6-article-kg): scrapes web articles and builds an interactive knowledge graph from the extracted ontologies.

Three infrastructure demos show the harness capabilities. One demonstrates the Kitaru integration: every run is recorded step by step and can be replayed with the model swapped, then compared against the original run. Another demonstrates remote sandboxing: the agent's bash tool runs in a disposable Modal sandbox. A third demonstrates serving a self-hosted Qwen 3.6 35B model on an H200 via a Modal endpoint and using it as the coding agent's inference backend.

These demos function as end-to-end tests of the harness: they run real tasks with real code execution rather than simulated interactions.

Course content and the technical stack

The course is structured as 8 articles and 4 videos, all published by Decoding AI at decodingai.com. The repository is the companion codebase for those articles. The curriculum topics, from the README's 'you will walk away knowing how to' section, include: designing a coding agent harness from scratch, implementing a headless agent loop, attaching the harness to a TUI and to remote Modal functions, deploying on Modal and firing parallel attempts from CLI or webhook, recording runs with Kitaru and replaying with models swapped, implementing guardrails through a permission layer and sandboxing, building memory and compaction, connecting an LSP server, implementing an agents catalog, spawning parallel subagents, adding observability, and designing an eval harness.

The technical stack uses Pydantic AI as the agent framework. LLM provider support covers Gemini through the AI SDK, OpenRouter as a hosted routing layer, and Modal for self-hosted open-weight inference. The pyproject.toml pins pydantic-ai-slim to versions 2.46 through 2.47 (an ADR-documented stability window). Observability integrates Logfire and Opik. Session recording uses Kitaru 0.27.0 or newer with a dedicated pydantic-ai adapter.

Limitations and what the course does not cover

The course requires Python 3.12 or newer. The pyproject.toml classifiers show support for Python 3.12 and 3.13. Python 3.11 and earlier are not supported. The uv package manager is required; using pip alone without uv may work but is not the tested path.

The course assumes the learner wants to build with Pydantic AI specifically. It does not cover LangChain, LlamaIndex, or other agent frameworks. Teams already invested in a different framework will find the harness concepts relevant but the code examples not directly transferable.

Remote sandbox execution and the Modal inference endpoint require a Modal account and incur compute costs. The free Gemini tier and the OpenRouter free router cover the LLM inference cost for basic exercises, but Modal sandboxes and H200 inference are paid resources.

The course is produced by Decoding AI, an independent publication, in collaboration with Modal, Opik (by Comet), and Kitaru (by ZenML) as documented in the README. The repository is actively maintained with a last push on 2026-09-25. There are no GitHub releases; the course materials and code evolve together as a single versioned codebase. The license is Apache 2.0, covering both the course code and the decode agent itself. The project uses a .pre-commit-config.yaml for code quality hooks, enforced through make install, so contributors need pre-commit installed.

Editorial conclusion

Python developers who want to understand what makes a coding agent effective at the implementation level, rather than just calling a framework, will find this course unusually specific: the curriculum dissects the harness (tools, permissions, memory, context engineering, sandboxing, evals) rather than treating these as solved problems. The course requires Python 3.12 or newer, uv, and at least one LLM provider key; Gemini's free tier is the fastest start. Teams who want a production-ready agent without writing the harness themselves will find the finished decode agent useful as a starting point, but the primary value is the 8-article explanation of why each piece is built the way it is. The last push was on 2026-09-25.

Frequently asked questions

Official sources

1. decodingai-magazine/building-a-coding-agent-from-scratch-course on GitHub
2. Issues
3. License: Apache-2.0
4. README