mobile-controlled-terminal
v1.0.5
Published
Control Claude Code sessions running in iTerm on your Mac from your phone, across multiple Claude accounts
Maintainers
Readme
mobile-controlled-terminal
Control the Claude Code sessions running in iTerm on your Mac from your phone, across all your Claude accounts.
npx mobile-controlled-terminalThat one command sets everything up and prints your phone link. Step-by-step guide with every popup explained: INSTALL.md.
What you get
- One list of every session from every Claude account on the Mac, with account, folder, status (Working / Needs approval / Idle) and tokens used.
- Live chat and terminal view of any session, including sub-agents (one tab per agent) and messages that are still waiting for Claude.
- Control from the phone: send a message, interrupt (Esc), approve or reject permission prompts.
- Start a new session under any account: pick the folder, type a prompt, and it opens in a new iTerm tab on the Mac. Startup questions (trust this folder? use the browser?) can be answered from the phone too.
- Phone notifications when Claude needs approval or finishes replying: straight to the phone over Tailscale HTTPS (🔔 in the dashboard), or via the free ntfy app.
- Works from anywhere over Tailscale (Wi-Fi or mobile data), and (if you choose) with the lid closed.
What setup does
- Installs anything missing: Homebrew, Node, Claude Code, iTerm2, Tailscale.
- Opens Tailscale for you to sign in.
- Asks for your projects folder (default: your home folder). Change it later:
npx mobile-controlled-terminal folder. - Sets up keep-awake, OFF by default: asks your Mac password once to allow only
pmset disablesleep 0/1without a password, and installs SwiftBar for a ☾/☀ menu bar toggle. Turn it on when you need it: menu bar, the ☀ button on the phone, ornpx mobile-controlled-terminal awake on/off. Works with the lid closed. - Installs a background service that starts at login and restarts if it crashes.
- Prints your link and opens a QR code page.
Every step skips itself if it's already done, so it's safe to run again.
On the phone
- Install Tailscale and sign in with the same account as the Mac.
- Open the link (or scan the QR code at
http://localhost:7878/pairon the Mac). - Share → Add to Home Screen.
Multiple Claude accounts
Every ~/.claude and ~/.claude-accountN folder is picked up automatically. To add an account:
alias claude1='CLAUDE_CONFIG_DIR="$HOME/.claude-account1" claude'
claude1 # log in onceCommands
npx mobile-controlled-terminal # setup (default)
npx mobile-controlled-terminal status # check everything runs and starts after a restart
npx mobile-controlled-terminal link # print your phone link
npx mobile-controlled-terminal folder # choose the projects folder (folder picker)
npx mobile-controlled-terminal awake on # keep the Mac awake, lid closed too (awake off / awake)
npx mobile-controlled-terminal notify on # phone notifications (notify off / notify test)
npx mobile-controlled-terminal restart
npx mobile-controlled-terminal logs
npx mobile-controlled-terminal uninstallLimits
- macOS + iTerm2 only. Sessions in Terminal.app are view-only.
- The Mac has to be awake and logged in. If it's asleep, the phone shows "Your Mac isn't reachable" until it wakes.
- The link contains your access key (
~/.claude-mission-control/token). Anyone with the link who can reach your Mac over Tailscale can control your terminals, so don't share it. To reset it, delete that file and runnpx mobile-controlled-terminal restart.
