Help with the phren app

For iPhone and Android. New here? Start with Get started, which walks through setup step by step.

Check these first

Most problems come down to one of these. On the computer, run:

npx --yes @phren/cli@0.3.67 bridge doctor

It checks Phren Hook, SSH, Herdr and the phone's authorization line, and says what to fix. Then check that:

1. the computer is awake, and SSH is on (Remote Login on a Mac);
2. the phone and computer are on the same Wi-Fi, or Tailscale is connected on both;
3. your agents run inside Herdr, and were started after Phren Hook was installed.

Computers and agents

The computer shows Offline, or Phren Hook can't be reached

• Keep Tailscale connected on the phone and the computer when you are away from home. At home, check both are on the same network.
• Check SSH: on a Mac, System Settings → General → Sharing → Remote Login. On Linux, sudo systemctl enable --now sshd.
• Run bridge doctor (above). If Phren Hook is not installed or not running, install it again with npx --yes @phren/cli@0.3.67 bridge install.
• On Linux, run loginctl enable-linger $USER if Phren Hook should keep running after you log out.
• Logs: ~/.local/share/phren/bridge/service.log on a Mac, journalctl --user -u phren-hook on Linux.

Busy is different from Offline. It means the computer answered but was too loaded to list its sessions in time. Its sessions still open, and the details fill in when it catches up.

A chat stays on "Starting…"

The agent isn't reporting its session to Phren Hook. Phren Hook adds callbacks to your agents, and an agent only loads them when it starts. Quit the agent and start it again inside Herdr. In Codex, also open /hooks and approve phren's callbacks; Codex doesn't trust new hooks on its own.

If you started the agent from the phone, give it up to a minute. If it still says Starting, open the terminal from the chat header to see what the agent is doing; it may be asking a question on screen.

OpenCode sessions don't show chat

Phren Hook needs to know which OpenCode conversation each pane is showing. It learns that from Herdr's OpenCode integration, or from phren's own OpenCode plugin in phren 0.3.11 or later. Turn on Herdr's OpenCode integration, or update phren on that computer, then restart OpenCode.

No sessions show up

• Agents need to run inside Herdr. An agent in a plain terminal window is invisible to Phren Hook.
• If you use a named Herdr server, enter its name on the computer's page in the app.
• Without Herdr you still have memory and an SSH terminal: open a project on the computer and choose Open a terminal instead. That terminal ends when the connection drops. Support for tmux without Herdr is planned but does not work yet.

A permission request only shows in the terminal

Claude Code and Codex requests reach the chat through phren's callbacks. Some questions have no callback; open the terminal from the chat header and answer there. The phone holds a request for up to 55 seconds, then the agent shows it in its terminal again, where you can still answer from the phone.

A message stays as a muted bubble

The computer did not confirm delivery. It usually arrived anyway, so check the chat or the terminal before you tap Retry. Tap Dismiss if it did arrive.

Notifications arrive late, or not at all

• Check Settings → Notifications in the app, and that notifications for phren are allowed in the phone's settings.
• iPhone: without your own push key on the computer, the app checks for waiting agents during short background windows that iOS decides. Alerts are instant while the app is open.
• Android: the app checks about every 15 minutes while closed, and Android may delay that to save battery. Exempting phren from battery optimization helps.

Memory and GitHub

Connecting memory

Open Projects, or Settings → Connect memory. Choose Use memory from a paired computer (no GitHub needed), or Sign in with GitHub. To use a token instead:

1. Create a fine-grained personal access token at github.com/settings/personal-access-tokens/new.
2. Under Repository access, choose Only select repositories and pick your phren store repository.
3. Under Permissions → Repository permissions, set Contents: Read and write and Metadata: Read.
4. In the app, choose Other options → Use a GitHub token and paste it.

Your token stays on the phone and is sent only to GitHub. No store yet? On your computer, run npm install -g @phren/cli, then phren init, then push the store to a private GitHub repository.

My store isn't in the list, or only public repositories are listed

Your sign-in can't see the repository. GitHub answers "not found" rather than "forbidden" for a private repository a token can't read, so it looks like the repository doesn't exist. Add your store under Repository access on GitHub, then pull to refresh.

Everything is read-only

The token can read but not write. Set Contents: Read and write, then pull to refresh. The app checks permissions again on refresh.

Something I added hasn't reached my other computers

Changes wait on the phone and go out when the app is open and online. Open the app and give it a few seconds. Settings → Recent captures shows where each capture went and whether it synced. Anything that failed for good shows under Settings → Needs attention, where you can retry or discard it.

Installing and moving phones

TestFlight (iPhone)

• The invite expired or the beta is full: write to us for a new invite.
• The app won't open and TestFlight says the build expired: open TestFlight and install the newest build. Test builds stop working after 90 days.
• No update showing: open TestFlight and pull to refresh. Automatic updates can be turned on on the app's TestFlight page.

Android test builds

phren for Android is not on Google Play yet. Ask us for a test build. Android may ask you to allow installs from the app you download it with.

New phone, reinstalled app, or keys lost

The phone's SSH keys never leave it and are not in backups. A new phone, a restored backup, a reinstall, or clearing the app's data on Android all leave the app without its keys, and computers stop answering it. To fix it:

1. In the app, open the computer and choose Forget computer, if it is still listed.
2. On the computer, run npx --yes @phren/cli@latest pair and scan the new code.
3. On the computer, remove the old phone's phren-iphone or phren-android line from ~/.ssh/authorized_keys.

Your GitHub sign-in also stays on the old phone; sign in again on the new one.

The phone can't connect while locked (iPhone): its SSH keys can only be read while the phone is unlocked. Unlock it and the connection resumes.

Other questions

A web preview has no styles or scripts (iPhone)

Check that the development server serves its CSS and JavaScript without errors. Relative assets and WebSockets work over phren's SSH preview; an app that hard-codes another address may need its public or base URL set.

The input token count is much bigger than my message

Each response counts the whole conversation, instructions and tools, not only your latest message. The usage details separate cached input from new input. They describe the latest response, not your account's limit.

Talk mode uses the phone's voice, not ElevenLabs

The computer the chat is on needs an ElevenLabs key. Run phren bridge speech-key set there and paste it. Without a key, or when the computer can't be reached, the phone reads replies itself.

Siri opens the wrong app when I say "phren" (iPhone)

Say "Add a phren task" rather than "add a task to phren", which Reminders also claims. Running the shortcut once by hand from the Shortcuts app helps Siri recognize it. You can also put phren: Add Task on the Action Button. To choose where Siri's captures go, set a default under Settings → Quick capture.

Contact

Email alaarab@gmail.com. Bug reports and feature requests are welcome as GitHub issues. Please don't paste tokens, keys or private code into an issue.