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.
Output for agents
Section titled “Output for agents”pawl check --changed --format agentOne 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.
Disable comments fail
Section titled “Disable comments fail”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.
Set it up
Section titled “Set it up”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:
{ "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:
{ "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:
## 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.
Running init under an agent
Section titled “Running init under an agent”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.