Working with AI agents

Kerf is built for code that AI agents write, as much as for code you write yourself. An agent's usual problem with a framework is that it guesses: it writes what the framework it knows best would want, and nothing tells it otherwise until a person reads the result. Kerf closes that gap from both sides. It tells the agent what this app is and how to write it, and when the agent gets something wrong, the diagnostics say exactly what and how to fix it, in a form a program can act on.

Nothing on this page needs an agent. Every command here is one you can run yourself, and you'll see the same things the agent sees.

AGENTS.md

A new app has an AGENTS.md at its root. Most coding agents read a file by that name when they start work in a project. Kerf's opens like this:

# AGENTS.md<!-- Generated by `kerf agents-md` from kerf@0.1.4.Do not edit: change kerf.config.ts and regenerate. -->This is a **kerf** app. It is not React: components run once,state is a box, and React hooks don't exist. Run `kerf check --json`after every change; each diagnostic gives code, location, why and fix.

The rest is written from the Kerf you have installed, not from a template, so it can't describe a version you don't have:

• The rules: the short list of how Kerf code is written (boxes, derived, live JSX and props, bodies that run once). It's the same text as kerf docs rules.
• The API in this version: what @kerf-js/core and its entries export, and anything it doesn't have yet, with "Don't import them".
• Diagnostics: how to look one up, and which test checks this Kerf reports.
• How to verify a change, which is the loop later on this page.
• Full stack, for an app with src/routes: routes, server functions, the database and auth, in brief.
• Styling, when the app has style groups: reuse a group before writing a new one.
• Commands: this project's commands and tasks, each with what it does and what it touches.
• Plugins: a short section from each plugin in kerf.config.ts.
• More: the kerf docs topics to read for depth.

Kerf keeps its own part under 8 KB, because an agent pays for every word of it on every task. Each plugin's section has its own limit of 1 KB (P112). Anything longer belongs in kerf docs, which an agent reads only when it needs to.

Keeping it current

AGENTS.md is generated, so don't edit it by hand. It's written after the install by the generator, and again by kerf add when you add a plugin. Regenerate it yourself after you upgrade Kerf or change tasks or plugins:

npx kerf agents-md

To check it's current without writing, as in CI:

npx kerf agents-md --check

That exits 1 when the file is stale, or when Kerf's part is over the limit. --stdout prints it instead of writing.

If your agent reads a different file, such as CLAUDE.md, have that file point to AGENTS.md rather than copying it, so there's one file to keep current.

Docs an agent can read: kerf docs

The site is for people. An agent working in a terminal reads the same reference from the command line:

npx kerf docs            # the list of topicsnpx kerf docs props      # one topicnpx kerf docs W014       # one diagnostic code

The topics are the reference pages: rules, state, props, lists, async, start, rust, plugins, testing, browser, ui-state, surface, verify, icons, fonts, meta, config, design and style. A few are generated from your app instead of written:

A code page says whether your install reports that code at all. A plugin can add topics and codes of its own, and they show up in kerf docs like the built-in ones.

Each topic is written to be short, because an agent reads it in its context. The Reference on the site shows the same text.

.kerf/map.md: what this app has

AGENTS.md says how to write Kerf. The map says what's in this app: its routes, its server functions and data, its style groups and its plugins, and what to call for each.

npx kerf map

That writes .kerf/map.md (and .kerf/map.json); kerf check keeps it current once .kerf/ exists. AGENTS.md tells the agent to start there, so it reuses the listTodos query you already have instead of writing another.

Tasks: commands an agent can trust

An agent shouldn't have to read a shell script to learn whether it deletes a database. Kerf's project commands are declared in kerf.config.ts, each with what it does and what it touches:

tasks: {  seed: {    run: 'node scripts/seed.mjs',    description: 'Load demo products into the dev db',    sideEffects: ['db'],    env: ['dev']  },},

kerf tasks lists them beside Kerf's own commands, and kerf run seed runs one. A task with no description or sideEffects is P004, and a package.json script that isn't a kerf command is P002, for the same reason.

scope in the config draws the lines an agent works inside: write and read globs, and forbid, which Kerf never compiles or writes (.env*, say). The config reference has the details.

The verify loop

"Done" for an agent means more than "it compiles". AGENTS.md gives it four steps for every change, and each one answers to a command.

1. Check: kerf check --json

After every change, the agent runs:

npx kerf check --json

Each diagnostic comes back with its code, its place, why it's wrong, and the fix, often as an exact edit. The agent applies the safe edits (kerf fix does it in one go), decides the rest, and runs the check again until there are no errors. Because the reason is written about the code in front of it, the agent doesn't have to guess what a stack trace meant.

2. See it work: kerf browser

A clean check means the code is well formed, not that the feature works. So the agent looks at the running app. With kerf dev running and the app open in a browser, kerf browser drives that tab through the dev server:

npx kerf browser snapshot --interactivenpx kerf browser act button "Add to cart" clicknpx kerf browser assert status - text "Total: $4.50"

snapshot lists what's on the page by role and name, with a ref for each, the way a screen reader or a test sees it, plus the reactive graph with real names: Cart.total = 4.5 ← Cart.lines. act clicks, types and selects as a user would, and returns what changed. assert checks what the user sees, and waits briefly for something that loads.

There's more for harder cases: time pause and time advance 3000 control the page's clock, net offline and net drop test what happens when the connection goes, set Cart.coupon '"SAVE10"' jumps to a state, and logs returns the page's errors with the component they came from. kerf browser help lists them all. With no browser open, kerf browser launch starts a headless Chrome.

An agent with its own browser tool can skip the CLI: every page in dev has __kerf__.agent, and await __kerf__.agent.run('snapshot') is the same command. That needs @testing-library/dom and @testing-library/user-event in the app, which the testing setup adds.

3. Keep it: kerf browser record

What the agent just did by hand can become a test. record start, then the acts and asserts, then:

npx kerf browser record code --component Cart --from ./Cart \  --out src/Cart.test.tsx

writes them as a @kerf-js/core/test test.

4. Prove the test: kerf test --gate

A test that passes isn't proof of anything if it would also have passed before the change. The gate checks the tests on the diff:

npx kerf test --gate

• T010: each new or changed test must fail on the code from before the change.
• T011: each new test must catch at least one deliberate mistake ("mutant") in the lines that changed. A mutant it misses comes back with what to assert.
• T020: no existing test may be deleted, skipped or loosened without a // kerf-allow T020: <reason>.

The gate works in scratch copies, so your working tree is never touched. --base main compares against a branch instead of the uncommitted change. The verify reference has every option.

kerf mcp: Kerf's tools over MCP

Agents that speak the Model Context Protocol can use Kerf as a set of tools instead of shell commands. kerf mcp is an MCP server on stdio. Most clients take a block like this in their MCP settings:

{  "mcpServers": {    "kerf": { "command": "npx", "args": ["kerf", "mcp"] }  }}

If the client starts it from another folder, add "--root", "path/to/my-app" to args.

The tools are the commands on this page:

Each tool returns the same JSON as the command's --json, so what you learn from one works in the other.

--json everywhere

Every kerf command takes --json and --root <dir>. They follow one convention, so a script or an agent can rely on it:

• JSON goes to stdout, and text for people goes to stderr. With --json, stdout holds nothing else.
• The exit code is 0 when all is well, 1 when there are errors (or, for agents-md --check, a stale file), and 2 for a usage error or a failure in Kerf itself. A failure still prints { "ok": false, "error": { "code", "message" } }.
• Diagnostics have one shape in every command: code, severity, file, span, why, fix and docs.

npx kerf check --json > check.jsonnpx kerf routes --meta --jsonnpx kerf tasks --json

Recap

• AGENTS.md is generated from your installed Kerf and your config. Regenerate it with kerf agents-md, check it in CI with --check, and never edit it by hand.
• kerf docs is the reference in the terminal, kerf docs <CODE> explains any diagnostic, and .kerf/map.md says what this app has.
• The verify loop: kerf check --json and fix, see it work with kerf browser, record a test, and pass kerf test --gate.
• kerf mcp offers the same commands as MCP tools, returning the same JSON.
• Every command takes --json: JSON on stdout, text on stderr, and exit codes 0, 1 and 2.

That's the end of Get started. Next, Describing the UI begins the tour of Kerf itself.