AGENTS.md · diff

git:20260929.e9c233b to git:20261018.938ab3e

4 added, 0 removed. Audit A to A.

# hush

hush is a Claude Code plugin that quiets narration, trims tool output and shapes the final answer

around the result. Its hooks and scripts are dependency-free Node.js and run with Node.js 22 or

later; there is no install or build step. This repository is Foundry's hush submodule, ships from

`main`, and has no Codex package.

## Start here

- Before changing a hook or the shipped voice, read [how hush works](docs/knowledge/how-it-works.md).

- Before changing a switch or the style slot, read [settings](docs/knowledge/settings.md).

- Before touching a README number, read [the benchmark details](docs/knowledge/benchmarks.md); every published number belongs to the voice shipped when its batch ran, with `HUSH_WRAP=1`.

- Before a release, read [the changelog](docs/knowledge/changelog.md) and [CONTRIBUTING.md](CONTRIBUTING.md).

## Rules that outrank everything

- One package on `main` for Claude Code. Do not add a `.codex-plugin/` manifest, a Codex hook registration or Codex installation steps unless a Codex port is decided and validated; the README keeps Codex marked as not available.

- The version lives in `.claude-plugin/plugin.json`; bump it in the release commit. Foundry's Claude catalog pins the `main` commit and carries no version for hush.

- README results name their host, model, source and date. They come from Claude Code sessions; never present them as Codex results.

## Commands

| Command | Purpose | Cost |

| --- | --- | --- |

| `node --test tests/*.test.js` | The suite | Local temporary fixtures |

| `node scripts/git-hooks/check-readme-nav.js` | The root README has its nav, and every heading anchor linked from a tracked Markdown file resolves | Local |

| `claude plugin validate .` | Claude Code package shape | Local |

| `git config core.hooksPath scripts/git-hooks` | One-time: the pre-commit hook runs the suite and the nav check | Local |

## Where things live

| Path | Content |

| --- | --- |

| `hooks/` | The session hooks: `compress-tool-output`, `silence-nudge`, `precompact-summary`, `postcompact-rearm`, `preserve-exit-code`, `session-end-cleanup`, `subagent-brief`; `lib/` holds the gate, the harness, the sidecar store and the transforms |

+ | `hooks/style-settings.js` | The message settings: their values, presets and saved file, the CLI `/hush:config` calls, and the SessionStart hook that sends each moved setting's module |

+ | `commands/config.md` | `/hush:config`: the configurator in the desktop app, or the terminal questions |

+ | `widgets/config.html` | The configurator widget and its sample-message preview; its knob list must match `hooks/style-settings.js` |

+ | `modules/` | One rule per moved setting, `<setting>-<value>.md`, which replaces the voice rule it names |

| `output-styles/hush.md` | The shipped voice |

| `scripts/git-hooks/` | The commit gates |

| `tests/` | The `node:test` suite, with `contract/` and `fixtures/` |

| `docs/knowledge/` | How it works, settings, benchmark details and the changelog |

## Conventions

Benchmark runners, datasets and experiments are not part of the package; `tests/` holds

functional tests only. `CLAUDE.md` imports this file; keep shared contributor facts here.

## Pitfalls

- **Claude Code guards the output of a failing command.** hush trims it only when the session no longer asks for per-step approval or `HUSH_WRAP=1` is set, which is the setup every published number used.

- **A passing nav check verifies anchors, not measurements.** Review the source of every README claim before calling a change ready.