# 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:

```json title="package.json"
"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:

   ```bash
   npx hushrun init --yes
   ```

   `--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:

```markdown
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

| Line | What to do |
|---|---|
| `… files changed while it ran, so it wasn't recorded …` | The check writes files that aren't ignored. Tell the person, and suggest adding them to `.gitignore` |
| `hushrun: sign in to share results with acme: npx hushrun login` | You run where nobody has signed in. Checks still run; tell the person, who signs in once |
| `hushrun: results aren't shared with acme: …` | No credential reached the backend, as in a sandbox without `HUSHRUN_TOKEN`. Checks still run; tell the person |
| `… refused HUSHRUN_TOKEN: … expired on …` or `… was revoked …` | The sandbox's token no longer works; the person makes a new one |
| ``… not recorded: set `HUSHRUN_MACHINE_KEY` to the key `hushrun token create --agent` printed`` | The sandbox has the agent token but not the key it came with. Checks still run; tell the person, who sets `HUSHRUN_MACHINE_KEY` |
| ``… not recorded: this machine isn't registered: run `hushrun login` `` | This machine's sign-in isn't registered, or lapsed after 90 days unused. Checks still run; tell the person, who signs in again |
| `… not recorded: …; upgrade: https://…` | The organization's plan recorded all the checks it includes this period. Checks still run; tell the person |
| `… running without skipping: can't tell which code this is …` | `hushrun.yaml` has several scopes: the script needs `--scope NAME` |

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](https://hushrun.com/docs/agents.md#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:

```markdown title="AGENTS.md"
## 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`](https://hushrun.com/llms.txt) lists every page with a line on each, and [`/llms-full.txt`](https://hushrun.com/llms-full.txt) has all of them in one file.