@zeph-to/hook-sdk 1.8.0 → 1.10.0

package/README.md

@@ -1,12 +1,18 @@
 # @zeph-to/hook-sdk
 
-Push notification SDK + CLI for [Zeph](https://zeph.to). Zero dependencies — uses native `fetch`.
+Push notification SDK + CLI for [Zeph](https://zeph.to), with an optional
+resident listener that **drives Claude Code / Codex / Gemini sessions
+from your phone** by injecting messages into named tmux sessions.
+
+- `ZephHook` SDK — native `fetch`, no runtime deps. Send/list/dismiss pushes.
+- `zeph` CLI — install Zeph plugins, send pushes, run agents under tmux,
+  and listen for inbound messages from your phone.
 
 ## Installation
 
 ```bash
-npm install @zeph-to/hook-sdk
-# or
+npm install -g @zeph-to/hook-sdk
+# or for one-off use
 npx @zeph-to/hook-sdk notify --title "Hello"
 ```
 
@@ -20,7 +26,214 @@ npx @zeph-to/hook-sdk install
 npx @zeph-to/hook-sdk install --key ak_... --hook hook_...
 ```
 
-Saves to `~/.zeph/config.json`. All Zeph tools (CLI, MCP server, plugin hooks) read this file.
+Saves to `~/.zeph/config.json`. All Zeph tools (CLI, MCP server, plugin
+hooks, listener) read this file.
+
+To **send** notifications:
+
+```bash
+zeph notify --title "Deploy done" --body "v2.1.0 shipped"
+```
+
+To **drive a Claude Code / Codex / Gemini session from your phone**, see
+[Remote Control](#remote-control) below.
+
+## Remote Control
+
+> Send messages from your phone *into* a live Claude Code / Codex /
+> Gemini session — even after a `zeph_ask` polling window has expired.
+
+The MCP tools `zeph_ask` / `zeph_prompt` / `zeph_input` open a polling
+loop on a fixed timeout (120–600 s). Once that window closes the
+session becomes unaddressable from the phone, even though it's still
+running. The `zeph listener` daemon fixes this by keeping a persistent
+WebSocket open to Zeph and injecting matching messages into a *named*
+tmux session via `tmux send-keys`.
+
+### Architecture
+
+```
+[phone — "Active Agents" picker on Zeph app]
+   │  selects session, types message
+   ▼  POST /pushes/send  { type: 'agent.command',
+   │                       agentSessionName: 'zeph-myapp',
+   │                       body: '리팩토링 마무리해줘' }
+[Zeph backend]
+   │  WebSocket fan-out (push.new)
+   ▼
+[zeph listener — resident daemon, started by `zeph cc` automatically]
+   │  tmux send-keys -l -t zeph-myapp "리팩토링 마무리해줘" + Enter
+   ▼
+[tmux session "zeph-myapp" running claude / codex / gemini]
+```
+
+The listener also reports its tmux session inventory back to the server
+every 5 seconds, so the phone picker stays in sync — no manual
+configuration needed once a session is running.
+
+### Setup
+
+1. **Install tmux.** The listener uses `send-keys`; the wrapper spawns
+   named sessions. `brew install tmux` on macOS, `apt install tmux` on
+   Debian/Ubuntu.
+
+2. **Add `wsUrl` to `~/.zeph/config.json`** (the WebSocket endpoint of
+   your Zeph backend — CDK output `WsApiUrl`):
+
+   ```json
+   {
+     "apiKey": "ak_...",
+     "hookId": "hook_...",
+     "wsUrl": "wss://<api-id>.execute-api.<region>.amazonaws.com/<stage>"
+   }
+   ```
+
+   Alternatively set `ZEPH_WS_URL` in your shell env.
+
+3. **Run agents through the wrapper.** That's it.
+
+   ```bash
+   zeph cc        # claude  → tmux session "zeph-<project>"
+   zeph codex     # codex   → tmux session "zeph-<project>"
+   zeph gemini    # gemini  → tmux session "zeph-<project>"
+   ```
+
+   The first `zeph cc` on a machine **auto-spawns a background
+   listener** (singleton, PID file at `~/.zeph/listener.pid`,
+   stdout/stderr at `~/.zeph/listener.log`). You never run
+   `zeph listener` by hand — every `zeph cc` checks the PID file and
+   skips the spawn when one is already alive, so opening a dozen
+   terminals doesn't create a dozen daemons. The daemon survives
+   between `zeph cc` invocations.
+
+   Project name resolves from `CLAUDE_PROJECT_DIR` /
+   `CURSOR_PROJECT_DIR` / `WINDSURF_PROJECT_DIR` if set, else the git
+   repo root, else the cwd basename. Any extra args after the command
+   pass through to the agent verbatim:
+
+   ```bash
+   zeph cc --resume "abc123"
+   zeph cc --dangerously-skip-permissions
+   zeph codex --model gpt-5-high "fix the failing test"
+   ```
+
+   **Multiple sessions in one project.** Open another terminal in the
+   same folder, run `zeph cc` again, and the wrapper auto-suffixes:
+   first session is `zeph-encl`, the next attached one becomes
+   `zeph-encl-2`, then `zeph-encl-3`, etc. The phone picker shows them
+   as `encl · Claude`, `encl · Claude #2`, `encl · Claude #3`. If
+   `zeph-encl` already exists but is **detached** (no one attached),
+   the wrapper reattaches to it instead of spawning a new one — close
+   the terminal, come back later, pick up where you left off.
+
+   If you're already inside a tmux session (`$TMUX` set) the wrapper
+   skips the outer tmux and runs the agent in the current pane — the
+   listener can't target an unnamed session that way, but you keep your
+   existing multiplexer setup.
+
+### Diagnostics
+
+The auto-spawned listener writes to two files under `~/.zeph/`:
+
+- `listener.pid` — the running daemon's PID. `cat ~/.zeph/listener.pid`
+  + `ps -p <pid>` to confirm it's alive.
+- `listener.log` — stdout + stderr from the daemon. `tail -f` to watch.
+
+A healthy listener log shows one line per cycle:
+
+```
+[xx:xx:xx] reported 2 session(s): zeph-myapp, zeph-otherapp
+[xx:xx:xx] ✓ server persisted 2 session(s)
+```
+
+If you see `! server rejected listener.sessions: ...` instead, the
+message points at the failure (auth, missing device record, etc.) so
+you can fix the actual problem instead of guessing.
+
+To force a restart — e.g. after upgrading `@zeph-to/hook-sdk`:
+
+```bash
+kill $(cat ~/.zeph/listener.pid)
+rm ~/.zeph/listener.pid
+zeph cc        # autospawns the new build
+```
+
+To run it in the foreground (for development of the SDK itself):
+
+```bash
+zeph listener
+```
+
+You'll get the same logs you'd otherwise tail from `listener.log`.
+
+### Custom tmux sockets
+
+The listener auto-discovers the tmux socket — it probes the default
+location, walks per-user `$TMPDIR` paths (macOS `/var/folders/.../T/`),
+falls back to `/tmp/tmux-<uid>/`, and finally finds running tmux servers
+via `lsof` so stale socket files don't trip discovery. If your tmux
+uses `tmux -L <name>` or a non-standard `-S <path>`, set the override
+explicitly:
+
+```bash
+export ZEPH_TMUX_SOCKET=/path/to/socket
+```
+
+(The wrapper passes the env to the auto-spawned listener, so setting
+it in your shell rc is enough.)
+
+### Wire format
+
+The listener only acts on pushes with `type='agent.command'` carrying
+the tmux session name in `agentSessionName` and the message in `body`.
+Other pushes (Stop-hook auto-pushes, `zeph_ask` responses, channel
+broadcasts, plain notes) are ignored. End-to-end:
+
+```
+tmux send-keys -l -t <agentSessionName> "<body>"
+tmux send-keys    -t <agentSessionName> Enter
+```
+
+If you need to send one from the command line (debugging, scripting),
+build the structured push directly:
+
+```bash
+curl -X POST "$ZEPH_BASE_URL/pushes/send" \
+  -H "X-API-Key: $ZEPH_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "agent.command",
+    "targetDeviceId": "dev_listener_<sha8(hostname)>",
+    "agentSessionName": "zeph-myapp",
+    "body": "테스트 통과시키고 PR 올려줘"
+  }'
+```
+
+### Defense
+
+The listener is a remote-code-execution surface by design (it types
+into a shell-adjacent pane). The defense is layered:
+
+1. **Pane guard** — before injecting, the listener checks
+   `tmux display-message -p '#{pane_current_command}'`. If the pane is
+   at an interactive shell (`bash`/`zsh`/`fish`/`sh`/`dash`/`ksh`/
+   `tcsh`/`csh`/`pwsh`), the inject is refused. CC/Codex/Gemini exited
+   ≠ phone gets free shell access.
+2. **Literal injection** — `tmux send-keys -l` takes the payload as
+   data; tmux escape sequences inside a message can't drive other tmux
+   commands.
+3. **Session-name allowlist** — only `[A-Za-z0-9._-]+` is accepted as
+   a session target, so shell metacharacters never reach the tmux argv.
+4. **Per-session rate limit** — 30 injections/minute/session token
+   bucket caps a runaway/compromised sender.
+5. **Agent permission gate stays on** — your CC/Codex/Gemini permission
+   prompt is still in front of every destructive tool call. The phone
+   can *talk* but can't approve `rm -rf` for you.
+
+The transport (WS) is currently authenticated by API key + `push:read`
+scope and is **not** end-to-end encrypted in v1 — your Zeph backend
+sees the message plaintext. If you self-host or trust your backend,
+that's fine. If you don't, hold off until per-device E2E ships.
 
 ## CLI Usage
 
@@ -42,6 +255,15 @@ zeph dismiss --all
 # Test connection
 zeph test
 
+# Run an agent in a named tmux session (so the listener can reach it)
+zeph cc                       # claude
+zeph codex                    # codex
+zeph gemini                   # gemini
+
+# Run the resident listener (foreground; background it as you like)
+zeph listener
+zeph listener --ws-url wss://...   # override config
+
 # JSON output
 zeph notify --title "Hello" --json
 ```
@@ -58,6 +280,8 @@ zeph notify --title "Hello" --json
 | `list` | List recent push notifications |
 | `dismiss <id>` | Dismiss a push (or `--all`) |
 | `test` | Verify connection and API key |
+| `cc` · `codex` · `gemini` | Run the agent in a `zeph-<project>` tmux session (auto-suffixed `-2`, `-3`, … on attached collisions). Auto-spawns the background listener on first invocation so the phone picker just works. Trailing args pass through to the agent (`zeph cc --resume "..."`) |
+| `listener` | (Usually unnecessary — `zeph cc` autospawns it.) Resident daemon: subscribes via WebSocket, reports tmux session inventory every 5 s, injects `agent.command` pushes into the matching session. Run in the foreground for SDK development; otherwise let `zeph cc` manage it |
 
 ### Notify Options
 
@@ -70,7 +294,22 @@ zeph notify --title "Hello" --json
 | `--priority <p>` | Priority: `low`, `normal`, `high`, `urgent` |
 | `--device <id>` | Target device ID |
 
-The defaults are tuned for hook-driven invocations (e.g. Stop hooks calling `zeph notify --title "Task done"` without a body) — you'll see which project + branch finished without writing per-IDE wrappers. Pass `--body ""` explicitly to suppress.
+The defaults are tuned for hook-driven invocations (e.g. Stop hooks
+calling `zeph notify --title "Task done"` without a body) — you'll see
+which project + branch finished without writing per-IDE wrappers. Pass
+`--body ""` explicitly to suppress.
+
+### Listener Options
+
+| Flag | Description |
+|------|-------------|
+| `--ws-url <url>` | WebSocket endpoint (or set `ZEPH_WS_URL` env, or `wsUrl` in `~/.zeph/config.json`) |
+| `--key <api-key>` | API key (or set `ZEPH_API_KEY` env) |
+
+The listener reconnects with exponential backoff + jitter (1 s → 30 s
+cap). Heartbeat is ping every 25 s with a 10 s pong timeout. On an
+authentication failure close (4001/4002/4003) the listener exits with
+code 3 instead of looping forever — fix the key and restart.
 
 ### List Options
 
@@ -90,9 +329,11 @@ The defaults are tuned for hook-driven invocations (e.g. Stop hooks calling `zep
 
 ### Mute
 
-Mute is project-scoped (uses project directory hash). Created by Claude Code `/zeph-mute` command.
+Mute is project-scoped (uses project directory hash). Created by Claude
+Code `/zeph-mute` command.
 
-Notifications are silently skipped when a mute file exists for the current project:
+Notifications are silently skipped when a mute file exists for the
+current project:
 
 ```bash
 # Mute (created by /zeph-mute in Claude Code plugin)
@@ -103,7 +344,8 @@ touch /tmp/zeph-muted-$HASH
 rm /tmp/zeph-muted-$HASH
 ```
 
-The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`, `WINDSURF_PROJECT_DIR`, and falls back to `cwd`.
+The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`,
+`WINDSURF_PROJECT_DIR`, and falls back to `cwd`.
 
 ### Exit Codes
 
@@ -112,7 +354,8 @@ The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`, `WINDSURF_PROJECT_DIR
 | 0 | Success |
 | 1 | General error |
 | 2 | Quota exceeded |
-| 3 | Authentication failed |
+| 3 | Authentication failed (also: listener auth close 4001/4002/4003) |
+| 127 | A required external binary (e.g. `tmux`, `claude`) was not found on PATH |
 
 ### Environment Variables
 
@@ -120,6 +363,9 @@ The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`, `WINDSURF_PROJECT_DIR
 |----------|-------------|
 | `ZEPH_API_KEY` | API key (fallback when `--key` not provided) |
 | `ZEPH_BASE_URL` | API base URL (default: `https://api.zeph.to/v1`) |
+| `ZEPH_WS_URL` | WebSocket endpoint for `zeph listener` (no default — required) |
+| `ZEPH_TMUX_SOCKET` | Explicit tmux socket path for the listener (skips auto-discovery — use when your tmux runs with `-L <name>` or a custom `-S <path>`) |
+| `ZEPH_SESSION_ID` | AI session ID (fallback when `--session` not provided) |
 
 ## SDK Usage
 
@@ -193,16 +439,39 @@ try {
 | Copilot CLI | Session end hook |
 | Cline | Rules file |
 
-## Encryption
+For remote-control via `zeph listener` the per-agent setup is the same
+across CC/Codex/Gemini — the wrapper just spawns them in a named tmux
+session.
 
-Push bodies are encrypted with AES-256-GCM. The wrapping key is derived via ECDH P-256 and synced across your own devices on first run so every device can read the same push. Toggle encryption in the Zeph app (Settings → Encryption); when disabled, the CLI sends plaintext. No configuration needed.
+## Encryption
 
-**Threat model honesty:** keys are persisted on the Zeph backend to enable cross-device sync, so this is *device-shared* encryption — not true end-to-end. It protects push contents from passive network observers and from a leaked database snapshot taken without the key store, but it does **not** protect against the Zeph backend itself (it has the keys it serves to your devices). A true E2E mode (per-device keypairs, server stores only public keys, no key escrow) is on the roadmap.
+Push bodies are encrypted with AES-256-GCM. The wrapping key is derived
+via ECDH P-256 and synced across your own devices on first run so every
+device can read the same push. Toggle encryption in the Zeph app
+(Settings → Encryption); when disabled, the CLI sends plaintext. No
+configuration needed.
+
+**Threat model honesty:** keys are persisted on the Zeph backend to
+enable cross-device sync, so this is *device-shared* encryption — not
+true end-to-end. It protects push contents from passive network
+observers and from a leaked database snapshot taken without the key
+store, but it does **not** protect against the Zeph backend itself (it
+has the keys it serves to your devices). A true E2E mode (per-device
+keypairs, server stores only public keys, no key escrow) is on the
+roadmap.
+
+The `zeph listener` ignores `isEncrypted` pushes for now — it has no
+per-device key to decrypt them. Stop-hook auto-pushes and `zeph_ask`
+responses are not part of the `@<session>` injection path, so this
+doesn't affect normal use.
 
 ## Requirements
 
-- Node.js >= 18 (uses native `fetch`)
-- Zero runtime dependencies
+- **Node.js >= 18** (uses native `fetch`).
+- **tmux** — required for `zeph cc` / `codex` / `gemini` and `zeph listener`.
+- The `ZephHook` SDK has no runtime dependencies. The CLI depends on
+  `@inquirer/prompts` for the interactive `zeph install` picker and on
+  `ws` for the listener's WebSocket subscription.
 
 ## License
 

package/dist/cli.js

@@ -9,6 +9,8 @@ const installer_js_1 = require("./installer.js");
 const uninstall_js_1 = require("./uninstall.js");
 const verify_js_1 = require("./verify.js");
 const check_update_js_1 = require("./check-update.js");
+const wrapper_js_1 = require("./wrapper.js");
+const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
 const PROJECT_DIR_VARS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
 const detectProjectDir = () => PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
@@ -76,6 +78,16 @@ Commands:
   list            List recent push notifications
   dismiss <id>    Dismiss a push notification (or --all)
   test            Send a test notification to verify setup
+  cc [args…]      Run 'claude' in a named tmux session ('zeph-<project>')
+  codex [args…]   Run 'codex' in a named tmux session
+  gemini [args…]  Run 'gemini' in a named tmux session
+                  (auto-suffixed -2/-3/… when another zeph cc is already
+                   attached to the default name; any args after the
+                   subcommand are forwarded verbatim, e.g.
+                   'zeph cc --resume')
+  listener        Resident daemon — receives 'agent.command' pushes from
+                  the phone picker and injects them into the matching
+                  tmux session.
 
 Notify options:
   --title <text>     Push title
@@ -97,6 +109,9 @@ Install options:
   --key <api-key>    API key (non-interactive)
   --hook <hook-id>   Hook ID (non-interactive)
   --base-url <url>   Base URL (non-interactive)
+  --only <agents>    Comma-separated agent ids to install for
+                     (claude,cursor,windsurf,gemini,codex,copilot,cline,aider).
+                     Skips the interactive picker.
 
 Uninstall options:
   --dry-run          Preview what would be removed, change nothing
@@ -291,6 +306,16 @@ const handleError = (err, isJson) => {
     printError(err instanceof Error ? err.message : 'Unknown error', isJson);
     return 1;
 };
+// ── Passthrough ─────────────────────────────────────────────────
+/**
+ * Collect raw argv after the given subcommand token so flags like
+ * `--resume` reach the wrapped agent verbatim instead of being swallowed
+ * by `parseArgs`. Returns [] when the command isn't found.
+ */
+const collectPassthrough = (argv, cmd) => {
+    const idx = argv.indexOf(cmd, 2);
+    return idx >= 0 ? argv.slice(idx + 1) : [];
+};
 // ── Main ────────────────────────────────────────────────────────
 const main = async () => {
     const args = parseArgs(process.argv);
@@ -321,6 +346,14 @@ const main = async () => {
             return handleDismiss(args);
         case 'test':
             return handleTest(args);
+        case 'cc':
+            return (0, wrapper_js_1.handleAgentSession)('claude', collectPassthrough(process.argv, 'cc'));
+        case 'codex':
+            return (0, wrapper_js_1.handleAgentSession)('codex', collectPassthrough(process.argv, 'codex'));
+        case 'gemini':
+            return (0, wrapper_js_1.handleAgentSession)('gemini', collectPassthrough(process.argv, 'gemini'));
+        case 'listener':
+            return (0, listener_js_1.handleListener)(args);
         default:
             printError(`Unknown command: ${command}`, args.json === true);
             printUsage();

package/dist/config.d.ts

@@ -4,6 +4,7 @@ export interface ZephConfig {
     apiKey?: string;
     hookId?: string;
     baseUrl?: string;
+    wsUrl?: string;
     deviceId?: string;
 }
 export declare const resolvedEnv: (key: string) => string | undefined;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}

package/dist/installer.d.ts

@@ -1,2 +1,9 @@
+import type { Agent } from './agents.js';
+/**
+ * Resolve agents from a non-interactive `--only cursor,gemini` flag.
+ * Matches on agent id; unknown ids are silently dropped. Exported for
+ * unit testing.
+ */
+export declare const filterAgentsByIds: (detected: Agent[], only: string) => Agent[];
 export declare const handleInstall: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=installer.d.ts.map

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AA4RA,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAoH1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAwSzC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AAqBF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4H1F,CAAC"}

package/dist/installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInstall = void 0;
+exports.handleInstall = exports.filterAgentsByIds = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -251,6 +251,52 @@ const AGENT_INSTALLERS = {
     cline: installCline,
     aider: installAider,
 };
+// One-line summary of what each agent's installer does — shown in the
+// interactive plan before anything is written.
+const AGENT_PLAN_LABELS = {
+    claude: 'Claude Code — install plugin',
+    cursor: 'Cursor — MCP + hooks + rules',
+    windsurf: 'Windsurf — MCP + hooks + rules',
+    gemini: 'Gemini CLI — MCP + hooks + rules',
+    codex: 'Codex CLI — hooks + rules',
+    copilot: 'Copilot CLI — hooks + rules',
+    cline: 'Cline — rules',
+    aider: 'Aider — conventions',
+};
+// ── Agent selection ──────────────────────────────────────────────
+/**
+ * Interactive agent picker — an @inquirer/prompts checkbox (arrow keys
+ * to move, space to toggle, enter to confirm). Every agent starts
+ * checked, so a bare Enter installs for all. Returns the chosen Agent[].
+ *
+ * Dynamic import keeps @inquirer/prompts (ESM) loadable from this
+ * CommonJS build, and means the dependency is only touched on the
+ * interactive path — `notify` / `list` / scripted `install --only`
+ * never load it.
+ */
+const pickAgentsInteractive = async (detected) => {
+    const { checkbox } = await import('@inquirer/prompts');
+    const picked = await checkbox({
+        message: 'Install Zeph for which agents? (space to toggle, enter to confirm)',
+        choices: detected.map((agent) => ({
+            name: AGENT_PLAN_LABELS[agent.id] ?? agent.name,
+            value: agent.id,
+            checked: true,
+        })),
+        loop: false,
+    });
+    return detected.filter((a) => picked.includes(a.id));
+};
+/**
+ * Resolve agents from a non-interactive `--only cursor,gemini` flag.
+ * Matches on agent id; unknown ids are silently dropped. Exported for
+ * unit testing.
+ */
+const filterAgentsByIds = (detected, only) => {
+    const ids = new Set(only.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean));
+    return detected.filter((a) => ids.has(a.id));
+};
+exports.filterAgentsByIds = filterAgentsByIds;
 // ── Test Connection ──────────────────────────────────────────────
 const testConnection = async (apiKey, baseUrl) => {
     try {
@@ -291,7 +337,32 @@ const handleInstall = async (args) => {
     if (detected.length === 0) {
         console.log('\n  No supported agents found. Config will still be saved.\n');
     }
-    // 2. Collect credentials
+    // 2. Choose which agents to install for — asked up front so the user
+    //    sees the choice before being walked through credential prompts.
+    let selected = detected;
+    const onlyArg = args.only?.trim();
+    if (detected.length > 0) {
+        if (onlyArg) {
+            // Non-interactive or scripted: --only cursor,gemini
+            selected = (0, exports.filterAgentsByIds)(detected, onlyArg);
+            console.log(`\n  --only ${onlyArg} → ${selected.map((a) => a.name).join(', ') || '(no match)'}`);
+        }
+        else if (nonInteractive) {
+            // Scripted run with no --only: keep the all-detected default
+            selected = detected;
+        }
+        else {
+            try {
+                selected = await pickAgentsInteractive(detected);
+            }
+            catch {
+                // Ctrl-C in the picker (or no TTY) — treat as a clean cancel.
+                console.log('\n  Cancelled.\n');
+                return 0;
+            }
+        }
+    }
+    // 3. Collect credentials
     const existing = (0, config_js_1.loadConfig)();
     let apiKey;
     let hookId;
@@ -321,33 +392,19 @@ const handleInstall = async (args) => {
         console.error('\n  Error: API key is required.\n');
         return 1;
     }
-    // 3. Confirmation (interactive only)
+    // 4. Show the resolved plan before touching anything (interactive only).
     if (!nonInteractive) {
         console.log('\n  Will do:');
-        console.log('    1. Save config to ~/.zeph/config.json');
-        let step = 2;
-        for (const agent of detected) {
-            const labels = {
-                claude: 'Install Claude Code plugin',
-                cursor: 'Setup Cursor (MCP + hooks + rules)',
-                windsurf: 'Setup Windsurf (MCP + hooks + rules)',
-                gemini: 'Setup Gemini CLI (MCP + hooks + rules)',
-                codex: 'Setup Codex CLI (hooks + rules)',
-                copilot: 'Setup Copilot CLI (hooks + rules)',
-                cline: 'Setup Cline (rules)',
-                aider: 'Setup Aider (conventions)',
-            };
-            console.log(`    ${step}. ${labels[agent.id] ?? `Install for ${agent.name}`}`);
-            step++;
+        console.log(`    - Save config to ${config_js_1.CONFIG_FILE}`);
+        for (const agent of selected) {
+            console.log(`    - ${AGENT_PLAN_LABELS[agent.id] ?? `Install for ${agent.name}`}`);
         }
-        console.log(`    ${step}. Test connection`);
-        const confirm = await promptInput('  Continue? [Y/n] ');
-        if (confirm.toLowerCase() === 'n') {
-            console.log('\n  Cancelled.\n');
-            return 0;
+        if (selected.length === 0) {
+            console.log('    (no agents selected — only the config file will be saved)');
         }
+        console.log('    - Test connection');
     }
-    // 4. Save config
+    // 5. Save config
     console.log('');
     const config = {
         apiKey,
@@ -356,14 +413,14 @@ const handleInstall = async (args) => {
     };
     (0, config_js_1.saveConfig)(config);
     ok(`Config saved to ${config_js_1.CONFIG_FILE}`);
-    // 5. Install per-agent
-    for (const agent of detected) {
+    // 6. Install for the selected agents only
+    for (const agent of selected) {
         console.log(`\n  Installing for ${agent.name}...`);
         const installer = AGENT_INSTALLERS[agent.id];
         if (installer)
             installer();
     }
-    // 6. Test connection
+    // 7. Test connection
     console.log('\n  Testing connection...');
     await testConnection(apiKey, baseUrl);
     console.log('\n  Done! Restart your agents.\n');