Skip to content

A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.

Docs: Coucou for agents on a remote machine

NikitaBulichev65cad9d32b1d
diff --git a/README.md b/README.md
index 2f7fd0e2..a2da4d99 100644
--- a/README.md
+++ b/README.md
@@ -409,6 +409,8 @@ ENGINE_TYPE=baileys SSRF_ALLOWED_HOSTS=127.0.0.1 npm run start:prod
OpenCode, Amp and Hermes use a plugin model rather than a hook command. Coucou installs the plugin file into `~/.config/opencode/plugins/`, `~/.config/amp/plugins/` and `~/.hermes/plugins/coucou/` respectively. On Windows and Linux the plugins start the `coucou-hook` relay directly — see [`windows/README.md`](windows/README.md#supported-agents).
+Agents running on a server (VS Code Remote - SSH, an SSH environment in the Claude app, Codex on a dev box) can reach Coucou on your Mac through an SSH tunnel: see [`docs/REMOTE.md`](docs/REMOTE.md).
+
## Things to try
| Do this | Mochi does that |
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 7621e8c8..5a5459a2 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -71,6 +71,8 @@ Send newline-terminated JSON to the socket:
- **Windows:** `\\.\pipe\coucou-<user-SID>`
- **Linux:** `$XDG_RUNTIME_DIR/coucou.sock` (usually `/run/user/<uid>/coucou.sock`). Only your own user account can connect.
+The Mac relay, `nb-hook`, uses another socket when `COUCOU_SOCKET` is set. That is how an agent on a remote machine reaches the Mac through an SSH tunnel: see [`REMOTE.md`](REMOTE.md).
+
## Supported events
All standard Claude Code hook events are supported, **except `PermissionRequest`**:
diff --git a/docs/REMOTE.md b/docs/REMOTE.md
new file mode 100644
index 00000000..156c9c6f
--- /dev/null
+++ b/docs/REMOTE.md
@@ -0,0 +1,173 @@
+# Coucou for agents on a remote machine (SSH)
+
+Claude Code and Codex sessions that run on a server (VS Code Remote - SSH, an SSH
+environment in the Claude app's Code tab, Codex on a dev box) can show up in Coucou on
+your Mac like local ones, approvals and questions included, on the iPhone too. Their
+hooks talk to a socket on the server, and an SSH tunnel opened by the Mac forwards that
+socket to Coucou:
+
+```
+agent on the server → nb-hook → socket on the server ──ssh -R──▶ nb.sock on the Mac → Coucou
+```
+
+The server needs `python3` and an SSH server. Nothing listens on a network port, and the
+server never has to reach the Mac: the Mac opens the connection.
+
+## 1. The relay on the server
+
+Copy the relay from the Mac. The GitHub build keeps it in
+`~/Library/Application Support/NotchBuddy/`, the App Store build in `~/.claude/coucou/`:
+
+```sh
+ssh myserver 'mkdir -p ~/.coucou && chmod 700 ~/.coucou'
+scp ~/Library/Application\ Support/NotchBuddy/nb-hook ~/Library/Application\ Support/NotchBuddy/nb-hook.py myserver:.coucou/
+```
+
+Copy both files again after updating Coucou: the relay changes with the app.
+
+Off the Mac, `nb-hook` runs the `python3` in `PATH`. The relay looks for the socket where
+Coucou keeps it on a Mac (`~/Library/Application Support/NotchBuddy/nb.sock` for the
+GitHub relay, the container path for the App Store one), so the tunnel below forwards to
+that path. To use another path, set `COUCOU_SOCKET`; Claude Code runs hook commands in a
+shell, so it can go in the command: `COUCOU_SOCKET=/run/user/1000/coucou-mac.sock "$HOME/.coucou/nb-hook"`.
+
+## 2. The hooks on the server
+
+**Claude Code** — the server's `~/.claude/settings.json` gets the hooks Coucou adds on the
+Mac, with the server's path. The simplest is to copy the entries whose command contains
+`NotchBuddy` from the Mac's `~/.claude/settings.json` and change the path. Every event runs
+`"$HOME/.coucou/nb-hook"` with a 10 s timeout (`SessionStart`, `SessionEnd`,
+`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`,
+`Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`), `PermissionRequest` waits up to
+120 s, and questions have their own `PreToolUse` entry:
+
+```json
+{
+ "hooks": {
+ "PermissionRequest": [
+ { "hooks": [{ "type": "command", "command": "\"$HOME/.coucou/nb-hook\"", "timeout": 120 }] }
+ ],
+ "PreToolUse": [
+ { "hooks": [{ "type": "command", "command": "\"$HOME/.coucou/nb-hook\"", "timeout": 10 }] },
+ { "matcher": "AskUserQuestion",
+ "hooks": [{ "type": "command", "command": "\"$HOME/.coucou/nb-hook\" --ask", "timeout": 130 }] }
+ ]
+ }
+}
+```
+
+**Codex** — the server's `~/.codex/hooks.json` gets the entries Coucou adds on the Mac
+(Settings → Codex → Install hooks), with `"$HOME/.coucou/nb-hook" --agent codex`. Codex
+approvals in the notch need the GitHub build. Recent Codex versions only run hooks they
+trust (`hooks.state` in `~/.codex/config.toml`): trust the new ones in Codex, and start a
+new chat, since a running one keeps the hooks it started with.
+
+## 3. The tunnel on the Mac
+
+```sh
+SERVER=myserver
+LOCAL="$HOME/Library/Application Support/NotchBuddy/nb.sock"
+# Creates the folder on the server, removes a socket left by an earlier connection, prints the path.
+REMOTE=$(ssh "$SERVER" 'd="$HOME/Library/Application Support/NotchBuddy"; mkdir -p "$d" && chmod 700 "$d" && rm -f "$d/nb.sock" && printf %s "$d/nb.sock"')
+ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=15 -o ServerAliveCountMax=3 \
+ -R "$REMOTE:$LOCAL" "$SERVER"
+```
+
+- **Remove the old socket first.** When a connection drops, sshd leaves the socket file
+ behind, and the next `ssh -R` fails with `remote port forwarding failed for listen
+ path` — unless the server's `sshd_config` says `StreamLocalBindUnlink yes`. The leftover
+ file does no harm meanwhile: connecting to it fails at once, and the agent carries on.
+- Use the absolute path on the server; its folder must exist (the first command does both).
+- App Store build: `LOCAL` is `~/Library/Containers/fr.louisraille.Coucou/Data/nb.sock`.
+- sshd creates the socket with mode `0600` (`StreamLocalBindMask`), so only your user on
+ the server, and root, can reach it. Whoever can act as your user there can put cards in
+ your notch and read your answers: keep that in mind on a shared machine.
+
+To keep the tunnel up, put the two commands in a script, add `-o BatchMode=yes` (launchd
+cannot type a password: the SSH key must work without a prompt), and let launchd restart
+it, in `~/Library/LaunchAgents/local.coucou-tunnel.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>Label</key><string>local.coucou-tunnel</string>
+ <key>ProgramArguments</key>
+ <array><string>/bin/sh</string><string>/Users/you/.coucou-tunnel.sh</string></array>
+ <key>RunAtLoad</key><true/>
+ <key>KeepAlive</key><true/>
+ <key>ThrottleInterval</key><integer>20</integer>
+</dict>
+</plist>
+```
+
+```sh
+launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/local.coucou-tunnel.plist
+```
+
+Check it from the Mac: the Claude Desktop pill should appear, say "hello", finish and go.
+
+```sh
+ssh myserver 'for e in UserPromptSubmit Stop; do
+ printf "{\"hook_event_name\":\"%s\",\"session_id\":\"t1\",\"prompt\":\"hello\"}" "$e" |
+ CLAUDE_CODE_ENTRYPOINT=claude-desktop ~/.coucou/nb-hook; sleep 2; done'
+```
+
+## 4. When the Mac sleeps
+
+A sleeping Mac does not close the connection, and sshd may keep it for a long time: the
+socket still accepts connections, and a permission request waits its full two minutes
+before the agent asks in its own window. Two ways around it:
+
+- **On the server, in `sshd_config`** (if you may edit it): `ClientAliveInterval 15` and
+ `ClientAliveCountMax 3`. sshd drops a silent connection after about 45 s; from then on
+ the hooks fail at once and the agent asks itself.
+- **A heartbeat**, when sshd is not yours. The tunnel's session sends a line every 10 s,
+ the server touches a file, and a wrapper (next section) skips Coucou once the file is
+ older than 30 s. On the Mac, instead of `ssh -N`:
+
+```sh
+while :; do echo; sleep 10; done | ssh -o ExitOnForwardFailure=yes -o ServerAliveInterval=15 \
+ -o ServerAliveCountMax=3 -R "$REMOTE:$LOCAL" "$SERVER" \
+ 'while read -r _; do touch ~/.coucou/alive; done; rm -f ~/.coucou/alive'
+```
+
+## 5. Which sessions show up
+
+Claude Code says where a session runs in `CLAUDE_CODE_ENTRYPOINT`, and the relay uses it:
+
+| `CLAUDE_CODE_ENTRYPOINT` | Session | In Coucou |
+|---|---|---|
+| `claude-desktop` | Code tab of the Claude app | Claude Desktop pill; approvals and questions stay in the app |
+| `claude-vscode` | VS Code's Claude Code extension | VS Code pill, with approvals and questions in the notch and on the iPhone |
+| `cli` | `claude` in a terminal over SSH | usually ignored: `TERM_PROGRAM` does not travel over SSH |
+| `sdk-ts`, `sdk-py`, … | scripts and tools that run Claude Code | ignored |
+
+Ignored sessions still open a connection for each event. To keep them, and anything else
+that runs as your user on the server, off the tunnel, and to use the heartbeat above, call
+a wrapper instead of `nb-hook` in the hook commands, `~/.coucou/hook`:
+
+```sh
+#!/bin/sh
+# nb-hook for the sessions you want, and only while the Mac answers.
+skip() { cat >/dev/null; exit 0; }
+alive="$HOME/.coucou/alive"
+[ $(( $(date +%s) - $(stat -c %Y "$alive" 2>/dev/null || echo 0) )) -le 30 ] || skip
+case " $* " in
+ *" --agent "*) ;; # Codex and other agents
+ *) case "$CLAUDE_CODE_ENTRYPOINT" in
+ claude-desktop|claude-vscode) ;;
+ *) skip ;;
+ esac ;;
+esac
+exec "$HOME/.coucou/nb-hook" "$@"
+```
+
+(Drop the `alive` line if you use `ClientAliveInterval` instead of the heartbeat. Copilot
+CLI expects an answer from its hook, so keep it out of this wrapper.)
+
+## What stays on the Mac
+
+The buttons that open a session's app, folder or terminal act on the Mac: they cannot
+reach a session on the server.