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.