Skip to content

Coding agents

Pawl was built for code that an agent writes and a person reviews. Two things make that work: output the agent can act on, and a ratchet the agent cannot argue its way past.

Terminal window
pawl check --changed --format agent

One JSON object per line, errors first, and nothing at all when there is nothing to do. Where pawl knows how to fix a finding, the line carries a fix. Here is one, spread over several lines:

{
"file": "src/api.ts",
"line": 1,
"rule": "biome:correctness/noUndeclaredDependencies",
"message": "Dependency made-up-package isn't specified in package.json.",
"fix": "Check that the package exists and is the one you mean, then add it to package.json."
}

Here is a real run, after an agent added a file that imports a package that is not installed, uses any, compares with ==, and hides one finding behind a biome-ignore comment:

$ pawl check --changed --format agent{"file":"src/billing.ts","line":1,"rule":"biome:correctness/noUndeclaredDependencies","message":"Dependency stripe-lite isn't specified in package.json.","fix":"Check that the package exists and is the one you mean, then add it to package.json."}{"file":"src/billing.ts","line":4,"rule":"pawl/no-new-disable","message":"New \"biome-ignore\" comment. Fix the finding instead of switching the check off.","fix":"Remove the disable comment and fix the finding it hides."}{"file":"src/billing.ts","line":6,"rule":"biome:suspicious/noDoubleEquals","message":"Using == may be unsafe if you are relying on type coercion."}{"file":"src/billing.ts","line":3,"rule":"biome:suspicious/noExplicitAny","message":"Unexpected any. Specify a different type.","fix":"Use a specific type, or unknown and narrow it."}

--changed limits the run to files changed against HEAD, plus untracked ones, so the agent hears about its own work only. --format json prints the whole result as one document instead.

A file that gains biome-ignore, eslint-disable, @ts-ignore, @ts-expect-error or @ts-nocheck fails with pawl/no-new-disable. Switching a check off is not a way past it; fixing the code is. Existing disable comments are part of the baseline, so this applies only to new ones.

Terminal window
npx @santi020k/pawl init --agents

--agents adds up to three things.

A Claude Code hook, so Claude Code sees the findings after every edit. It goes in .claude/settings.json, next to any hooks you already have:

.claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "npx pawl check --changed --format agent"
}
]
}
]
}
}

A Cursor hook, in repos that already have a .cursor folder. Cursor does not read a hook’s output back, so this hook applies safe fixes and formatting after each edit, and the AGENTS.md instructions tell the agent to run the check:

.cursor/hooks.json
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"command": "npx pawl fix --changed"
}
]
}
}

Instructions in AGENTS.md, for every agent. Pawl writes them between <!-- pawl:start --> and <!-- pawl:end --> markers, so running init again updates its block and leaves the rest of the file alone:

AGENTS.md
## Code quality
This repo uses pawl. After editing code, run:
npx pawl check --changed --format agent
It prints one JSON line per problem, each with a `fix`. No output means there is nothing to do.
Run `npx pawl fix` to apply formatting and safe fixes.
Do not silence a problem with a disable comment (`biome-ignore`, `eslint-disable`, `@ts-ignore`).
New ones fail the check. Fix the code instead.

Codex reads AGENTS.md at the start of every session, so the block above is all it needs: it runs pawl check --changed --format agent after it edits code and fixes what it reports. Pawl does not write a Codex hook. Codex ignores the plain output of a PostToolUse hook, so a hook that runs the check would not reach the model.

init offers a menu in a terminal. In CI or under a coding agent it uses auto, so an agent can set up a repo without getting stuck on a prompt. Add --yes to accept the plan without asking.

MIT licensed. Made by santi020k.