Building a Coding Agent From Scratch: The Decoding AI Course Reviewed
From agent user to agent builder: build a Claude Code-style coding agent from scratch in Python: 8 articles, 4 videos, one codebase
At a glance
- What is it?
- A free, Apache-2.0 Python course that builds a Claude Code-style coding agent called decode, from a 20-line agent loop to remote Modal sandboxes. Here is what the repository actually contains, and where it stops.
- Who is it for?
- Adopt this if you already write Python and want to see the harness around a tool-calling loop: permissions, compaction, sandboxing, evals. Skip it if you want a production agent to deploy next week, or if you need a support contract, since the repository is a course artifact with no release tags.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the Decoding AI course actually ships
The repository is the artifact of a course by Decoding AI, built with Modal, Opik (by Comet) and Kitaru (by ZenML). It is not a library you import into another project. It is a working terminal coding agent named decode, plus the teaching material that explains how each part of it was assembled: 8 articles and 4 videos, according to the README badges.
The stated thesis is blunt. The README quotes LangChain's Terminal-Bench experiment, where changing only the harness with the same model moved a coding agent from around 30th place into the top 5. From that the course draws its premise: the harness, not the model, makes a coding agent good. The README repeats the claim in its own words, and the whole structure follows from it.
The audience is therefore narrow and specific. This is for engineers who have used Claude Code, OpenCode, Aider or Pi and now want to know what sits between the prompt and the file edit. The README says the authors spent months under the hood of Claude Code (via its leaked source), OpenCode, Pi and Aider, then distilled that into the course. If you have never written a tool-calling loop, the early articles are the on-ramp. If you want a finished product to install and forget, this is the wrong repository.
The 20-line agent and the harness around it
The README makes a claim that is easy to check and hard to argue with: the agent itself is about 20 lines. It shows the whole tool-calling core as an Agent constructed with a model, a deps type carrying the working directory, an event sink and a permission gate, and an output type that is either a string or deferred tool requests. Then `register_tools(agent)` adds read, edit, bash, grep and the rest, and an async loop over `agent.iter` streams events as the model requests tools and gets results back.
Everything else is the harness. The README lists the pieces: tools, skills, the permission layer, sandbox, steering queue, memory, compaction, session recording and replay, remote execution, subagent fan-out, and evals. The architecture diagram in the repository shows two interfaces driving one headless core. On one side is the interactive TUI with a steering queue and a priority gate. On the other is a remote Modal runtime running N headless harnesses, fired by CLI, webhook or cron. Both sit on the same headless harness, which contains a context window with compaction, the LLM-to-tools agent loop, and six modules: LLM providers, memory, skills, sandbox, permissions and an LSP server. Underneath that is an evals and observability layer for benchmarks, regressions and replays, wired to Opik and Kitaru.
That layout is the honest answer to what a coding agent is. The interesting engineering is in compaction, in deciding when a tool call needs approval, and in running the same loop in a disposable remote sandbox. The model call is the small part.
Installing decode and running your first demo
The README gives a five-minute, zero-cost path to the finished agent before you read any article. Clone the repository, run `make install`, copy the environment file and set one API key, then launch the TUI with `uv run decode`.
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 decodeThe `make install` recipe runs `uv sync` and then installs pre-commit hooks for both pre-commit and pre-push, so the toolchain is wired the first time. The project requires Python 3.12 or newer and declares 3.12 and 3.13 classifiers in `pyproject.toml`. The `decode` command itself is registered as a console script pointing at `decode.cli:cli`.
Provider selection happens in `.env`. The commented default is `LLM_PROVIDER=gemini`, which the file describes as one free key and the fastest start, with a rate-limited free tier. The other two options are `modal`, which the file marks as recommended because you serve an open-weights model yourself with no rate limits, and `openrouter`, where the `openrouter/free` router costs nothing. For Gemini you paste a key from the AI Studio link the file gives. For Modal the authentication is separate from `.env`:
uv run modal token set --token-id <token-id> --token-secret <token-secret>Once the TUI is open, the README says to type `/demo-` and pick one of six demo skills shipped under `.decode/skills/`. You should see the skill list appear as autocomplete. The documented demos include `/demo-1-terminal-arcade`, a playable Snake game from one prompt, `/demo-3-repo-pulse`, which renders live GitHub API data as a dashboard, and `/demo-6-article-kg`, which scrapes web articles into an interactive knowledge graph. If you would rather have `decode` on your PATH permanently, `make install-cli` runs `uv tool install --editable .` and the Makefile notes you may need `uv tool update-shell` if the command is not found.
Where decode stops being the right tool
This is a course artifact, and the packaging reflects that. There are no releases retrieved for the repository, and `pyproject.toml` pins the project at version 0.1.0. If your workflow depends on semantic version tags, changelogs or a migration path between versions, there is nothing here to depend on.
The dependency set is also deliberately provisional. The `pyproject.toml` comments say the runtime dependencies are kept light on purpose because the course adds heavier integrations at the step that needs them. It pins `pydantic-ai-slim[google,openai]` to `>=2.40,<2.41`, with a comment explaining that this is the window the kitaru-pydantic-ai adapter supports, whose own cap is below 2.41. That is a narrow band. If you want to build on a newer pydantic-ai, you are working against the course's constraint, not with it.
The evals are a second boundary. The Makefile marks the benchmark and regression recipes as costing money and never running in CI, and each one first checks for API keys and skips in a friendly way when they are absent. So the evaluation layer is something you run deliberately with your own provider key, not a gate that protects every commit. Anyone expecting a continuously verified agent will be disappointed by that design.
Finally, the course is opinionated about infrastructure. The remote execution path goes through Modal, observability through Opik, and session record and replay through Kitaru. Those are real dependencies, not illustrations. If your organization cannot use those services, the later articles are still readable but the runnable artifacts will not match your environment. The README does not document a rollback or migration path for any of this, and no alternative backends are listed.
How it differs from Aider and OpenCode
The obvious comparison is Aider or OpenCode, and the README invites it by naming both, along with Pi, as the projects the authors studied. The difference is not features. It is intent.
Aider and OpenCode are tools you install and use. Their value is in the editing loop, the git integration, the model support, and the accumulated handling of edge cases that comes from being used daily. You adopt them, you configure them, and the internals stay internal unless something breaks.
This repository is the opposite trade. It gives you the internals and asks you to assemble them. The README's own framing is that the agent is roughly 20 lines and the course is everything else, so the deliverable is understanding of the harness, not a polished daily driver. You get the permission layer as something you wrote, the compaction strategy as something you chose, and the sandbox as something you wired to Modal. What you do not get is years of bug reports from other users.
There is also a structural difference in how the agent runs. The README describes one headless core with two modes: an interactive TUI, and Modal serverless functions running N copies in parallel, triggered by CLI, webhook or cron. That second mode is a fan-out design. Aider and OpenCode are shaped around a single interactive session. If you want to run many agent instances headlessly and compare their runs, the architecture here is aimed at exactly that, with Kitaru recording each run step by step for replay with the model swapped.
Licence, maintenance and upgrade cost
The repository is licensed Apache-2.0, declared in both the LICENSE file and the `pyproject.toml` license field, with the classifier for the Apache Software License. That is a permissive licence, and the practical consequence for a course artifact is that you can copy the code into your own project, including a commercial one, provided you keep the required notices. This is a description of what the licence says, not legal advice, and if the distinction matters to your employer you should have counsel read it rather than this paragraph.
One thing worth noting about the codebase's own provenance: the README states the authors studied Claude Code via its leaked source. The licence here covers this repository's code. It says nothing about the terms attached to any other project's source that informed the design, and the README does not address that question.
On maintenance, the last push to the default branch was on 2026-09-17, and the repository is not archived. The dependency comments reference ADR numbers, including ADR-0019, ADR-0021 and ADR-0022, which suggests active internal decision-making at the time of that push. The upgrade cost is the real consideration. Because `pydantic-ai-slim` is pinned inside a narrow minor window tied to the Kitaru adapter, and because the runtime dependencies are intentionally sparse with heavier integrations added per course step, tracking upstream will mean revisiting those pins rather than bumping a version number. Budget for that if you intend to keep a fork alive.
Editorial conclusion
Adopt this if you already write Python and want to see the harness around a tool-calling loop: permissions, compaction, sandboxing, evals. Skip it if you want a production agent to deploy next week, or if you need a support contract, since the repository is a course artifact with no release tags. Before committing time, run `make install` and `uv run decode`, open `.env.example` and confirm you can fill in one provider key, and check `running_the_code/01_install_and_usage.md` for the provider you intend to use.
Frequently asked questions
How to build a coding agent from scratch?
The repository's approach is to write the harness around a small tool-calling loop. The README shows an Agent built with a model, a deps type and an output type, then `register_tools(agent)` and an async loop over `agent.iter` that streams events as the model requests tools. The 8 articles and 4 videos walk through the rest: tools, permissions, sandbox, memory, compaction and evals.
How can I build a coding agent?
The README's quick start is to clone the repository, run `make install`, copy `.env.example` to `.env` and set an LLM API key, then run `uv run decode`. The default provider is Gemini with a free key; Modal and OpenRouter are the other two options listed in the environment file.
Can I learn agentic AI from scratch with this course?
The course assumes Python and walks from a bare-bones agent loop to a swarm of cloud agents, so it does not require prior agent-building experience. It does assume you can install a Python project with uv and supply an API key, since `make install` and the `.env` provider settings are the entry point.
What exactly is a coding agent?
As this repository frames it, the agent is roughly 20 lines: a model, a set of registered tools, and a loop that alternates between model requests and tool calls. Everything else, including the permission layer, sandbox, memory, compaction and remote execution, is the harness that the course says determines whether the agent is good.
Community notes