Set up your Mac

What you need

• A Mac with Apple silicon (M1 or later), macOS 15 Sequoia or later.
• Homebrew 6 or later. Check with brew --version.
• Tailscale on your Mac and your iPhone, signed in to the same tailnet.
• Claude Code, with claude working in Terminal.
• tmux. Homebrew installs it for you if it’s missing.
• Hoptail on your iPhone from TestFlight (link coming soon)

Install

Open Terminal and run:

brew install hoptail-app/tap/hoptail
hoptail setup

Homebrew adds the Hoptail tap and trusts this formula because you named it in full. The daemon is signed and notarized by Apple.

hoptail setup checks that tmux, Tailscale and claude are in place, then:

• creates a TLS certificate, so your iPhone talks to your Mac over an encrypted connection;
• starts the daemon in the background and at login. macOS may show “Background Items Added”, which is expected;
• adds Hoptail’s hooks to Claude Code’s settings, so the daemon knows when an agent is waiting. Your existing hooks stay, and a backup of settings.json is saved next to it.

It’s safe to run hoptail setup again at any time.

Pair your iPhone

hoptail pair

A QR code appears in Terminal. Open Hoptail on your iPhone and scan it, or scan it with the iPhone Camera. If scanning doesn’t work, tap Enter Code Manually and type the address and code shown next to the QR.

Codes last 5 minutes. If yours expires, run hoptail pair again.

Then start an agent in tmux, for example tmux new -s demo and claude, or tap New Session in the app. When the agent asks something, your iPhone will let you know.

Everyday commands

Update

brew upgrade hoptail && hoptail restart

If the app shows Update Hoptail on your Mac, run the same command. If hoptail logs says “run hoptail setup”, the hooks have changed in the new version: run hoptail setup once.

Uninstall

hoptail uninstall
brew uninstall hoptail

hoptail uninstall stops the daemon, removes it from login items and removes only Hoptail’s hooks from Claude Code’s settings. Your pairings and settings stay, in case you come back.

To remove everything, including pairings, settings and logs, use hoptail uninstall --purge instead. Then unpair in the app, or just delete the app.

If you removed Hoptail with Homebrew first

Claude Code keeps working: the leftover hook quietly does nothing. To clean up by hand:

1. Stop the daemon and remove it from login items:

   launchctl bootout gui/$(id -u)/dev.hoptail.daemon
   rm ~/Library/LaunchAgents/dev.hoptail.daemon.plist

2. Remove the hooks. Open ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json, if you set it) and, under "hooks", delete every entry whose command contains Application Support/Hoptail/hook.sh. Leave other hooks as they are. To check that nothing is left:

   grep -n "Hoptail/hook.sh" ~/.claude/settings.json

3. Remove Hoptail’s data:

   rm -rf ~/Library/Application\ Support/Hoptail
   rm -rf ~/Library/Caches/Hoptail
   rm -rf ~/Library/Logs/Hoptail

Troubleshooting

“Can’t find your Mac” or “Can’t reach your Mac”

• Make sure Tailscale is running and connected on both devices, with the same account or tailnet.
• On your Mac, tailscale ip -4 should print an address starting with 100.. hoptail status should show the same address.
• Make sure your Mac is awake. A sleeping Mac can’t answer.
• If macOS asks whether to allow incoming connections for hoptail, choose Allow. If you denied it earlier, turn it back on in System Settings → Network → Firewall → Options.

The port is busy

Hoptail uses port 7880. If another app holds it, hoptail setup picks the next free port and saves it; the QR code carries the port to your iPhone. If you change ports later, run hoptail pair again. To see what holds a port:

lsof -nP -iTCP:7880 -sTCP:LISTEN

macOS says the app can’t be opened or verified

The daemon is signed and notarized. On first launch, macOS checks it with Apple, so your Mac needs an internet connection the first time. If macOS still blocks it:

• update with brew upgrade hoptail;
• check the signature with codesign -dv "$(brew --prefix)/bin/hoptail". It should name the developer;
• send us the output of spctl -a -vv -t open --context context:primary-signature "$(brew --prefix)/bin/hoptail".

Don’t turn off Gatekeeper to make Hoptail work.

No notifications

• Check that notifications for Hoptail are on in iOS Settings, and the app isn’t set to Mute.
• In Desk mode, Hoptail first waits 20 seconds for you to answer at your Mac. Try Away.
• Make sure the agent runs in tmux, and run hoptail setup if you installed Claude Code after Hoptail.

claude not found

hoptail setup looks for claude the way your login shell finds it. Make sure claude --version works in a new Terminal window, then run hoptail setup again.

Feedback

Send feedback from TestFlight: take a screenshot in Hoptail and tap Share Beta Feedback, or email feedback@hoptail.app. If something broke, hoptail logs helps a lot. Logs can include project names and paths, so have a look before you send them.