# agentlab

Building a coding agent from scratch, one stage at a time.

Companion to the field manual:
**https://claude.ai/code/artifact/2c0b2fd8-fdb9-4237-9588-631d5838559c**

Each directory under `stages/` is a complete, runnable agent. They stand alone —
read them side by side to see exactly what each idea adds.

## Setup

```sh
npm install
$env:ANTHROPIC_API_KEY = "sk-ant-..."   # PowerShell
```

Get a key at <https://console.anthropic.com/settings/keys>. Nothing runs without it.

## Run

```sh
npm run stage:01     # the loop, three tools
npm run stage:02     # eight tools, concurrent batching, /tokens and /todos
```

Then talk to it:

```
❯ create fizzbuzz.js, then run it with node and show me the output
❯ add a test file and make it fail, then fix it
```

The agent works inside `playground/`, which is gitignored. Nothing in there is
precious — that's the point.

## Verify without spending tokens

Tools are ordinary functions. Stage 02 ships a suite that exercises every one
of them with no model and no API key:

```sh
npm run verify:02
npm run typecheck
```

## Stages

| Stage | Adds | Status |
|-------|------|--------|
| `01-loop` | The whole idea: three tools, one `while` loop, errors fed back to the model | ✅ |
| `02-tools` | glob, grep, list_dir, todo; concurrent tool batching; result capping | ✅ |
| `03-caching` | Cache breakpoints, usage accounting, a real system prompt | planned |
| `04-permissions` | The approval gate — allow / ask / deny, session-scoped grants | planned |
| `05-context` | Compaction and context editing for long sessions | planned |
| `06-subagents` | Delegation with isolated context windows | planned |
| `final` | Everything, factored into modules | planned |

## Notes on the toolchain

Node 24 runs `.ts` files directly by **stripping types** — there is no build
step and no `tsx`. Two consequences:

- Every construct must be erasable. No `enum`, no `namespace`, no parameter
  properties. `tsconfig.json` sets `erasableSyntaxOnly` so `tsc` catches this.
- `tsc` is a *checker only* (`noEmit`). Run `npm run typecheck`.

## Layout

```
agentlab/
├── stages/
│   └── 01-loop/agent.ts     complete agent, ~200 lines
├── final/src/               the factored version (later)
├── playground/              the agent's workspace — gitignored
├── package.json
└── tsconfig.json
```