03 / Session continuity
Resume the same Pi session on your phone
Start Pi at your desk, leave the host running, and reopen the same native session in Pix when you move. Same session, same context, and same workspace—without creating a separate cloud conversation.
at your deskleave desk →iPhone
Pix remote client→ returnTerminal
same workspace
What happens to your Pi session when you leave your desk?
Pi keeps running on the Mac or Linux host while Pix gives you a remote view and control surface. The host remains the place where the workspace, runtime, and session process live.
Pix resumes Pi's native session—it does not create a copy
Pi’s native JSONL session remains the durable source of truth. Pix Host connects the paired client to that host-side runtime instead of copying messages into a second hosted conversation database.
Connect an active terminal session with the Pi extension
For a Pi session that is currently open in the terminal, the Pix Pi extension, @zaincheung/pix, connects that TUI to Pix Host so the same live session can be controlled remotely. A bare Pi TUI without the bridge is not automatically adopted by Pix.
- Install the optional @zaincheung/pix extension with pi install npm:@zaincheung/pix.
- Restart Pi, or run /reload in the existing TUI, so the extension can connect to Pix Host.
Read the setup and ownership requirements in the Pi TUI bridge guide.
Desktop → iPhone → desktop
- Start a Pi session in the workspace on your Mac or Linux machine.
- For a session already open in the terminal, connect its TUI with the @zaincheung/pix extension.
- Run Pix Host and pair your iPhone with the host.
- Open the same workspace and session in Pix when you leave your desk.
- Return to the terminal later; the native Pi session and its context are still on the host.
What if your phone disconnects?
A disconnected phone changes the client’s reachability, not Pi’s local process. Once the host and phone are reachable again, Pix can reconnect to the host-side session.
For the network behavior behind reconnects, read how remote Pi access works.
Can I use the Pi TUI and Pix with the same session?
Pix coordinates host ownership so two Pi processes do not write the same session at once. The Pi TUI bridge and Pix RPC use the same session lock; release or switch ownership explicitly before another process resumes the session.
See the implementation details in the Pi TUI bridge guide.
Keep the local context
- The repository remains on the authorized host workspace.
- Pi keeps its native session history and runtime state there.
- Workspace access remains limited to roots you explicitly authorize.
- A session can be released before another Pi process resumes it.
Learn what Pix keeps on the host in the local-first security boundary.
Questions
Common questions
How does Pix resume the same Pi session?
Pix discovers native Pi sessions on the host and connects the paired client to the selected host-side runtime. Pi’s native JSONL remains the durable session source of truth.
Does Pix create a second session?
No. Pix does not move the conversation into a hosted session store; it provides a remote interface to the native Pi session on your computer.
Can I start on my computer and continue on my phone?
Yes. Keep the host running, and for a Pi session already open in the terminal install the @zaincheung/pix extension so its TUI connects to Pix Host. Then choose the same workspace and Pi session from Pix on your iPhone.
What if my phone disconnects while Pi is working?
Pi keeps running on the host. Pix can reconnect when the phone and host are reachable again, subject to the session’s current ownership state.
Can I use the Pi TUI and Pix with the same session?
Yes, with the @zaincheung/pix extension installed and one live writer at a time. Pix and the Pi TUI bridge coordinate ownership through the host session lock; a bare Pi TUI is not automatically adopted by Pix.
Does the host computer need to stay on?
Yes. The Pi runtime and native session are on the host, so the computer must be running and reachable for a remote handoff.