Help

Get started

What you need

An iPhone with Tavi. Tavi is in beta on TestFlight; ask for an invite.
A Mac or a Linux computer with Node.js 20 or later. node --version tells you which one you have.
Optionally, herdr, for agent cards and starting agents from your phone. Without it, Tavi is a plain remote terminal. The setup below offers to install it.

Set up your computer

Open a terminal on the computer and run:
npx tavi-host connect
It shows a short checklist of what the computer already has and what it will set up: Tavi running in the background, a tavi command, herdr for the agent cards, and, when Claude Code is on the computer, its hooks, so your phone knows when Claude asks something, finishes or gets stuck. It asks once, sets it up, connects the computer to Tavi's relay and shows a QR code.
In Tavi on your phone, tap Scan pairing code and scan it.
Check that the fingerprint your phone shows matches the one in the terminal, then confirm.

A code pairs one phone, for five minutes, and disappears from the screen once it's used. No camera? npx tavi-host connect --text also prints the code as text you can type into the app. Run from something that isn't a terminal, such as an agent or a script, connect opens the code in your browser instead, and --yes answers yes to everything.

Another computer

Run the same command on the other computer, a Linux box or a second Mac, and scan its code too. Tavi keeps every computer you connect on its home screen, each with its connection health, and anything waiting on any of them sits on top. Tavi Pro adds more computers.

Look around first

Not ready to connect a computer? On Tavi's first screen, tap Look around first to explore an offline sample.

Updates

Tavi keeps itself up to date. Once a day the background host checks npm for a newer version, installs it beside the current one and restarts; if the new version fails to start, it goes back to the previous one by itself. The Claude Code hooks come up to date with it. There is nothing to run again; tavi update checks right away.

Commands

From any terminal on the computer:

tavi doctor: Shows every check without changing anything, including which of Tavi's Claude Code hooks are installed.
tavi update: Checks for a newer version now.
tavi devices: Lists the paired phones.
tavi devices revoke <id>: Cuts one phone off. --all cuts every phone off.
tavi identity: Shows this computer's key and id.
tavi identity reset: Replaces this computer's key and host token, and revokes every phone, so each pairs again.
tavi install-claude-hooks: Adds the Claude Code hooks on their own, for any that tavi doctor names as missing or out of date.
tavi uninstall: Removes Tavi from the computer entirely.

connect puts the tavi command on your PATH. If it had to use ~/.local/bin and that folder isn't on your PATH, the checklist shows the one line to add. npx tavi-host <command> works too.

Troubleshooting

Start with `tavi doctor`

It checks everything and changes nothing: Node, the tavi command, the computer's key, the port your phone connects to on your network, the relay, the fast path and the Claude Code hooks. A check that fails says what to do. The host also writes a log to ~/.tavi/host.log.

Tavi can't reach your computer

Is the computer awake? Your agents run on the computer, so a computer that is asleep or has its lid closed can't answer. Tavi shows it as asleep or offline and keeps trying.
Is the host running? Run tavi doctor on the computer.
Is the computer online? Away from its network, your phone reaches the computer through Tavi's relay, so the computer needs an internet connection. If connect says the computer could not reach Tavi's relay, check its connection and run npx tavi-host connect again. If it says the relay turned the computer away, tavi doctor says why and what to do.

`connect` says Tavi hasn't let this computer in yet

During the beta, new computers are let in by hand. connect prints the computer's id: send it to support@tavihost.com, and once it's let in, run npx tavi-host connect again.

Node.js

Tavi needs Node.js 20 or later. The background service starts the Node that installed it. If that one goes away, it starts nvm's default instead when nvm installed it, and otherwise the one Homebrew or the system has. ~/.tavi/host.log and tavi doctor say which Node it chose and why. With no Node at all, it says so once, and starts by itself within five minutes of you installing one.

Linux

On Linux the host runs as a systemd user service, ~/.config/systemd/user/tavi-host.service, so it needs no root and runs as you. To see how it's doing:

systemctl --user status tavi-host

To keep the host running after you log out and across reboots, connect turns on lingering for your user. Some distributions allow that only to an administrator; if the host stops when you log out, run:

sudo loginctl enable-linger $USER

No compiler is needed on Linux x64 or arm64. If the terminal module ever fails to load, tavi doctor says exactly what to do.

No agent cards, or you can't start an agent from your phone

Those come from herdr, which is optional. Run npx tavi-host connect again: when herdr is missing or stopped, it offers to install it or start it. tavi doctor shows whether herdr is running.

An agent you started elsewhere doesn't show up

Tavi attaches to anything running in herdr and can start any command-line agent herdr knows. It can't take over a process you started in a normal terminal window or in a vendor's desktop app. Start the agent from Tavi or in herdr, or resume its session there with the tool's own resume command.

Your phone doesn't know when Claude Code needs you

tavi doctor shows which of Tavi's Claude Code hooks are installed, and tavi install-claude-hooks adds any that are missing or out of date.

Pair a phone again

If a phone lost its pairing, or you reset the computer's identity, run npx tavi-host connect on the computer and scan the new code.

Unpair a phone

On the computer, tavi devices lists the paired phones. tavi devices revoke <id> cuts one off without touching the others, and tavi devices revoke --all cuts every one off. The relay stops admitting a phone you unpair.

On the phone, Forget on this iPhone removes the computer from that phone only. The computer still lists the phone until you revoke it there.

Lost a phone, or think the computer's keys leaked? Run tavi identity reset. It replaces the computer's key and its host token and revokes every phone; pair the phones you keep again with npx tavi-host connect.

Uninstall

tavi uninstall removes Tavi from the computer entirely: the background host, the paired phones, its Claude Code hooks, and its keys and pairings in ~/.tavi. herdr and Node stay. To remove the app, delete Tavi from your iPhone as you would any app.

Questions

Is Tavi an AI agent?

No. Tavi doesn't run or replace any agent. Your agents run on your computer as they do now, and Tavi gives you a terminal and a phone-first way to launch, watch, type into and answer them.

Which agents work with Tavi?

Anything that runs in a terminal: Claude Code, Codex, other command-line agents, test runners and plain shells. With herdr you also get agent cards and can start agents from your phone. When Claude Code is on the computer, its hooks tell your phone when Claude asks something, finishes or gets stuck.

Can Tavi see my code?

No. Your code, files, prompts, the agents' replies and what your terminals show stay between your phone and your computer, encrypted end to end. How it works.

Do I need an account?

No. There's no sign-in and no email. You connect a computer by scanning a code in its terminal.

Does it work away from home, on mobile data?

Yes. On the same network your phone goes straight to your computer. Anywhere else it goes through Tavi's relay on Cloudflare, with no VPN and no port forwarding, still encrypted to your computer's own key.

Can I use Tavi without the relay?

Yes. You can turn the relay off on your computer, and then your phone reaches it only on the same network.

Does my computer have to stay on?

Yes, while you want to reach it. Your agents run on the computer, so it needs to be awake and online. When it sleeps, Tavi shows it as asleep and keeps trying.

Which computers can run the host?

macOS and Linux, with Node.js 20 or later.

Is there an iPad or Android app?

Not yet. Tavi is for iPhone today.

What does Tavi Pro add?

Tavi Pro is an in-app subscription through Apple. It adds more computers, the fast path, previews of a dev server on your computer, and merging from your phone. You manage or cancel it in your iPhone's Settings, under your Apple Account's subscriptions.

Is the host open source?

Yes. The host, tavi-host on npm, is open source under the Apache License 2.0. It runs with shell access on your computer, so anyone can read what it does.

Contact

Write to support@tavihost.com. It helps to say what you did, what you expected and what happened, your iPhone and iOS version, the computer's system, and what tavi doctor shows.

Never send a pairing code, a host token or anything from ~/.tavi. They are keys to your shell, and we will never ask for them.

Found a security problem? See reporting a vulnerability.