Get started

From zero to your first chat.

This guide takes you from a new phone to talking with a coding agent on your own computer. It takes about fifteen minutes. Every step says what to do, what you should see, and what to do if it goes wrong.

How the pieces fit

There is no phren server and no phren account. The app talks to two things you already own:

Your computers. The phone connects over SSH to Phren Hook, a small helper you install on each computer. Phren Hook reads your agents through Herdr, a terminal workspace manager, and passes chat, status and approvals to the phone.
Your memory. Your phren store (findings, notes, tasks) comes either from a paired computer or from a GitHub repository you own.

At home, the phone reaches your computer on your Wi-Fi. Away from home, Tailscale connects them privately. Nothing needs a public port.

What you need

An iPhone with iOS 17 or later, or an Android phone with Android 8.0 or later.
A Mac or a Linux computer where you run coding agents: Claude Code, Codex, Copilot or OpenCode.
Node.js 22.19 or newer on that computer.
Herdr on that computer, for chat, status, approvals and starting agents from the phone. tmux 3.0 or newer also works; see what works without Herdr.
Optional: a GitHub account, to sync memory when you are away from your computer.
Optional: Tailscale on the phone and the computer, to reach it away from home.

1Install the app

Do this

iPhone: phren is in testing through Apple's TestFlight and is not on the App Store yet. Install TestFlight from the App Store, then open the invite link we sent you on the phone and tap Install.
Android: phren for Android is not on Google Play yet. Ask us for a test build.

You should see

Five tabs along the bottom: Projects, Agents, Tasks, Memory and Settings. Projects opens on Connect project memory. You can leave it for now; step 5 comes back to it.

If it fails

The TestFlight link says the invite expired or the beta is full: write to us and we will send a new one.
TestFlight says the build expired: open TestFlight and install the newest build. Test builds stop working after 90 days.

2Get your computer ready

Do this

Turn on SSH. On a Mac: System Settings → General → Sharing → Remote Login. On Linux: sudo systemctl enable --now sshd (the service is called ssh on some distributions).
Check Node. Run node --version. It should print v22.19 or higher.
Install Herdr from herdr.dev and run your agents inside it. Herdr keeps each agent in a named pane that Phren Hook can find, read and type into.

You should see

ssh localhost on the computer asks for your password or logs you in. Herdr opens and shows your workspaces.

If it fails

A company-managed Mac may block Remote Login. Ask your IT team, or use a computer you control.
node is missing or old: install the current LTS release from nodejs.org or your package manager.

3Pair the phone with the computer

Do this

On the computer, as the user who runs your agents, run:
```
npx --yes @phren/cli@latest pair
```
It installs Phren Hook if it is missing and prints a QR code. The app shows the same command under Add computer, with a Copy button.
On the phone, open Agents → Add computer → Scan pairing code and point the camera at the QR code.
Can't scan? Choose Enter code and type the address and the six-character code the terminal shows.

You should see

The terminal prints Paired with your phone's name. The computer appears in the Agents tab, and after a few seconds it lists the agent sessions running in Herdr.

Behind the scenes, the phone made its own SSH key and the computer added one restricted line for it to ~/.ssh/authorized_keys. The phone also saved the computer's host key, so it will refuse to talk to anything pretending to be that computer. The pairing code never crosses the network.

If it fails

"SSH isn't answering on this computer": go back to step 2 and turn on SSH. Pairing can finish first; the phone connects once SSH is on.
"No network address found": connect the computer to Wi-Fi or Tailscale and run the command again.
The code stopped working: it lasts five minutes and closes after five wrong tries. Run the command again, or give yourself longer with npx --yes @phren/cli@latest pair --minutes 15.
The phone can't reach the computer: put both on the same Wi-Fi, or turn on Tailscale on both (step 4).
You prefer to set up SSH yourself: under Add computer choose Enter details, copy the line the app shows into ~/.ssh/authorized_keys, then confirm the fingerprint. The Phren Hook page covers this.

To check the helper at any time, run npx --yes @phren/cli@0.3.56 bridge doctor on the computer.

4Reach it away from home

Do this

Install Tailscale on the phone and on the computer and sign in to the same account. Keep it connected on both. If you pair while Tailscale is on, the QR code already carries the computer's Tailscale name, so there is nothing else to set.

You should see

Turn off Wi-Fi on the phone. The computer in the Agents tab still lists its sessions.

If it fails

The computer shows Offline: open the Tailscale app on both devices and check they are connected. A sleeping laptop can't answer; keep it awake or plugged in.
It shows Busy: the computer answers but is too loaded to list sessions right away. Its sessions still open; the details fill in when it catches up.
You paired before installing Tailscale: pair again with Tailscale on, so the phone learns the Tailscale address.

5Connect your memory

Memory is your phren store: the findings, notes and tasks your agents keep. Open the Projects tab and choose one way in.

Do this

From your computer (no GitHub): Tap Use memory from your paired computer. The phone reads and edits the store on that computer through Phren Hook. This only works while the phone can reach that computer.
Through GitHub (works anywhere): Tap Sign in with GitHub, enter the code GitHub shows, then pick the repository that holds your store (it contains a phren.root.yaml file). Prefer a token? Under Other options, choose Use a GitHub token; the Support page lists the exact permissions.
Just looking (iPhone): Tap Try the sample store for two example projects that stay on the phone.

No store yet? On your computer run npm install -g @phren/cli and then phren init. To sync through GitHub, push the store to a private repository, for example with phren store add --remote <url> or phren team init for a team store.

You should see

"Syncing your store…", then your projects with their counts. Tasks and Memory fill in too.

If it fails

Your store is not in the list: the token or sign-in can't see that repository. Give it access under Repository access on GitHub, then pull to refresh.
Everything is read-only: the token needs Contents: Read and write.

6Start your agents

Phren Hook connects to agents that are running. It adds small callbacks to your agents so they report their sessions and approval requests. An agent loads those callbacks when it starts.

Do this

Restart any agent that was already running when you installed Phren Hook. Quit it and start it again inside a Herdr pane.
In Codex, open /hooks and approve phren's new callbacks. Codex does not trust new hooks on its own.
Or start one from the phone: open a project, tap Open on a computer, pick the computer and agent, and tap Open <project> with <agent>. The app creates a Herdr workspace in that folder and starts the agent. Starting can take up to a minute.

You should see

Each agent appears in the Agents tab with its computer, project and state: working, waiting on you, or idle.

If it fails

No sessions show up: check that the agent runs inside Herdr (or tmux, on a computer without Herdr), not a plain terminal window.
OpenCode sessions don't show chat: turn on Herdr's OpenCode integration, or update the computer to phren 0.3.11 or later, whose OpenCode plugin reports the session itself. Then restart OpenCode.

7Your first chat

Do this

Tap a session in the Agents tab. Type a message and send it, or tap the microphone to dictate.

You should see

The agent's reply streams in, with each command it runs as a compact row you can expand, and the files it changed with their diffs. When the agent asks for permission, the request shows as a card with Deny and Approve.

If it fails

The chat stays on "Starting…": the agent is not reporting its session to Phren Hook. Almost always it was started before Phren Hook was installed. Restart the agent (step 6). For OpenCode, see step 6's note.
A message stays as a muted bubble: the computer did not confirm delivery. It often arrived anyway. Check the terminal before you tap Retry.
Approvals only show in the terminal: some questions have no callback yet. Open the terminal from the chat header and answer there.

What Herdr does, and what works without it

Herdr is a terminal workspace manager. It runs your agents in named workspaces, tabs and panes, and it knows which agent is in which pane. Phren Hook uses that to find each session, read its conversation and send your messages to the right place. On a computer without Herdr, Phren Hook uses tmux 3.0 or newer instead, if it is installed.

Feature	With Herdr	With tmux, no Herdr	Neither
Memory: projects, findings, notes, tasks	Yes	Yes	Yes
Agent list and status	Yes	Yes, from the agents' own reports	No
Chat with a running agent	Yes	Yes	No
Approvals from the phone	Yes	Yes	No
Start an agent from the phone	Yes, in a Herdr workspace that keeps running	Yes, in a hidden tmux server that keeps running	Only as a terminal over SSH
Terminal	The exact Herdr pane, which survives a dropped connection	The tmux server, which survives a dropped connection	A shell or an agent in a project folder, which ends when the connection drops

With tmux, start your agents inside tmux (tmux, then claude) and they show up on the phone. Agents you start from the phone run in a hidden tmux server; to see them on the computer, run tmux -L phren attach.

Without Herdr or tmux, choose Open a terminal instead when you open a project on a computer. It runs a shell, or the agent you picked, straight over SSH in that folder. It has no chat and no approvals, and it stops when you leave or the connection drops.

tmux support is new. It is tested against tmux itself with stand-in agents; tell us on Support if a harness misbehaves in tmux.

Optional extras

Talk mode reads an agent's replies aloud. It uses an ElevenLabs voice through your computer if that computer has a key (phren bridge speech-key set), and the phone's own voice otherwise. Each ElevenLabs use is billed to your ElevenLabs account.
Notifications tell you when an agent is waiting on you. Turn them on under Settings → Notifications.
More computers: repeat steps 2 and 3 on each one. The Agents tab lists them all.

Where to go next

Support and troubleshooting
Phren Hook: install, update, remove, and what it connects
Privacy policy: what stays on the phone and what leaves it
phren documentation: the CLI, memory, and the rest