LOSTTY(1)Lostty ManualLOSTTY(1)
Getting started
Install Lostty on your Mac, put the app on your iPhone, and pair them. It takes four steps.
Requirements
- A Mac on macOS 14 or later.
- An iPhone on iOS 17 or later.
- Tailscale on both.
On your Mac
1. Install Lostty
Download Lostty.dmg, open it, drag Lostty to Applications, and open it from there.
On your iPhone
2. Install the app
Lostty for iPhone is coming soon on TestFlight. Once it's out, install TestFlight from the App Store, open the Lostty link on your phone and tap Install.
noteUntil then, developers can install it from source with Xcode. See Build from source.
Pair them
3. Install Tailscale on both
Install Tailscale on the Mac and the iPhone, and sign in to both with the same account.
why tailscale?Your phone talks to your Mac directly, over SSH, inside your own private Tailscale network. There's no Lostty server in the middle. There isn't one. And the phone's SSH key never leaves the phone.
4. Pair
On the Mac, open Lostty → Phone Access… and fix any row without a ✓. Each row says what to click. Then click Pair a Phone…, and on the iPhone open Lostty, tap Pair with Mac and scan the code. Click Allow on the Mac.
If you'd rather set up the Mac by hand, the steps Phone Access automates are in Manual Mac setup.
Updating
Lostty checks for updates once a day and asks before installing one. TestFlight keeps the iPhone app up to date.
That's it
Go take a walk. Your phone reaches the Mac while it's awake and Lostty is open. To keep it reachable with the lid closed, see Phone Access.
Phone Access
Open your Mac's Lostty sessions from your iPhone, anywhere, over your own Tailscale. Nothing goes through a Lostty server; there isn't one.
Set up once
- Install Tailscale on your Mac and your iPhone, and sign in to both with the same account.
- On the Mac, open Lostty → Phone Access…. Fix any row that isn't ✓:
- tmux:
brew install tmux.
- Remote Login and Password logins off: one admin password prompt turns on Remote Login and allows only key logins.
- Terminal definition: click Install.
- Folder access (optional): click Grant Now and allow Desktop, Documents and Downloads, so commands from your phone never wait on a macOS prompt.
- Click Pair a Phone…. On the iPhone, open Lostty, tap Pair with Mac, and scan the code. Click Allow on the Mac.
Stay Awake
Your phone can reach the Mac only while the Mac is awake and Lostty is open. To keep it awake with the lid closed, install the Stay-awake permission in Phone Access, then choose Stay Awake for Phone from Lostty's menu bar icon.
While it's on, Low Power Mode is on whenever the lid is closed, and it turns itself off at your battery floor (15% by default) or if the Mac gets too hot.
Using it
- A Claude Code session shows its task, with Waiting when it's waiting for you or Working while it works. Waiting sessions come first.
- Other sessions show their project. A session in
.claude/worktrees/<name> shows as <repo>/<name>.
- Swipe left on a row → Rename to name a session. It's the same name as Rename Tab… on the Mac.
Lost phone
Open Lostty → Phone Access on the Mac and click Remove next to it. If you can't get to Lostty, delete the line ending in lostty-phone:<id> from ~/.ssh/authorized_keys.
Troubleshooting
- "Couldn't find your Mac nearby" while pairing
- Keep the code open on the Mac, keep the phone close, and allow Local Network access for Lostty on both.
- "Can't reach your Mac"
- Check Tailscale is on on both, signed into the same account, and the Mac is awake.
- "This Mac's identity changed"
- If you reinstalled macOS, pair again. Otherwise don't connect; something else is answering at that address.
- The Mac never sleeps
- After a force-quit while Stay Awake was on: open Lostty once (it puts things back), or run
sudo pmset -a disablesleep 0.
Skins
Lostty gives every pane a background color and texture based on the project it is in.
cd into a project and the pane re-skins; leave and it reverts.- Split panes are skinned independently.
- Git repos you have not configured get a stable automatic skin.
- Override any pane from the Skins icon in the sidebar or the
skins command.
Presets
Twelve built-in skins restyle your background, text color, texture, 16-color ANSI palette, cursor and selection. Each has a rarity label and an accent color.
| Skin | Rarity | Look |
|---|
neon-arcade | legendary | Bright magenta and cyan on a dark purple. |
sunset-drive | epic | Warm orange and pink on a dark plum with scanlines. |
mint-protocol | rare | Neon green and yellow on a dark teal. |
deep-dive | rare | Bright cyan and purple on a dark blue. |
lava-rush | epic | Warm orange and yellow on a dark brown with diagonal texture. |
bubble-pop | common | Hot pink and yellow on a purple with sparkle texture. |
thunderhead | epic (Zeus) | Thunder gold on storm navy with lightning. |
undertow | rare (Poseidon) | Sea-foam on abyssal teal with tide lines. |
bloodrite | heroic (Ares) | Battle red on dried blood with blade marks. |
heartsease | common (Aphrodite) | Rose pink on dusk rose with petals. |
silverbow | legendary (Artemis) | Hunter green on night forest with a starfield. |
stormsurge | duo (Zeus & Poseidon) | Gold lightning over teal swells. |
Commands
sh
skins # interactive picker
skins set neon-arcade
skins color '#3a0f14'
skins texture grid
skins opacity 0.5
skins list # name, background, texture, rarity
skins current
skins reset
Overrides last until reset or until the pane closes. zsh and bash get the skins function from Lostty's shell integration; other shells can run lostty +skins.
Configure
Copy docs/skins/skins.example.toml to ~/.config/lostty/skins/skins.toml. A [[match]] entry maps a folder to a skin. Errors never break the terminal: the last good config stays active and the Skins icon in the sidebar shows a yellow dot.
Claude trace
While Claude Code is working in a pane, a light ray races around that pane's edge. The moment Claude finishes, the ray disappears. Each preset has its own trace; panes without a skin get a pink-and-cyan beam.
Manual Mac setup
These are the steps Phone Access automates, for setting up by hand.
noteMost people should use Lostty → Phone Access instead. See Phone Access.
Steps
- tmux:
brew install tmux.
- Remote Login: System Settings → General → Sharing → Remote Login on, "Allow access for" → only your user.
- Keys only: create
/etc/ssh/sshd_config.d/000-lostty.conf containing:
sshd_config
PasswordAuthentication no
KbdInteractiveAuthentication no
ssh -o PreferredAuthentications=password localhost; it must refuse.
- The phone's key: in the phone app, Settings → Show This Phone's Key → share it to the Mac, and append it to
~/.ssh/authorized_keys as restrict,pty <key> lostty-phone:<any-id>. Then chmod 600 ~/.ssh/authorized_keys.
- Terminal definition, so tmux draws Lostty's terminal correctly:
sh
mkdir -p ~/.terminfo/78 ~/.terminfo/67
cp /Applications/Lostty.app/Contents/Resources/terminfo/78/xterm-ghostty ~/.terminfo/78/
cp /Applications/Lostty.app/Contents/Resources/terminfo/67/ghostty ~/.terminfo/67/
- Tailscale on the Mac and the iPhone, signed in to the same tailnet, starting at login, with two-factor on the account. In the phone app use the Mac's Tailscale name (
your-mac.tailXXXX.ts.net) or 100.x address.
- Awake in a bag (optional):
sudo pmset -a disablesleep 1, and sudo pmset -a disablesleep 0 to undo. Set the Mac's Wi-Fi to join the iPhone's hotspot automatically. Expect heat under heavy builds and battery drain.
Build from source
For developers: build the Mac app yourself and install the iPhone app over the cable, before it's on TestFlight or to run your own changes.
# the short version
git clone https://github.com/Lawliang/lostty.git && cd lostty
macos/setup.sh # build and install the Mac app
macos/install-phone.sh # install the iPhone app over the cable
Requirements
- A Mac on macOS 15 or later, with Xcode 26 and Homebrew.
- An iPhone on iOS 17 or later, with its cable.
- A free Apple Account, to sign the iPhone app.
The Mac app
Get Xcode 26 from the App Store and open it once. Then, in Terminal:
sh
git clone https://github.com/Lawliang/lostty.git
cd lostty
macos/setup.sh
It installs what the build needs (it may ask for your password), then builds Lostty, puts it in /Applications and opens it. The first build takes a while.
The iPhone app
Add your Apple Account to Xcode: Settings → Accounts, click +, and sign in. Plug your iPhone into the Mac, unlock it, and tap Trust. Then, in the lostty folder:
sh
macos/install-phone.sh
The first time, the phone may ask you to:
- turn on Settings → Privacy & Security → Developer Mode (the phone restarts);
- trust your Apple Account in Settings → General → VPN & Device Management.
Then run the command again.
noteWith a free Apple Account, the app stops opening after 7 days. Run the command again to renew it. A paid developer account makes it last a year.
Then pair them as in Getting Started.
Updating
sh
git pull
macos/install.sh
Then choose Restart to Update in Lostty's menu bar.
warningDon't Quit Lostty to update: quitting ends every terminal session.
Contributing
Bug reports, ideas and changes are all welcome.
Report a bug
Open an issue at github.com/Lawliang/lostty/issues. Say what you did, what you expected and what happened, plus your macOS version (and iOS version for the phone app). If a bug also happens in plain Ghostty (rendering, fonts, escape sequences, input), it belongs upstream at ghostty-org/ghostty.
Send a change
- Fork the repo and make a branch.
- Keep the change focused: one fix or feature per pull request.
- Run the tests that cover what you touched.
- Open a pull request saying what changed and why. Screenshots help for UI.
Prerequisites
- macOS with Xcode 26, plus the Metal Toolchain:
xcodebuild -downloadComponent MetalToolchain
- Zig 0.15.2 and Nushell:
brew install zig@0.15 nushell
- tmux, for the phone features:
brew install tmux
Build
sh
zig build -Demit-macos-app=false # the engine, whenever code outside macos/ changes
macos/build.nu # Debug build of the Mac app
macos/install.sh # release copy into /Applications
Test
| What | Command |
|---|
| Zig (engine and CLI) | zig build test -Dtest-filter=<name> |
| Mac app | macos/build.nu --action test |
| One Mac test suite | macos/skins-test.sh <SuiteName> |
| Phone's shared package | cd macos/LosttyRemote && swift test |
- Zig:
zig fmt .
- Swift:
swiftlint lint --strict --fix
- Everything else:
prettier -w .