For coding agents

This page is written for a coding agent: one asked to add hushrun to a repository, or working in a repository that already uses it. People can read it as the rules their agents follow.

Is hushrun here?

A repository uses hushrun when its package.json has scripts that start with hushrun run, or a "hushrun" key that names a backend:

"scripts": {
  "test": "hushrun run -- vitest run"
},
"hushrun": {
  "backend": "https://api.hushrun.com/o/acme"
}

Other repositories call hushrun run NAME -- COMMAND from their CI files or scripts.

Setting hushrun up

When a person asks you to add hushrun to a repository:

1. At the repository's root, run:

   npx hushrun init --yes

   Copy Copied

   --yes applies the changes without asking. Without --yes, and without a terminal, init prints its plan and exits with status 2.

2. It prints a sign-in link and a code. Show both to the person and wait: they approve it in their browser, and you can't do it for them. If they don't have an organization yet, they create one on that page.

3. When init finishes, show the person the diff, run each check it wrapped once, and commit the change on a new branch.

npx hushrun init --dry-run shows the plan and changes nothing: no sign-in, no files, no install. The prompt people give agents for this, word for word:

Add hushrun to this repository. Run `npx hushrun init --yes` at the repository root; it prints a sign-in link, which I'll approve in my browser. Then show me the diff it made, run the checks it wrapped once, and commit the change on a new branch.

Running checks

• Run checks the usual way: npm test, pnpm lint, yarn typecheck. Don't call the tools behind them directly to get around hushrun.
• A skip is a pass. hushrun: test skipped: this exact code passed … means the same check, with the same command, passed on exactly these files: here, in CI or in another agent's sandbox. The exit code is 0. Running it again would give the same answer.
• A failure is real. hushrun: test failed in 2s (exit 1) keeps the check's own exit code and output. Fix the cause; the next run runs again.
• Changing files runs checks again. Editing a file changes the code, so checks run; going back to files that passed skips them.
• Partial runs are separate checks. vitest run src/cart.test.ts never reuses the full run's pass, and its pass never stands in for the full run. Use them freely while you work, then run the full check.
• To see a skipped check's output, such as a log or a coverage report, run it again with --force, giving the script's name and its exact command so the result counts for the same check: npx hushrun run --force test -- vitest run.
• hushrun's lines go to stderr and start with hushrun: . Everything else is the check's own output.

Lines that need you

None of these fail a check: hushrun runs the command and keeps its exit code. hushrun whoami shows where results go and which credential is used.

In a sandbox

Without a browser, hushrun needs an agent token and the key it came with, from a person: HUSHRUN_TOKEN=hra_…, HUSHRUN_MACHINE_KEY (the key's PEM block), and HUSHRUN_PROVIDER=local where the sandbox sets CI=true. If hushrun whoami shows no token, or a run says its result wasn't recorded for want of the key, checks still run but share nothing: say so instead of trying to sign in. Agents and sandboxes is the page to point the person to.

Never

• Commit a token (hra_…, hru_…) or a machine key, or print one in a log or a pull request.
• Edit the "hushrun" key in package.json, a HUSHRUN_* variable, or id-token: write in a workflow, unless the person asks.
• Remove hushrun run -- from a script to make a check run. Use --force once instead.
• Run hushrun login, hushrun logout or hushrun token on a person's behalf without being asked.

A snippet for AGENTS.md

Add this to the repository's AGENTS.md, CLAUDE.md or your agent's instructions file:

## Checks run through hushrun

This repository's checks run through hushrun (`hushrun run -- …` in package.json's scripts). A
check skips when this exact code already passed it, here, in CI or in another agent's sandbox.

- Run checks as usual (`npm test`, `npm run lint`); don't call the tools behind them directly.
- A skip is a pass, with exit code 0. A failure is real: fix it.
- To see a skipped check's output, run it with `--force`, the script's name and its command, such as
  `npx hushrun run --force test -- vitest run`.
- A check that writes files must list them in .gitignore, or its result isn't recorded.
- Never commit tokens (hra_…, hru_…) or machine keys, and never edit package.json's "hushrun" key.
- More: https://hushrun.com/docs/for-agents.md

Reading these docs

Every page of these docs is Markdown at its address with .md added, such as https://hushrun.com/docs/run.md. A request whose Accept header asks for text/markdown gets the Markdown at the page's own address. /llms.txt lists every page with a line on each, and /llms-full.txt has all of them in one file.