From 44d23a25e51cfbc4a1cee3a481229115f737748d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?A=CC=82nderson=20Q?= Date: Sat, 5 Sep 2026 15:53:43 -0300 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20add=20root=20AGENTS.md=20=E2=80=94?= =?UTF-8?q?=20the=20project=20contract?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Names what this project is, which roles work it, and where they read from. No personas live here: an agent arrives already knowing who it is. Part of the crew-consolidation plan, P5. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..abc7c90 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# hey + +Attention beeps for terminal agents. When an agent hands back to you — a finished reply, or a +permission prompt — `hey` plays a short sound, **but only if you have been idle longer than a +threshold**. A fast back-and-forth stays silent; you are summoned only when you have likely stepped +away. Built for Claude Code hooks, but the CLI works anywhere. + +**It never listens.** Most alerts are plain sounds; one is a short pre-rendered voice clip, because +a spoken word cuts through ambient audio better than a blip. + +The rule is uniform and carries no model judgement: any hand-back beeps if and only if +`now − last_prompt ≥ threshold`. That rule is the product — changing it changes what the tool is. + +**Open source, AGPL-3.0, passively maintained.** The public `README.md` is the user documentation +and stays that way; `CONTRIBUTING.md` and `LICENSING.md` carry the contribution and licensing +terms. + +## Crew + +The roles this project is worked by, and what each one needs. **No personas live here** — an agent +arrives already knowing who it is, and reads this project to learn the project. + +| Role | What this project needs from it | +|------|---------------------------------| +| Engineering | The `hey` CLI, the hook scripts, the sound set | +| Code review | Any change to the idle gate. It is the whole behavioural contract | +| Content | The README is public OSS documentation, not internal notes | +| Sysadmin | Branch protection and the LGTM gate | + +No architect or data role is in use. + +**After any context loss, re-read your anchor under `~/.agent-anchors/hey/`** (canon §17). None +exists yet. + +## Key files + +- `README.md` — user documentation: install, use, hook wiring +- `hey` — the CLI +- `hooks/` — `turn-mark.sh` stamps the turn start; `hey.sh` decides and plays +- `assets/` — the sounds +- `config.sh` — defaults +- `MEMO-CODEX-URGENT.md` — untracked and open: LGTM gate and branch protection From 8386f188cf8e826ae3742c838133c96e5f0eaa4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?A=CC=82nderson=20Q?= Date: Sat, 5 Sep 2026 16:11:20 -0300 Subject: [PATCH 2/2] docs: correct AGENTS.md against the repository Fixes from the review pass: licence, branch and gate claims measured rather than copied from stale memos; missing surfaces named; a 'how work flows' section added. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index abc7c90..0c49487 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,12 +8,24 @@ away. Built for Claude Code hooks, but the CLI works anywhere. **It never listens.** Most alerts are plain sounds; one is a short pre-rendered voice clip, because a spoken word cuts through ambient audio better than a blip. -The rule is uniform and carries no model judgement: any hand-back beeps if and only if -`now − last_prompt ≥ threshold`. That rule is the product — changing it changes what the tool is. +**The gate is uniform and carries no model judgement.** Once a session is armed with `hey `, +a hand-back beeps when `now − last_prompt ≥ threshold`. A missing turn marker counts as long-idle +and beeps: the design fails toward alerting rather than toward silence. That gate is the product — +changing it changes what the tool is. -**Open source, AGPL-3.0, passively maintained.** The public `README.md` is the user documentation -and stays that way; `CONTRIBUTING.md` and `LICENSING.md` carry the contribution and licensing -terms. +**Beep where you sit.** Over SSH the beep sounds on *your* machine, not the remote box: `hey` +forwards the sound name over a multiplexed SSH forced-command call to `server/hey-play` on the +operator's machine. It fails closed — if the channel is down the beep is dropped, never sounded +into an unattended room. + +**Open source, dual-licensed** — AGPL-3.0, commercial on request (`LICENSING.md`) — and passively +maintained. The public `README.md` is the user documentation and stays that way. + +## How work flows + +Branch, work from a worktree under `.worktrees/`, open a PR against `main`. The LGTM gate runs on +every PR. The `.claude/` CLU guards enforce worktree-only writes and refuse a self-merge, but only +while a CLU run is active. `main` is not branch-protected, so the gate is advisory. ## Crew @@ -22,10 +34,11 @@ arrives already knowing who it is, and reads this project to learn the project. | Role | What this project needs from it | |------|---------------------------------| -| Engineering | The `hey` CLI, the hook scripts, the sound set | -| Code review | Any change to the idle gate. It is the whole behavioural contract | +| Engineering | The `hey` CLI, the hook scripts, the reverse-beep path, the sound set | +| Code review | Any change to the idle gate or to the fail-closed reverse path. Both are the behavioural contract | +| Security review | Only when the SSH forced-command setup changes — it is a key-authorized remote execution path | | Content | The README is public OSS documentation, not internal notes | -| Sysadmin | Branch protection and the LGTM gate | +| Sysadmin | Branch protection and the gate | No architect or data role is in use. @@ -34,9 +47,10 @@ exists yet. ## Key files -- `README.md` — user documentation: install, use, hook wiring +- `README.md` — user documentation: install, use, hook wiring, reverse-beep setup - `hey` — the CLI -- `hooks/` — `turn-mark.sh` stamps the turn start; `hey.sh` decides and plays +- `hooks/` — `turn-mark.sh` stamps the turn start; `hey.sh` decides and emits +- `server/hey-play` — the reverse-beep endpoint, run as an SSH forced command on the operator's machine +- `config.sh` — defaults and the reverse-beep destination resolution - `assets/` — the sounds -- `config.sh` — defaults -- `MEMO-CODEX-URGENT.md` — untracked and open: LGTM gate and branch protection +- `MEMO-CODEX-URGENT.md` — untracked. Its gate item is done; branch protection is still open