Before You Begin

This work runs in several terminals at once: one holds the server, one the client, and one takes your deploys and checks. Open them now and keep them up — the exercises assume all three. Your agent gets its own.

These exercises put five languages on your screen: TypeScript in harness, a paradox spec in dox/, nix in the flakes, JSON for the server, and the javascript payloads from both the model javascript tutorial and the payload that dox-populi generated.

Enviromental Variables

put this in your favorite rc file.

SCREEPS_LOCAL_EMAIL=<username> SCREEPS_LOCAL_PASSWORD=<password>

Bring your agent

I use Claude Code exclusively, with fable passing off particular tasks to appropriate model. You can use your preferred agent.

The loop

Ask your agent a question about the code in front of you. Take its answer as a claim. Verify the claim yourself, and keep what survives.

A claim that keeps losing to the evidence is telling you about your model. Ask smaller questions, or bring a stronger model.

Feeding the agent

I had Claude write the spec by first reading the source code for Paradox, and the model tutorial code. That was my first test of this whole approach: could Claude read the Paradox source and write Paradox? Could it write the solution to the tutorial in concert with the typescript harness? It could, and it did.

The viewer in this repo carries the sharpest example of source as food. Its map came up empty, and the agent spent three rounds deducing how the renderer’s metadata package ought to import: each round plausible, each wrong. What ended it was reading the published bundle itself: the file exports nothing; it assigns window.RENDERER_METADATA and that’s all. My ruling from that exchange is on the record and it governs this whole page: rely on documentation instead of deduction. The session is in docs/unedited/2026-09-02-102600-im-in-trouble-claude.txt.

Give your agent the same food: the sources of the projects you’re asking about — the repos listed in Klanker Kontext.

Who gets the last word

As promising as the new tooling is, it is not a substitute for your own judgment. You are the arbiter; the agent’s claims are settled by you, on evidence you can hold. Every toolchain in the flake doubles as an instrument that produces it.

Two of those instruments arrive with nix run .#generate. It writes generated/ — the decision logic Paradox generates from the spec — and vendor/screeps.d.ts — the game’s type declarations, copied from typed-screeps — into your working tree.

• A file in this repo — the file, sitting in your checkout.
• Game behavior — the running world: deploy and watch.
• The game API — the Screeps API reference, and your cloned screeps repos when the claim reaches into the engine.
• TypeScript — the compiler: turn the claim into a line and put it through the gate; tsc rejects it or compiles it, evidence either way. vendor/screeps.d.ts settles what the game’s types declare, and the TypeScript handbook settles claims about the language.
• nix — handles orchestration of the evaluation and the build: nix eval or nix build the attribute the claim is about, and flake.nix is in your checkout to read. The command links above land in the Nix reference manual’s command reference.
• The spec — paradox check verifies the named properties, and the Paradox source is in your clones.
• JavaScript semantics — MDN, and the running world for what the two tutorial files actually do.

Why Did the Tests Pass?

The loop above is how this repo was built. The transcripts in docs/unedited/ are the unedited record; four moments from them, one per kind of evidence:

• Why Did the Tests Pass? Three green checks, and the running world had the last word.
• This Is a Clean Build The agent’s theory against what I knew I had done.
• It Passes Locally CI reached a deadlock my machine missed.
• The Wrong Server A confident command pointed at the wrong world.

The JavaScript

The original tutorial’s JS is two short files. One semantic in it deserves respect: a misspelled property reads as undefined, and the error arrives later, somewhere else. It has its own exercise — 2-same-mistake.md — where the running world demonstrates it. Each JS file also has a typed counterpart in the port, so a claim about the JS can be held against the same behavior written with declared types.

Start

As you work through the exercises, I’m certain I have missed important details. Help the next person by filing an issue or a merge request; either form opens with the description template ready.

Back to Let’s Play Screeps.