Remote Claude Code sessions: no way to open plan review UI without a local browser

[GunitBindal]

Problem

When using Plannotator via a remote Claude Code instance (SSH, cloud VM, headless server), the hook starts a local server and either:

• Tries to open a browser that doesn't exist, or
• Correctly detects the remote session (SSH_TTY/SSH_CONNECTION/PLANNOTATOR_REMOTE=1) and skips the browser — but then there's no way to actually view the plan review UI from your local machine.

The server binds to localhost:<port> on the remote host, which isn't accessible from the user's local browser. The user is stuck — they can see the URL printed in the terminal, but can't open it.

This is a real blocker for anyone using Claude Code over SSH (which is a very common setup — remote dev servers, cloud instances, codespaces, etc.).

Expected Behavior

When running on a remote instance, Plannotator should give the user a shareable URL they can open in their local browser — no tunneling, no port forwarding required.

Suggested Solutions

Option A: Auto-generate share URL in remote mode (Recommended)

When a remote session is detected, automatically generate the compressed share URL (or short paste URL from #188) and print it to the terminal. The user copies the link, opens it on their local machine via share.plannotator.ai, done.

🔗 Remote session detected — open this link on your local machine:
   https://share.plannotator.ai/p/aBcDeFgH

   (or full URL: https://share.plannotator.ai/#eJy0Vk1v4z...)

   Waiting for your decision...

This is the cleanest UX — zero setup, works everywhere. The share portal is already a static SPA that works independently of the server.

Option B: --url-only / --no-open CLI flag

Add a flag that skips the browser open and just prints the share URL:

# In .claude/hooks/ExitPlanMode.sh
plannotator --url-only

This gives users explicit control regardless of remote detection.

Option C: Clipboard-friendly output

When remote, copy the share URL to the remote clipboard (if available via xclip/xsel/OSC 52 terminal escape) and print it. Many modern terminals (iTerm2, WezTerm, kitty) support OSC 52 for remote-to-local clipboard sync.

Option D: QR code in terminal

Print a QR code in the terminal that the user can scan with their phone to open the review. Libraries like qrcode-terminal make this trivial. Great for quick mobile review.

Implementation Notes

• Remote detection already works well in packages/server/remote.ts (PLANNOTATOR_REMOTE, SSH_TTY, SSH_CONNECTION)
• The onReady callback in all three modes (plan/review/annotate) already receives isRemote — just needs to generate and print a share URL when isRemote === true
• With PR Add short URL sharing via paste service to fix URL truncation #188 (short URLs), this becomes even better — a 50-char URL instead of a 40KB hash URL
• The handleServerReady/handleReviewServerReady/handleAnnotateServerReady functions are the exact place to add this logic
• Should work for all three modes: plan review, code review (plannotator review), and annotate (plannotator annotate)

Workaround (current)

Users can manually set up SSH port forwarding:

ssh -L 19432:localhost:19432 remote-host

But this is fragile (port changes), requires planning ahead, and is a terrible UX.

---

I use Claude Code on remote instances daily and this is the #1 thing preventing me from using Plannotator in that workflow. Happy to create a PR implementing any of these approaches — Option A seems like the best default behavior.

[GunitBindal]

Implemented this in PR #188 (commit e917a84) — since @backnotprop is already reviewing that PR, I bundled it there instead of a separate PR.

What's implemented

When a remote session is detected (SSH_TTY, SSH_CONNECTION, or PLANNOTATOR_REMOTE=1), the hook now:

1. Generates a share.plannotator.ai hash URL server-side using the same deflate-raw + base64url compression as the client
2. Prints it to stderr (stdout is reserved for hook JSON output)
3. Works for all three modes: plan review, code review, and annotate

Example output in remote terminal:

  Open this link on your local machine to review the plan:
  https://share.plannotator.ai/#eJy0Vk1v4z...

  (12.3 KB — plan only, annotations added in browser)

The user copies this link, opens it on their local browser, and gets the full plan review UI via the existing share portal. Annotations are added in-browser and can be shared back via the normal sharing flow.

Limitations

• The server-generated URL contains the plan only (no annotations) since annotations don't exist yet at server startup. Once the user opens the share portal, they can annotate and generate a new share URL with annotations included.
• For very large plans, the hash URL will still be long. If/when the paste service lands (also in PR Add short URL sharing via paste service to fix URL truncation #188), the remote mode could generate short URLs instead — that's a one-line change.

Files changed

• packages/server/share-url.ts (new) — server-side share URL generator
• packages/server/package.json — export the new module
• apps/hook/server/index.ts — all three modes updated to print share URL when remote

Happy to split this into its own PR if you'd prefer to review it separately from the short URL feature.

[tfriedel]

Disclaimer: This comment was written by Claude (Opus 4.6) on behalf of @tfriedel based on hands-on testing.

---

Tested this on a remote SSH session (tmux inside SSH, with PLANNOTATOR_REMOTE=1, SSH_TTY, and SSH_CONNECTION all set). A few findings:

1. v0.11.0 release binary is missing the plan-mode share link

The compiled binary from the v0.11.0 release only has the writeRemoteShareLink call for review and annotate modes — the main plan review mode (ExitPlanMode hook) is missing it. Verified by comparing strings output:

• Release binary: 3 matches (function definition + review + annotate calls)
• Locally compiled binary from main: 4 matches (includes the plan review call)

The code on main is correct (apps/hook/server/index.ts:199), but the release was cut from a commit that didn't include it yet. A new release will fix this.

2. Claude Code doesn't surface hook stderr to the user

This is the bigger issue. After fixing the binary, writeRemoteShareLink does write the share URL to stderr — confirmed by capturing it:

  Open this link on your local machine to review the plan:
  https://share.plannotator.ai/#q1YqULJSUlYISS0u...

  (88 B — plan only, annotations added in browser)

However, Claude Code connects hook stderr to a socket (verified via /proc/<pid>/fd/2 -> socket:[...]), not the terminal. The output is captured but never displayed to the user. The user sees Claude Code's built-in plan mode UI with no indication that plannotator is running or that a share URL exists.

Meanwhile, the plannotator server does start correctly on port 19432, saves the plan to ~/.plannotator/history/, and waits for a decision — it's just invisible.

What needs to change

The stderr approach won't work for Claude Code hooks. The share URL needs to be surfaced through a different channel.

[tfriedel]

Took a stab at this in #286 — it works for my setup but relies on external dependencies (Tailscale, tmux, ntfy), so it's more of a proof-of-concept than a general solution.

What the PR does

• Auto-detects Tailscale hostname so the server URL is directly reachable from a local browser without port forwarding
• tmux display-popup to surface the URL — this bypasses Claude Code's stdio capture since it's a tmux-layer overlay on top of the TUI
• ntfy push notification with a clickable link (reuses existing CLAUDE_HOOKS_NTFY_URL config)
• Random ports instead of fixed 19432, so parallel Claude sessions work
• 0.0.0.0 binding when a non-localhost hostname is detected

The root problem remains

As noted in the earlier comment, Claude Code captures hook stderr to a socket — there's no built-in way for a hook to surface a message to the user during execution. All the workarounds are external channels (Tailscale, tmux, ntfy), which most users won't have.

What would actually fix this for everyone

1. Claude Code feature: A way for hooks to surface messages/progress to the user's terminal. Even just printing stderr would solve it.
2. Session router on a fixed port: One long-lived server that multiplexes sessions on subpaths (/session/<id>). Users forward one port, all sessions work. More complex but zero external dependencies.
3. VS Code Remote: Already auto-forwards ports. If the URL gets surfaced somehow, VS Code Remote users are covered today.

Would be curious if others have ideas for approaches that work without Tailscale/tmux/ntfy.