Part one of the Handmade Claude Code campaign: the agent becomes a loop. Not a script that sends one prompt and prints one reply — a process that holds a conversation, runs the tools the model asks for, feeds the results back, survives a model that hiccups, and stops when told to.

Everything after this part is built on the shape frozen here, so the shape comes first and the tool set stays deliberately thin: bash only. Part two gives it real hands.

The command

You declare it, and it is captured into session memory — any language, any entry point:

agent: <command>     started as:  <command> -C <dir> [--yes] -p "<prompt>"

• -C <dir> — the working directory. Everything relative (files, shell commands, later AGENTS.md discovery) is relative to it. Default: the current directory.
• -p "<prompt>" — headless mode: run the loop to completion, print the final answer to stdout, exit 0. Nothing else goes to stdout — logs and progress belong on stderr. Without -p the same command opens the terminal UI (part six).
• --yes — skip permission checks; every tool call is allowed. Part two adds the permission engine; until then the checks always pass --yes.
• --output-format json — instead of the plain answer, print one JSON object: {"result": "<answer>", "session_id": "<id>", "turns": <model calls>, "usage": {"input_tokens": <sum>, "output_tokens": <sum>}}.
• --max-turns <n> — the most model calls one run may make (default 50).

The model protocol

The harness never knows which model it is talking to. Every model call is one run of the command in the environment variable AGENT_MODEL_CMD (started with sh -c): the request goes to its stdin as one JSON document, the reply comes back on its stdout, the process exits 0. Once per call — the model is stateless, the whole conversation travels every time, exactly like a real API.

The request:

{
  "system": "<the system prompt — never empty>",
  "messages": [
    {"role": "user", "content": [{"type": "text", "text": "<prompt>"}]},
    {"role": "assistant", "content": [
      {"type": "text", "text": "…"},
      {"type": "tool_use", "id": "t1", "name": "bash", "input": {"command": "ls"}}
    ]},
    {"role": "user", "content": [
      {"type": "tool_result", "tool_use_id": "t1", "content": "<output>", "is_error": false}
    ]}
  ],
  "tools": [{"name": "bash", "description": "…", "input_schema": {…}}]
}

The reply: one JSON object per line. Any number of streamed fragments {"type": "text_delta", "text": "…"}, then exactly one final line:

{"type": "message", "content": [<blocks>], "stop_reason": "end_turn", "usage": {"input_tokens": 123, "output_tokens": 45}}

stop_reason: "tool_use" means the content carries tool_use blocks: run every one of them, append one user message carrying a tool_result per call in the same order, and call the model again. end_turn ends the loop; the text blocks of the final message, joined with newlines, are the answer. The deltas are for showing progress — they are never printed as the answer a second time.

A model command that exits non-zero, or whose last line is not a valid message, has failed. Call it again — three attempts in total, no more than a second or two apart. After the third failure print a line starting ERROR: to stderr and exit non-zero. --max-turns is enforced the same way: one call past the cap is an ERROR: and a non-zero exit.

Providers and models

AGENT_MODEL_CMD is the shortcut the checks use; the mechanism behind it is a provider registry in .agent/settings.json of the working directory:

{"providers": {"scripted": {"type": "command", "command": "sh model.sh"},
               "claude":   {"type": "anthropic", "api_key_env": "ANTHROPIC_API_KEY"},
               "local":    {"type": "openai", "base_url": "http://localhost:11434/v1"}},
 "model": "scripted/default"}

model names the default as <provider>/<model>; --model <provider>/<model> overrides it for one run. Every request carries the model name: "model": "<model>" next to system, messages and tools. AGENT_MODEL_CMD, when set and non-empty and no --model is given, is a command provider that wins over the settings. A --model naming a provider the settings do not declare is an ERROR: and a non-zero exit.

The command type is the one the checks exercise. At least one HTTP type belongs in the same registry so the agent can be used for real — the Anthropic Messages API, or an OpenAI-compatible chat completions endpoint (which also covers Ollama, OpenRouter and most local servers) — behind the same interface, so the loop never knows which one it is talking to. The review panel looks for it; part six adds /model to switch at runtime.

The bash tool

{"name": "bash", "input": {"command": "<shell>"}}

Runs the command with sh -c in the working directory. The result content is its stdout and stderr, in order. A non-zero exit appends a line exit code: <n> to the content and sets is_error to true. The loop does not stop on a failed tool — the model is told, and decides.

Wrapping claude, codex, gemini, aider or any other coding agent, or building on an agent SDK that owns the loop, is not building one. The loop is yours; HTTP clients, JSON parsers and terminal libraries are tools.

The judges

The quality panel — architecture, performance, code quality, test quality, technical governance and DX review — sits on the rungs where its subject is decided, one verdict per judge per rung, on top of the rung's own points. There is no closing review: what you build is judged as you build it, and a rung you never reach is a verdict you never get.

The ladder

• Set up: declare agent: and test: (10)
• One prompt, one answer (10)
• The request is a conversation (10)
• A tool round trip (30)
• Many turns (30)
• Bash tells the truth (20)
• Providers and models (30)
• A flaky model gets retried (20)
• Turns are capped, the bill is printed (20)