@trygocode/notify 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `@trygocode/notify` are documented here. This project
+follows [Semantic Versioning](https://semver.org).
+
+## [0.1.0] — 2026-06-03
+
+Initial public release.
+
+### Added
+- **One-command install** — `npx @trygocode/notify@latest setup` pairs the machine,
+  auto-detects your agent runtimes, and merges hooks + the MCP server + an
+  anti-double-ping rule into each (Cursor, Claude Code, OpenCode). Idempotent;
+  safe to re-run; `--force` re-pairs.
+- **Three notification triggers** — (A) runtime hooks (Cursor `stop`; Claude Code
+  `Stop` / `Notification` / `SubagentStop`), (B) the `gocode_notify` MCP tool for
+  explicit "ping me when X is done" requests, (C) an opt-in Ralph/Homer loop
+  completion/halt snippet.
+- **Secure pairing** — a short-lived 6-digit code is exchanged for a scoped,
+  push-only API key stored locally (`~/.gocode/credentials`, chmod 600). The key
+  can only send pushes to your own phone; revoke any time from the app.
+- **Offline outbox** — sends made while the server is unreachable are queued and
+  flushed best-effort later, so a blocked agent is never caused by a slow push.
+- **`status` self-diagnosis**, `test` round-trip push, and a clean `uninstall`
+  that removes exactly what this tool added.
+- **MCP server metadata** — `icons` + `websiteUrl` (SEP-973) so compatible clients
+  can show the GoCode mark next to the server.
+
+[0.1.0]: https://github.com/joseph-lewis/gocode-notify/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+<p align="center">
+  <img src="assets/icon.svg" alt="GoCode Notify" width="96" height="96" />
+</p>
+
+<h1 align="center">@trygocode/notify</h1>
+
+<p align="center">
+  <strong>Get a push notification on your phone the moment your AI coding agent finishes.</strong><br/>
+  Cursor · Claude Code · OpenCode · Ralph/Homer loops — installed with <em>one</em> command.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@trygocode/notify"><img alt="npm" src="https://img.shields.io/npm/v/@trygocode/notify?color=5EE6A8&label=npm"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white">
+  <img alt="works with" src="https://img.shields.io/badge/works%20with-Cursor%20%C2%B7%20Claude%20Code%20%C2%B7%20OpenCode-111">
+</p>
+
+```bash
+npx @trygocode/notify@latest setup
+```
+
+<p align="center">
+  <!-- Joseph: drop a 2-3s screen recording of the phone notification arriving here. -->
+  <img src="assets/demo.gif" alt="A push notification arrives on the phone the instant the agent finishes" width="320" />
+</p>
+
+---
+
+## Why?
+
+You kick off a long agent run, then walk away to make coffee, take a call, or
+context-switch to something else. Now you're stuck in the loop of *checking back
+every 30 seconds* to see if it's done — or worse, it finished 20 minutes ago and
+you didn't notice.
+
+**`@trygocode/notify` pings your phone the instant your agent finishes a turn, goes
+idle waiting for you, errors out, or an overnight loop completes/halts.** Walk
+away. Your phone tells you when it needs you.
+
+- ⚡ **One command.** `npx @trygocode/notify@latest setup` — no server to host, no config files to hand-edit.
+- 🔒 **Push-only & private.** The paired key can *only* send notifications to your phone. It can't read your chats, code, or settings. Revoke it any time.
+- 🧩 **Auto-detects your tools.** Wires up Cursor, Claude Code, and OpenCode in one go — never clobbering your existing hooks/MCP config.
+- 🪶 **Never blocks your agent.** Every send is fire-and-forget with a hard timeout + an offline queue. A slow push can't slow your work.
+
+## Works with
+
+| Tool | How it hooks in |
+|---|---|
+| **Cursor** | `stop` hook |
+| **Claude Code** | `Stop` + `Notification` + `SubagentStop` hooks |
+| **OpenCode** | runtime hook |
+| **Ralph / Homer loops** | opt-in completion/halt snippet |
+
+> Notifications are delivered through the free **[GoCode](https://oh.jeltechsolutions.com)**
+> phone app (the one-time pairing target). Install GoCode, pair once, done.
+
+## Contents
+
+- [Install — two equally-supported paths](#install--two-equally-supported-paths)
+- [Pairing — step by step](#pairing--step-by-step)
+- [The three triggers](#the-three-triggers)
+- [Ralph/Homer opt-in snippet (trigger C)](#ralphhomer-opt-in-snippet-trigger-c)
+- [Troubleshooting](#troubleshooting)
+- [Develop](#develop)
+- [Layout](#layout)
+
+## Install — two equally-supported paths
+
+Both paths converge on the same installer (`gocode-notify setup`): it pairs this
+machine, auto-detects your agent runtimes, and merges the hooks + MCP server +
+anti-double-ping rule into each one's config (never clobbering your existing
+settings; safe to re-run).
+
+### Path 1 — paste a one-liner into your terminal
+
+```bash
+npx @trygocode/notify@latest setup
+```
+
+This runs the interactive installer: it prompts for the 6-digit pairing code
+(from the GoCode app → **"Connect a coding agent"**), then detects and configures
+Claude Code / Cursor / OpenCode. Re-run any time — it's idempotent; pass
+`--force` to re-pair.
+
+> First time? You'll need the free **[GoCode](https://oh.jeltechsolutions.com)**
+> app on your phone to receive the pushes and to generate the 6-digit pairing
+> code (Settings → **"Connect a coding agent"**).
+
+### Path 2 — paste a prompt into your AI agent and let it install
+
+Hand this to Cursor / Claude Code and the agent does the install for you. The
+`--agent-driven` flag suppresses interactive prompts and emits one JSON line per
+step so the agent can verify each one:
+
+```
+Install GoCode phone notifications for this machine. Run:
+  npx @trygocode/notify@latest setup --agent-driven --pair-code <CODE>
+Then confirm the hooks and MCP server were written, and run
+  npx @trygocode/notify@latest test
+to send a test push to my phone. Report whether the test push arrived.
+```
+
+Replace `<CODE>` with the 6-digit code from the GoCode app. `--agent-driven` is
+fully idempotent and machine-readable; it never spawns a prompt.
+
+## Pairing — step by step
+
+A dev machine running agent hooks has no GoCode login (no JWT), so it can't use
+GitHub OAuth. Instead you pair it once with a short-lived **6-digit code**, which
+the CLI exchanges for a scoped, push-only **API key** stored locally. The key can
+only send pushes to *your* phone — it can't read chats, settings, or trigger any
+agent action, and you can revoke it from the app at any time.
+
+1. **In the GoCode app**, open **Settings → "Connect a coding agent"**. The app
+   shows a large 6-digit code (valid 10 minutes), a copyable
+   `npx @trygocode/notify login --code 123456` line, and a 10:00 countdown. Tap
+   **"Generate new code"** if it expires.
+2. **On the machine**, either run the full installer (`npx @trygocode/notify@latest
+   setup`, which pairs *and* writes your agent configs) or just pair on its own:
+
+   ```bash
+   # Interactive — prompts for the code:
+   npx @trygocode/notify@latest login
+
+   # Or pass it directly (and optionally label this machine):
+   npx @trygocode/notify@latest login --code 123456 --label "MacBook Pro — Cursor"
+   ```
+3. The CLI calls the server's `pair/claim` endpoint, receives the API key **once**,
+   and writes it to `~/.gocode/credentials` (chmod `600`). The app flips to a
+   **"connected ✓"** success state showing the machine's label.
+4. **Verify the round-trip** with a real push to your phone:
+
+   ```bash
+   npx @trygocode/notify@latest test
+   ```
+
+   A "GoCode test" notification should arrive on your paired device. If it
+   doesn't, see [Troubleshooting](#troubleshooting).
+
+**Re-pairing.** Both `login` and `setup` are idempotent — re-running them won't
+clobber an existing pairing. To deliberately replace the stored key (new machine
+owner, rotated key), pass `--force` to `setup` (or just run `login` again with a
+fresh code). Revoke an old machine from the app's **"Connected agents"** screen.
+
+**Server selection.** Pairing and every send resolve the server URL in this
+precedence order: the `--server` flag → the `GOCODE_SERVER` env var → the value
+saved in `~/.gocode/credentials` → the built-in default
+(`https://oh.jeltechsolutions.com`). You only need `--server` for a self-hosted
+or staging GoCode server.
+
+## The three triggers
+
+| Trigger | Mechanism | Fires when |
+|---|---|---|
+| **(A) Runtime hook** | Cursor `stop` / Claude Code `Stop`+`Notification`+`SubagentStop` | Agent finishes a turn, goes idle, or errors — **automatic, the killer feature** |
+| **(B) MCP tool** | `gocode_notify` tool the agent calls | You *explicitly* ask "ping me when X is done" mid-task |
+| **(C) Loop shell hook** | one line in your loop's completion/halt path | A Ralph/Homer loop reaches `completed` / `halted` |
+
+The installed rule/skill tells the agent **not** to call the MCP tool for
+done/idle/error pings — those are owned by the deterministic hook (A), so you
+never get double-pinged.
+
+## Ralph/Homer opt-in snippet (trigger C)
+
+For power users running a loop **they control** (this repo's `ralph`/`homer`
+skills, a `while :; do … done` one-liner, or any custom driver), drop these two
+lines into the loop's completion/halt path:
+
+```bash
+# At loop completion:
+gocode-notify send --kind loop_completed --source ralph --project "$(basename "$PWD")" || true
+# At loop halt (paused_max_failures / awaiting_human):
+gocode-notify send --kind loop_halted --source ralph --project "$(basename "$PWD")" \
+  --title "Ralph halted — needs you" || true
+```
+
+The ready-to-copy version with comments lives at
+[`snippets/ralph-homer.sh`](snippets/ralph-homer.sh).
+
+**This is opt-in and never auto-injected** — the installer does not edit your
+loop scripts. Both lines are fire-and-forget (`|| true` + the CLI's 5s
+self-timeout), so a failed or slow push can never block or fail your loop.
+
+## Troubleshooting
+
+**Start here:** `gocode-notify status` prints a one-screen report — whether
+credentials are present (and the bound user/label), whether the server is
+reachable, which agent runtimes were detected, and whether each one's config has
+been written. Most issues below are diagnosable from that output.
+
+| Symptom | Likely cause & fix |
+|---|---|
+| `test` / `send` prints **"not paired"** | No `~/.gocode/credentials`. Run `gocode-notify login` and pair from the app (see [Pairing](#pairing--step-by-step)). |
+| **Pairing fails** ("invalid or expired code") | Codes expire after 10 min and are single-use. Tap **"Generate new code"** in the app and re-run `login` with the fresh code. |
+| `status` shows **Server: not reachable** | Network/DNS/firewall, or a wrong server URL. Confirm you can reach `https://oh.jeltechsolutions.com`; check the `--server` flag / `GOCODE_SERVER` env / the `server` field in `~/.gocode/credentials`. |
+| **No push arrives** even though `test` exits 0 | The send is fire-and-forget and exits 0 even on failure — check `~/.gocode/notify.log` for the real error. Also confirm push permissions are granted in the GoCode app and the device token is registered (re-open the app once after signing in). |
+| **Double pings** (two notifications per event) | The agent is calling the `gocode_notify` MCP tool *and* the runtime hook is firing. Re-run `setup` so the anti-double-ping rule/skill is installed; it tells the agent not to notify for automatic done/idle/error events. |
+| **Hook doesn't fire** in Cursor / Claude Code | Re-run `setup` and check `status` shows "config written" for that runtime. Restart the agent app so it reloads `~/.cursor/hooks.json` / `~/.claude/settings.json`. The hooks are merged, never clobbered — your existing hooks are preserved. |
+| **Pushes queue up while offline** then arrive later | Expected. Sends made while the server is unreachable are enqueued to `~/.gocode/outbox/` (size-capped, drop-oldest) and flushed best-effort on the next `send`. A missed "done" ping is acceptable; a blocked agent is not. |
+| **`npx @trygocode/notify` can't find the package** | Make sure you're online and using the scoped name exactly: `npx @trygocode/notify@latest setup`. Clear a stale npx cache with `npx clear-npx-cache` (or `rm -rf ~/.npm/_npx`) and retry. |
+| **Want it gone** | `gocode-notify uninstall` removes exactly the hook/MCP/rule entries this tool added (nothing else). Delete `~/.gocode/` to also drop the stored credentials, and revoke the key from the app's **"Connected agents"** screen. |
+
+**Logs & files.** Failures are appended to `~/.gocode/notify.log` (size-capped,
+rotated to `notify.log.1`). Credentials live in `~/.gocode/credentials` (chmod
+`600`); non-secret prefs in `~/.gocode/config.json`; the offline queue in
+`~/.gocode/outbox/`.
+
+Found a bug or have a feature idea? Please
+[open an issue](https://github.com/joseph-lewis/gocode-notify/issues) — issues are
+welcome and usually get a reply within a day or two.
+
+## Develop
+
+```bash
+git clone https://github.com/joseph-lewis/gocode-notify.git
+cd gocode-notify
+npm install
+npm run build      # compile TypeScript -> dist/
+npm test           # builds, then runs node --test on dist/test/
+npm run typecheck  # type-check only, no emit
+```
+
+Zero runtime dependencies beyond the MCP SDK (Node built-in `fetch`/`fs`/
+`readline` for everything else). Tests use Node's built-in test runner
+(`node:test`).
+
+## Layout
+
+| Path | Purpose |
+|---|---|
+| `src/cli.ts` | `gocode-notify` bin entrypoint + command dispatcher |
+| `src/setup.ts` | Installer orchestration (pair → detect → write configs) |
+| `src/claude.ts` / `src/cursor.ts` | Per-client config writers (hooks + MCP + rule/skill) |
+| `src/send.ts` / `src/login.ts` / `src/mcp.ts` | Core send, pairing, and MCP server |
+| `snippets/ralph-homer.sh` | Opt-in loop completion/halt snippet (trigger C) |
+| `test/` | `node:test` smoke + unit tests |

package/assets/README.md

@@ -0,0 +1,16 @@
+# Assets
+
+Brand assets for **GoCode Notify**.
+
+| File | Used by |
+|---|---|
+| `icon.svg` | MCP server icon metadata (`mimeType: image/svg+xml`, scalable), README, social. |
+| `icon-128.png` | MCP server icon metadata (`128x128`). |
+| `demo.gif` | README hero — the phone notification arriving when an agent finishes. |
+| `logo.png` | GitHub social preview / npm. |
+
+> **Joseph:** drop the real GoCode logo PNG/SVG and a 2-second demo GIF in here
+> (replace the placeholders). Keep filenames identical so the MCP icon URLs and
+> README image links keep resolving. Recommended: `icon.svg` (square, transparent),
+> `icon-128.png` (128×128), `demo.gif` (≤ 3s, ≤ 5 MB), `logo.png` (1280×640 for the
+> GitHub social card).

package/assets/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="GoCode Notify">
+  <!-- Placeholder GoCode Notify mark. Replace with the real GoCode logo (keep this filename). -->
+  <rect width="128" height="128" rx="28" fill="#0B1020"/>
+  <text x="20" y="74" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="40" font-weight="700" fill="#5EE6A8">&gt;_</text>
+  <!-- bell -->
+  <path d="M86 44a14 14 0 0 0-28 0c0 16-6 20-6 24h40c0-4-6-8-6-24z" fill="#FFC857"/>
+  <circle cx="72" cy="92" r="6" fill="#FFC857"/>
+</svg>

package/dist/src/agent.js

@@ -0,0 +1,33 @@
+// Structured, machine-readable progress output for `--agent-driven` mode (PRD §4.4).
+//
+// When any command is invoked with `--agent-driven`, it emits ONE JSON line per
+// step to stdout in the canonical shape
+//   { "step": "...", "ok": true|false, "detail": "..." }
+// so an agent installer (PRD §2 Path 2) can parse and verify each step. In this
+// mode the usual human-readable console output is suppressed — only step lines
+// reach stdout.
+//
+// The emitter takes an injectable {@link StepSink} so tests can collect lines
+// without capturing the real process stdout. Zero runtime deps — Node built-ins
+// only, matching the package's zero-dep rule.
+/**
+ * Serialize a step to its canonical single-line JSON form (PRD §4.4). The field
+ * order is fixed (`step`, `ok`, `detail`) so the output is stable to assert
+ * against and contains no incidental newlines (detail is JSON-escaped).
+ */
+export function formatStep(line) {
+    return JSON.stringify({ step: line.step, ok: line.ok, detail: line.detail });
+}
+/** Default sink: one newline-terminated JSON line per step to stdout. */
+export const stdoutSink = (line) => {
+    process.stdout.write(`${formatStep(line)}\n`);
+};
+/**
+ * True when the parsed flags requested agent-driven (machine-readable) output.
+ * Accepts the bare boolean form (`--agent-driven`) and the explicit
+ * `--agent-driven=true`; any other value (including `=false`) is off.
+ */
+export function isAgentDriven(flags) {
+    const v = flags.get("agent-driven");
+    return v === true || v === "true";
+}

package/dist/src/claude.js

@@ -0,0 +1,287 @@
+// Claude Code config writer (PRD §5.3) — the installer's per-runtime writer for
+// Claude Code. It does three things, all idempotently and without clobbering the
+// user's existing config:
+//
+//   1. MERGE three fire-and-forget hooks into `~/.claude/settings.json`:
+//        Stop          → "finished"        (a turn completed)
+//        Notification  → "awaiting_input"  (the agent needs the user)
+//        SubagentStop  → "finished"        (a subagent completed)
+//      Each hook shells out to `gocode-notify send … || true` so a failed push
+//      NEVER blocks the agent's turn (PRD §4.4, §5.3).
+//   2. MERGE an `mcpServers` entry pointing at `npx -y @trygocode/notify mcp`.
+//   3. WRITE the on-demand skill to `~/.claude/skills/gocode-notify/SKILL.md`
+//      (the anti-double-ping rule, PRD §5.5).
+//
+// MERGE, never clobber: the user's own hooks / MCP servers / top-level settings
+// keys are preserved. Re-running converges (idempotent) — our hook groups and
+// MCP entry are replaced in place, not duplicated. `uninstallClaudeConfig`
+// removes EXACTLY our entries and nothing else (PRD §11, the uninstall test).
+//
+// Our entries are identified by a stable marker (the command contains both
+// `gocode-notify` and `--source claude_code`) so idempotency and uninstall work
+// even across version bumps to the exact command string.
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveHome } from "./creds.js";
+import { buildRuleContent, CLAUDE_FRONTMATTER, CLAUDE_HOOK_DESCRIPTION, } from "./rule-content.js";
+/** Display name of the runtime this writer handles (matches the detector). */
+export const CLAUDE_RUNTIME_NAME = "Claude Code";
+/** MCP server key written into `~/.claude/settings.json` `mcpServers`. */
+export const MCP_SERVER_NAME = "gocode-notify";
+/** The MCP server entry we register (PRD §4.3, §5.4 invocation form). */
+export const MCP_SERVER_ENTRY = {
+    command: "npx",
+    args: ["-y", "@trygocode/notify", "mcp"],
+};
+/**
+ * The hook command for each Claude Code event (PRD §5.3, verbatim shape). Every
+ * command ends in `|| true` so a notification failure can never block the
+ * agent's turn, and carries a per-session `--dedupe-key` so overlapping triggers
+ * (e.g. Cursor `stop` + Claude `Stop`) coalesce server-side.
+ */
+export const CLAUDE_HOOK_COMMANDS = {
+    Stop: 'gocode-notify send --kind finished --source claude_code --dedupe-key "$CLAUDE_SESSION_ID-stop" || true',
+    Notification: 'gocode-notify send --kind awaiting_input --source claude_code --title "Agent needs you" --dedupe-key "$CLAUDE_SESSION_ID-notify" || true',
+    SubagentStop: 'gocode-notify send --kind finished --source claude_code --title "Subagent done" --dedupe-key "$CLAUDE_SESSION_ID-subagent" || true',
+};
+/**
+ * Substrings that together identify a hook command as OURS. Used for idempotent
+ * merge (replace, don't duplicate) and for surgical uninstall (remove exactly
+ * ours). A command must contain BOTH to be considered ours.
+ */
+const HOOK_MARKERS = ["gocode-notify", "--source claude_code"];
+/**
+ * The on-demand skill written to `~/.claude/skills/gocode-notify/SKILL.md`
+ * (PRD §5.5). The crucial content is the anti-double-ping rule: the automatic
+ * pings are owned by the runtime hooks, so the agent must only call the MCP tool
+ * when the user EXPLICITLY asks. Built from the shared {@link buildRuleContent}
+ * so the body stays in lockstep with the Cursor rule.
+ */
+export const SKILL_CONTENT = buildRuleContent({
+    frontmatter: CLAUDE_FRONTMATTER,
+    hookDescription: CLAUDE_HOOK_DESCRIPTION,
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** `~/.claude/` directory for the given (optional) HOME override. */
+function claudeDir(opts) {
+    return path.join(resolveHome(opts), ".claude");
+}
+/** Absolute path to Claude Code's `settings.json`. */
+export function claudeSettingsPath(opts) {
+    return path.join(claudeDir(opts), "settings.json");
+}
+/** Absolute path to the directory holding our skill. */
+export function claudeSkillDir(opts) {
+    return path.join(claudeDir(opts), "skills", "gocode-notify");
+}
+/** Absolute path to our `SKILL.md`. */
+export function claudeSkillPath(opts) {
+    return path.join(claudeSkillDir(opts), "SKILL.md");
+}
+/**
+ * Read a JSON object from `file`. Returns null when the file does not exist.
+ * Throws when it exists but is not a JSON object — so we never silently clobber
+ * a file we failed to parse (the caller surfaces it as a write failure).
+ */
+async function readJsonObject(file) {
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`gocode-notify: ${file} contains invalid JSON`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`gocode-notify: ${file} is not a JSON object`);
+    }
+    return parsed;
+}
+/** Write a JSON object with 2-space indent + trailing newline (matches creds). */
+async function writeJsonFile(file, value) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(value, null, 2) + "\n");
+}
+/** True when a single hook ENTRY (`{ type, command }`) is one we wrote. */
+function isOurHookCommand(h) {
+    return (isRecord(h) &&
+        typeof h.command === "string" &&
+        HOOK_MARKERS.every((m) => h.command.includes(m)));
+}
+/**
+ * Strip OUR hook entries out of an event's group array, operating at the
+ * individual-command level (NOT the whole group): a user group that happens to
+ * also contain one of our commands keeps its other commands. Any group left with
+ * no commands is dropped. Returns the cleaned array plus whether anything of ours
+ * was removed (so callers can detect a real change). Never mutates the input.
+ */
+function stripOurHooks(groups) {
+    let removed = false;
+    const out = [];
+    for (const group of groups) {
+        if (!isRecord(group) || !Array.isArray(group.hooks)) {
+            out.push(group); // unexpected shape → leave the user's data untouched
+            continue;
+        }
+        const kept = group.hooks.filter((h) => !isOurHookCommand(h));
+        if (kept.length !== group.hooks.length)
+            removed = true;
+        if (kept.length === 0)
+            continue; // group held only our command(s) → drop it
+        out.push(kept.length === group.hooks.length ? group : { ...group, hooks: kept });
+    }
+    return { groups: out, removed };
+}
+/** Build the matcher group we add for a single event. */
+function ourHookGroup(command) {
+    return { hooks: [{ type: "command", command }] };
+}
+/**
+ * Merge our three hook events into `settings.hooks`, preserving the user's own
+ * hooks. For each event we strip any prior copy of OUR command (idempotent /
+ * version-safe) — at the command level, so a user command sharing a group with
+ * ours survives — then append a single fresh group. Mutates `settings` in place.
+ */
+function mergeHooks(settings) {
+    const hooks = isRecord(settings.hooks) ? settings.hooks : {};
+    for (const [event, command] of Object.entries(CLAUDE_HOOK_COMMANDS)) {
+        const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const preserved = stripOurHooks(existing).groups;
+        preserved.push(ourHookGroup(command));
+        hooks[event] = preserved;
+    }
+    settings.hooks = hooks;
+}
+/** Merge our MCP server entry into `settings.mcpServers`. Mutates in place. */
+function mergeMcp(settings) {
+    const servers = isRecord(settings.mcpServers) ? settings.mcpServers : {};
+    servers[MCP_SERVER_NAME] = { ...MCP_SERVER_ENTRY, args: [...MCP_SERVER_ENTRY.args] };
+    settings.mcpServers = servers;
+}
+/**
+ * Install Claude Code config (PRD §5.3): merge hooks + MCP entry into
+ * `settings.json` and write the skill. A {@link RuntimeConfigWriter} — never
+ * throws; returns a {@link ConfigWriteResult}. Idempotent: re-running converges
+ * without duplicating our entries.
+ */
+export async function writeClaudeConfig(runtime, opts) {
+    const name = runtime?.name ?? CLAUDE_RUNTIME_NAME;
+    // Track paths as they land so a mid-way failure (e.g. settings written but the
+    // skill write fails) reports what WAS actually written rather than claiming
+    // nothing changed.
+    const written = [];
+    try {
+        await fs.mkdir(claudeDir(opts), { recursive: true });
+        const settingsPath = claudeSettingsPath(opts);
+        const settings = (await readJsonObject(settingsPath)) ?? {};
+        mergeHooks(settings);
+        mergeMcp(settings);
+        await writeJsonFile(settingsPath, settings);
+        written.push(settingsPath);
+        const skillPath = claudeSkillPath(opts);
+        await fs.mkdir(claudeSkillDir(opts), { recursive: true });
+        await fs.writeFile(skillPath, SKILL_CONTENT);
+        written.push(skillPath);
+        return {
+            runtime: name,
+            written,
+            skipped: false,
+            detail: "merged Stop/Notification/SubagentStop hooks + MCP entry; wrote skill",
+        };
+    }
+    catch (err) {
+        return {
+            runtime: name,
+            written,
+            skipped: false,
+            failed: true,
+            detail: `Claude Code config write failed: ${errMessage(err)}`,
+        };
+    }
+}
+/**
+ * Remove EXACTLY the entries this writer added (PRD §11): our three hook groups,
+ * our MCP server entry, and our skill directory. The user's own hooks, MCP
+ * servers, and other settings keys are preserved untouched. Idempotent — a
+ * second run (or a run when nothing was installed) is a clean no-op. Never
+ * throws.
+ */
+export async function uninstallClaudeConfig(opts) {
+    const removed = [];
+    try {
+        const settingsPath = claudeSettingsPath(opts);
+        const settings = await readJsonObject(settingsPath);
+        if (settings) {
+            let changed = false;
+            if (isRecord(settings.hooks)) {
+                const hooks = settings.hooks;
+                for (const event of Object.keys(CLAUDE_HOOK_COMMANDS)) {
+                    if (!Array.isArray(hooks[event]))
+                        continue;
+                    const { groups: kept, removed } = stripOurHooks(hooks[event]);
+                    if (removed)
+                        changed = true;
+                    if (kept.length > 0)
+                        hooks[event] = kept;
+                    else
+                        delete hooks[event];
+                }
+                if (Object.keys(hooks).length === 0)
+                    delete settings.hooks;
+            }
+            if (isRecord(settings.mcpServers) && MCP_SERVER_NAME in settings.mcpServers) {
+                delete settings.mcpServers[MCP_SERVER_NAME];
+                changed = true;
+                if (Object.keys(settings.mcpServers).length === 0)
+                    delete settings.mcpServers;
+            }
+            if (changed) {
+                await writeJsonFile(settingsPath, settings);
+                removed.push(settingsPath);
+            }
+        }
+        // Remove only OUR skill dir, never the whole `skills/` tree. Stat first so
+        // we report it in `removed` only when it actually existed.
+        const skillDir = claudeSkillDir(opts);
+        let skillExisted = false;
+        try {
+            await fs.stat(skillDir);
+            skillExisted = true;
+        }
+        catch (err) {
+            // Only ENOENT means "not installed". A permission/IO error must surface as
+            // a failure, not be silently reported as a clean uninstall.
+            if (err.code !== "ENOENT")
+                throw err;
+            skillExisted = false;
+        }
+        if (skillExisted) {
+            await fs.rm(skillDir, { recursive: true, force: true });
+            removed.push(skillDir);
+        }
+        return {
+            removed,
+            detail: removed.length > 0
+                ? `removed gocode-notify entries (${removed.length} path${removed.length === 1 ? "" : "s"})`
+                : "no gocode-notify entries found",
+        };
+    }
+    catch (err) {
+        return { removed, failed: true, detail: `Claude Code uninstall failed: ${errMessage(err)}` };
+    }
+}