pair-mode 0.2.0 → 0.3.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "pair-mode",
+  "version": "0.3.0",
+  "description": "Hold every proposed edit, annotate the diff line by line, and hand the notes back to the agent.",
+  "author": {
+    "name": "ofrusch",
+    "email": "owenc343@gmail.com"
+  },
+  "homepage": "https://github.com/oFrusch/pair-mode#readme",
+  "repository": "https://github.com/oFrusch/pair-mode.git",
+  "license": "MIT"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "pair-mode",
+  "version": "0.3.0",
+  "description": "Hold every proposed edit, annotate the diff line by line, and hand the notes back to the agent.",
+  "author": {
+    "name": "ofrusch",
+    "url": "https://github.com/oFrusch"
+  },
+  "homepage": "https://github.com/oFrusch/pair-mode#readme",
+  "license": "MIT",
+  "keywords": [
+    "code-review",
+    "diff",
+    "hooks",
+    "pair-programming",
+    "terminal"
+  ],
+  "hooks": "./hooks/codex.json",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Pair Mode",
+    "shortDescription": "Review each proposed edit before it lands",
+    "longDescription": "Pair mode intercepts every proposed edit. It renders the diff in a terminal pane or a browser page, collects notes anchored to line numbers, then holds the edit and returns those notes to the agent. A review you close with no notes applies the edit as proposed.",
+    "developerName": "ofrusch",
+    "category": "Engineering",
+    "websiteURL": "https://github.com/oFrusch/pair-mode",
+    "logo": "./assets/duck.png"
+  }
+}

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://raw.githubusercontent.com/oFrusch/pair-mode/main/docs/images/duck.png" alt="The pair-mode duck" width="120" align="right">
+
 # pair mode
 
 #### For when your agent needs a rubber ducky.
@@ -19,6 +21,28 @@ npm install -g pair-mode
 pair-mode setup
 ```
 
+### Or install it as a plugin
+
+A plugin resolves its own path at runtime, so it needs no global install and no setup step.
+
+Claude Code:
+
+```
+/plugin marketplace add oFrusch/pair-mode
+/plugin install pair-mode
+```
+
+Codex:
+
+```
+codex plugin marketplace add oFrusch/pair-mode
+codex plugin add pair-mode@pair-mode
+```
+
+The plugin registers the hook and the `/pair` command for that one CLI. Run
+`npm install -g pair-mode` as well if you want the `pair-mode` command on your PATH, which
+`pair-mode watch` and `pair-mode config` need.
+
 Install pair-mode globally before you run setup. Setup writes the install path into each CLI's config as an absolute path. `npx pair-mode setup` runs from a package cache that npm later prunes, which would leave every hook pointing at a deleted file. Setup detects that case and stops.
 
 The setup command detects the CLIs and multiplexers on your machine, registers the

package/commands/pair.md

@@ -0,0 +1,18 @@
+---
+description: Toggle pair mode. Every proposed edit opens in the pair review pane for line annotation.
+allowed-tools: Bash(node:*)
+---
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" $ARGUMENTS` and report the resulting state in one line.
+
+With no action, run it with `status`.
+
+Pair mode intercepts your Write, Edit, and MultiEdit calls. The user reads the proposed diff in the
+pair review pane, selects lines, and attaches notes. Pair mode then holds the edit and
+returns those notes as questions anchored to line numbers. Answer every question. Do not
+re-attempt the edit until the user asks for it. An edit the user closes with no notes
+applies as proposed.
+
+Pair mode keys the flag by the real directory path, and the hook walks up from the edited
+file. A flag on a parent directory therefore covers every repo beneath it. If pair mode
+stays on after an `off`, check each parent with `status <dir>`.

package/dist/cli.js

@@ -7361,7 +7361,7 @@ var require_dist = __commonJS({
 });
 
 // src/cli/index.ts
-import { readFileSync as readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync8 } from "node:fs";
 import { join as join13, resolve as resolve2 } from "node:path";
 
 // src/cli/setup/setup.ts
@@ -12156,6 +12156,7 @@ function runTui(options, io, abort) {
 var TITLE = "pair-mode watch";
 var HINT = "waiting for an edit \xB7 q quits";
 var LABEL_WIDTH = 10;
+var DUCK = ["   __", " <(o )___", "  ( ._> /", "   `---'"];
 function line(label, value, truecolor) {
   return fg(theme.fold, truecolor) + label.padEnd(LABEL_WIDTH) + RESET + value;
 }
@@ -12167,9 +12168,12 @@ function queueText(waiting) {
 }
 function renderIdle(status, width, truecolor) {
   const heading = bg(theme.chrome, truecolor) + fg(theme.statusText, truecolor) + TITLE.padEnd(width).slice(0, width) + RESET;
+  const duck = DUCK.map((row) => fg(theme.chrome, truecolor) + row + RESET);
   return [
     heading,
     "",
+    ...duck,
+    "",
     line("session", status.directory, truecolor),
     line("socket", status.socketPath, truecolor),
     line("clients", plural(status.clients, "client"), truecolor),
@@ -12597,6 +12601,8 @@ function runConfig(args, path) {
 // src/web/server.ts
 import { createServer as createServer2 } from "node:http";
 import { randomBytes as randomBytes4 } from "node:crypto";
+import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // src/web/client/bundle.ts
 var CLIENT_BUNDLE = `"use strict";
@@ -12946,7 +12952,8 @@ header {
 }
 
 header .seg { padding: 6px 13px; white-space: nowrap; }
-header .mode { background: var(--amber); color: ${theme.statusText}; font-weight: 700; letter-spacing: 0.1em; }
+header .mode { display: flex; align-items: center; gap: 7px; color: var(--amber); font-weight: 700; letter-spacing: 0.1em; }
+header .mark { border-radius: 4px; }
 header .path { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; color: var(--muted); }
 header .plus { color: var(--add-bar); }
 header .minus { color: var(--del-bar); }
@@ -13170,7 +13177,15 @@ textarea {
 
 .hint { color: var(--dim); font-size: 11px; }
 
-#idle { padding: 64px 24px; color: var(--dim); text-align: center; }
+#idle { padding: 72px 24px; color: var(--dim); text-align: center; }
+#idle img { border-radius: 14px; opacity: 0.75; animation: bob 3.2s ease-in-out infinite; }
+#idle p { margin: 16px 0 0; }
+
+@keyframes bob { 50% { transform: translateY(-6px); } }
+
+@media (prefers-reduced-motion: reduce) {
+  #idle img { animation: none; }
+}
 
 @media (max-width: 900px) {
   main { flex-wrap: wrap; }
@@ -13181,6 +13196,7 @@ textarea {
 `;
 var WIRING = String.raw`
 const C = PairClient;
+const assets = document.body.dataset.assets ?? "";
 const token = location.pathname.split("/")[2];
 const main = document.querySelector("main");
 const diff = document.getElementById("diff");
@@ -13291,7 +13307,8 @@ function renderMargin() {
 
 function render() {
   if (review === null) {
-    diff.innerHTML = '<div id="idle">waiting for an edit</div>';
+    diff.innerHTML =
+      '<div id="idle"><img src="' + assets + '/duck.png" alt="" width="88" height="88"><p>waiting for an edit</p></div>';
     pathLabel.textContent = "no review open";
     plusLabel.textContent = "";
     minusLabel.textContent = "";
@@ -13563,18 +13580,19 @@ ${WIRING}`);
 function pressed(layout, wanted) {
   return layout === wanted ? "true" : "false";
 }
-function renderPage(layout = "split") {
+function renderPage(layout = "split", assetBase = "") {
   return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" type="image/png" href="${assetBase}/favicon.png">
 <title>pair mode</title>
 <style>${STYLE}</style>
 </head>
-<body data-layout="${layout}">
+<body data-layout="${layout}" data-assets="${assetBase}">
 <header>
-  <span class="seg mode">PAIR</span>
+  <span class="seg mode"><img class="mark" src="${assetBase}/duck.png" alt="" width="18" height="18">pair</span>
   <span class="seg path" id="path">no review open</span>
   <span class="seg plus" id="plus"></span>
   <span class="seg minus" id="minus"></span>
@@ -13647,6 +13665,15 @@ function webNotesToQuestions(review, notes) {
 var HOST = "127.0.0.1";
 var TOKEN_BYTES = 16;
 var MAX_BODY_BYTES = 1e6;
+function readAsset(name) {
+  const bundled = fileURLToPath4(new URL(`../assets/${name}`, import.meta.url));
+  const source = fileURLToPath4(new URL(`../../assets/${name}`, import.meta.url));
+  return readFileSync7(existsSync10(bundled) ? bundled : source);
+}
+var IMAGES = {
+  "favicon.png": readAsset("favicon.png"),
+  "duck.png": readAsset("duck.png")
+};
 var NOT_FOUND = 404;
 var OK = 200;
 var BAD_REQUEST = 400;
@@ -13778,7 +13805,13 @@ data: ${data}
     const url = request.url ?? "";
     if (url === base && request.method === "GET") {
       response.writeHead(OK, { "content-type": "text/html; charset=utf-8" });
-      response.end(renderPage(options.layout));
+      response.end(renderPage(options.layout, base));
+      return;
+    }
+    const image = url.startsWith(`${base}/`) ? IMAGES[url.slice(base.length + 1)] : void 0;
+    if (image !== void 0 && request.method === "GET") {
+      response.writeHead(OK, { "content-type": "image/png" });
+      response.end(image);
       return;
     }
     if (url === `${base}/events` && request.method === "GET") {
@@ -13947,7 +13980,7 @@ Commands:
 function readVersion() {
   const pkgPath = join13(installRoot(), "package.json");
   try {
-    const raw = JSON.parse(readFileSync7(pkgPath, "utf-8"));
+    const raw = JSON.parse(readFileSync8(pkgPath, "utf-8"));
     if (isRecord(raw) && typeof raw["version"] === "string") {
       return raw["version"];
     }

package/hooks/codex.json

@@ -0,0 +1,17 @@
+{
+  "description": "Pair mode holds a proposed edit so the user can annotate the diff line by line.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/dist/codex.js\"",
+            "timeout": 600
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude-code.js\"",
+            "timeout": 600
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-mode",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Annotate a coding agent's proposed edits line by line, in your terminal.",
   "keywords": [
     "ai",
@@ -31,6 +31,11 @@
   "files": [
     "dist",
     "assets",
+    ".claude-plugin/plugin.json",
+    ".codex-plugin/plugin.json",
+    "hooks",
+    "commands",
+    "skills",
     "README.md"
   ],
   "type": "module",

package/skills/pair/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: pair
+description: Toggle pair mode. Every proposed edit opens in the pair review pane for line annotation.
+---
+
+Read the action from the user's message, then run `pair-mode <action>` and report the resulting state in one line.
+
+With no action, run `pair-mode status`.
+
+Pair mode intercepts your apply_patch, Write, and Edit calls. The user reads the proposed diff in the
+pair review pane, selects lines, and attaches notes. Pair mode then holds the edit and
+returns those notes as questions anchored to line numbers. Answer every question. Do not
+re-attempt the edit until the user asks for it. An edit the user closes with no notes
+applies as proposed.
+
+Pair mode keys the flag by the real directory path, and the hook walks up from the edited
+file. A flag on a parent directory therefore covers every repo beneath it. If pair mode
+stays on after an `off`, check each parent with `pair-mode status <dir>`.
+
+The `pair-mode` command must resolve on PATH. Install it with `npm install -g pair-mode`.