Coding Agent from Scratch

Building a coding agent from first principles — and the language model it runs on — without a high-level agent framework. The repository is both a production-quality implementation and an executable technical book: the implementation, examples, exercises, benchmarks, and book share one source of truth.

Status: Early foundation. The full specification is written; the repository scaffolding (Milestone 0) is being built now. The commands below describe the intended workflow and become live as the foundation lands — see Roadmap for what currently works.

What this is

A coding agent implemented in ordinary, inspectable Python, inspired by minimal agent systems. The core loop stays explicit:

while not state.finished:
    request = context_builder.build(state)
    response = model.complete(request)
    events = protocol.parse(response)
    state = reducer.apply(state, events)
    state = tool_runtime.execute_pending(state)

The project spans six subsystems: an agent core, model adapters, a tool runtime, context & memory, evaluation & tracing, and a from-scratch transformer language model — culminating in an agent driven by a model trained inside this repository.

Full details: docs/specs/coding-agent-from-scratch-project-spec.md.

Design principles

• Explicit control flow — the agent loop is normal code, not a framework.
• State as data — typed, serializable, replayable, inspectable.
• Ports and adapters — provider-specific code lives behind narrow interfaces.
• One source of truth — the book imports production code from src/; no copied implementations.
• Evaluation before optimization — changes are measured against explicit tasks and metrics.
• Progressive complexity — every milestone leaves the repository working.

Getting started

Requirements: Python ≥ 3.12, uv, just, and Quarto ≥ 1.5 (PDF output needs a LaTeX engine — quarto install tinytex).

uv sync            # install dependencies
just check         # lint + typecheck + test
just book-render   # render the book to HTML, PDF, and EPUB

Standard task-runner commands (spec §18.1):

Command	Purpose
just setup	Install the toolchain
just test	Run the test suite
just lint	Ruff lint + format check
just typecheck	Pyright static type check
just check	lint + typecheck + test
just example <n>	Run an example (examples/NN_*.py)
just eval smoke	Run the smoke evaluation suite
just book-preview	Live-preview the book
just book-render	Render HTML + PDF + EPUB

Repository layout

docs/specs/     Project and prototype specifications
docs/reference/ Archived, validated prototypes (e.g. the Pyodide exercise spike)
src/            Production packages: coding_agent, scratch_llm  (the source of truth)
tests/          unit / integration / golden / evals / fixtures
examples/       Runnable, stage-by-stage example agents
exercises/      Chapter starter / solution / tests
book/           Quarto book (imports from src/)
site/           Standalone articles
configs/        Versioned agent / eval / train / inference configs
notes/          Concepts, papers, and architecture decision records
artifacts/      Benchmarks, figures, traces, tables

Roadmap

Development proceeds in milestones; each leaves the repository in a working state. See spec §19 for the full list.

• M0 — Repository foundation & book scaffolding (in progress)
• M1 — Deterministic minimal agent
• M2 — Tool runtime
• M3 — Model adapters
• M4 — Coding task end-to-end
• M5 — Context management
• M6 — Evaluation system
• M7 — Interactive publishing vertical slice
• M8 — Scratch transformer
• M9 — Coding fine-tuning
• M10 — Optimization & final integration

Non-goals (first version)

Not a competitor to mature commercial agents, not a hosted service, and it does not depend on LangChain, LangGraph, CrewAI, AutoGen, or similar frameworks in the core.

License

To be selected before public release.