Phone companion

The phone companion preview is a browser app for agents running on your computer. It shows their conversations and requests, and starts new conversations in the projects the phone can work in. The agent keeps running on the computer.

App: Settings → Remote access → Connect a phone
CLI: hansard remote host link

For read-only archive browsing, use the Hosted viewer. For pairing two computers, see Remote access.

Connect with Tailscale

The computer needs Hansard, signed-in agent CLIs, and a working Tailscale connection. Keep it awake and connected to the network. A tailnet is the private network your Tailscale devices share.

Hansard walks through these steps and draws what the phone and Tailscale’s admin console show: select Guided setup beside Connect a phone, or open guided setup’s Remote access guide and choose A phone.

Install Tailscale on the phone.
Sign the phone in to the same tailnet as the computer.
If MagicDNS is off, enable it on the Tailscale admin console’s DNS page.
Under HTTPS Certificates, select Enable HTTPS for the tailnet.
On the computer, open Settings → Remote access → Connect a phone.
Select Prepare phone access.

Hansard turns on remote access and checks Tailscale. If HTTPS is already ready, continue at This phone can work in below.
If a setup command appears, select Copy command.
Run the copied command in Terminal on the computer.

The command starts with tailscale serve --bg --https=443 and points to Hansard’s local gateway. Use the port shown in the command.
Select Check connection.
Under This phone can work in, choose one:
- All projects on this computer
- Projects in a portfolio
- Only shared projects, then check the projects under Projects this phone can access
Select Create connection link.
Scan the QR code with the phone’s camera.
On the phone, enter Name for this phone.
Select Connect.
Add the page to the home screen with the browser’s Add to Home Screen or Install app action.

Tailscale Serve publishes the gateway only to devices on your tailnet, not to the public internet. Tailscale access rules still apply. Hansard generates the QR code locally.

These are the same choices as Can work in under Allowed devices, where you can change them after the phone connects. The phone does not need a new link. Projects in lists your portfolios. Only shared projects appears after you share a project with Share a project.

The choice limits which conversations the phone sees and where new work starts. It does not restrict an agent’s file access. The agent keeps its permissions on the computer.

Claude Code approvals on your phone stays off until you turn it on in Settings → Remote access, after pairing a phone. When enabled, supported terminal approvals wait up to 15 seconds for the phone, then use the terminal prompt if no decision arrives.

See Tailscale’s HTTPS setup for the admin console steps. HTTPS certificates publish the computer’s Tailscale DNS name in a public certificate log.

Connect without Tailscale

Install Hansard and sign in to the agent CLIs on the host computer. Keep the computer awake and connected to the network. This path uses a tunwg relay that you or your administrator has already configured. Hansard does not provide a public relay.

On the host computer:

Initialize the host:

hansard remote host init --label "My computer"

hansard remote host project example --cwd /path/to/project --label "Example project"

Configure the relay, replacing the example hostname with your relay’s hostname:
Terminal window
```
hansard remote host relay --api relay.example.com
```
If the relay requires a credential, add --auth-file <private-file>.
Turn on access:
Terminal window
```
hansard remote host access on
```
Check that the gateway has a working HTTPS address:
Terminal window
```
hansard remote host access status
```
Create a link for the registered project:
Terminal window
```
hansard remote host link --projects example
```
Use a comma-separated list to include more registered projects. Replace --projects example with --all for every project folder on the computer, or with --portfolio <id> for one portfolio’s projects.

The command returns a url. The same ten-minute limit and one-use rule apply to this link. Keep the whole link private.

On the phone:

Open the returned link in your browser.
Enter Name for this phone.
Select Connect.
Add the page to the home screen with the browser’s Add to Home Screen or Install app action.

See the remote host reference for relay requirements and CLI options.

Use the phone app

The phone app is for the agents running on your computer.

Tab	What you can do
Agents	See which agents are running and which need you. Select an agent to read its conversation and current state.
Inbox	Review approvals and questions that the host can answer from the phone.
Search	Find a message in any conversation the phone can open, or switch to Titles to match titles and projects. Select a match to open its conversation at that message.
Devices	Review the connected computer and what the phone can work in, set reminders, or sign out.

Select New conversation (the plus at the top of a tab) to choose a Project, Agent, and Model, enter a task, and select Start conversation.

Pull down at the top of Agents or Inbox to refresh them.

Use Load earlier messages to read older conversation text. Jump to latest returns to new output after you scroll away. Send a message from the conversation when its composer is available.

Open Agent actions for Pause, Revive, Stop, Continue on phone, and Conversation details. The host determines which controls work for that agent. An unavailable control explains why. Pausing an eligible idle terminal saves its conversation and closes that terminal run. Continuing an existing Hansard run takes control without restarting it.

Approvals and questions appear only when the host supplies those controls. An agent visible in Agents may still need you at its original terminal.

Add the app to your home screen

Use your browser’s Add to Home Screen or Install app action. The app loads conversations from the computer when connected. It does not store conversation history for offline reading.

Waiting reminders works while the app is open, where the browser supports system notifications. Background push notifications are not connected.

Native iOS source preview

The source checkout includes a SwiftUI app in mobile/ios/. It displays this same phone page with native QR pairing, a paired Mac list, Keychain credentials, and a link share sheet. It can schedule local reminders while the app is active. It does not receive new events while suspended.

The native app has simulator testing only. Signing and physical-device acceptance remain unfinished. There is no signed app, TestFlight download, or native Android app to download.

Open mobile/ios/README.md in the source checkout for Xcode, iPhone signing, and TestFlight steps. The phone still needs the separate Tailscale app for a Tailscale gateway.

Disconnect or revoke access

Select Devices → Sign out this phone to sign out. Accepted work keeps running on the computer.

On the host, remove the phone under Settings → Remote access → Allowed devices to revoke its access. Turning off Allow access from other devices disconnects devices and leaves accepted work running. Stop an agent separately when you want its work to end.

Troubleshooting

Tailscale setup messages

Hansard checks the HTTPS configuration before offering a connection link. It leaves existing Tailscale Serve and Funnel configurations unchanged.

Message	Meaning and action
Turn off Funnel for this HTTPS name before using private phone access.	Funnel makes this HTTPS name public. Turn off Funnel for this name before retrying phone setup.
A foreground Tailscale Serve command uses HTTPS. Finish it before configuring phone access.	A running terminal command occupies HTTPS port 443. Finish that command in its terminal before retrying phone setup.
Tailscale Serve already uses HTTPS for another service. Its configuration has not changed.	Port 443 has another service, extra routes, or a destination that differs from Hansard’s gateway. Move that configuration away from port 443 before retrying phone setup.
Connect this computer to Tailscale to use phone access.	Hansard cannot find a connected Tailscale device with a usable HTTPS name. Connect the computer to Tailscale.
This computer’s Tailscale name changed. Set up phone access again.	The current name differs from the saved HTTPS address. Repeat Connect with Tailscale to create a link for the new name.
Tailscale Serve status is unavailable. Check the Tailscale installation.	Hansard cannot read the Serve configuration. Check that Tailscale is installed and running on the computer.

If Run the setup command on this computer to enable Tailscale HTTPS. appears, complete the Copy command, Terminal, and Check connection steps above.

Connection and agent access

A link expired or was already used. Create a new link on the host.

The computer is offline. Check its power and network connection. For Tailscale, check that both devices are connected to the same tailnet. For a relay, check the relay connection. Reconnect before sending more work.

An action has no confirmed result. Select Check action before sending another request. The app checks whether the host accepted the first action.

A project is missing. On the computer, change the phone’s Can work in under Settings → Remote access → Allowed devices. The phone cannot widen its own access.