# How to Resume Sessions from Pi in jcode: Complete Technical Guide

> Learn to resume Raspberry Pi sessions in jcode. Launch a persistent server, get the session ID, and connect from your Pi to restore the interactive state. A complete technical guide.

- Repository: [Jeremy Huang/jcode](https://github.com/1jehuang/jcode)
- Tags: how-to-guide
- Published: 2026-04-30

---

**To resume a session from a Raspberry Pi in jcode, launch a persistent server with `--persist`, note the session ID, then execute `jcode --connect ws://<SERVER_IP>:7777 --resume <id>` on the Pi to restore the full interactive state.**

The `1jehuang/jcode` repository provides a persistent session architecture that allows you to disconnect from an interactive coding session and resume it later from any device, including a Raspberry Pi. This workflow relies on a client-server model where the server maintains session state on disk, enabling seamless handoff between machines without losing history or context.

## Start a Persistent jcode Server

Before you can resume a session from your Pi, you must run jcode in **server mode** on a machine that will remain online. This server acts as the stateful hub for all sessions.

Use the following command to start the server:

```bash
jcode --listen ws://0.0.0.0:7777 \
      --session-dir /home/pi/.jcode/sessions \
      --persist

```

The flags work as follows:

- `--listen` – Opens the WebSocket endpoint that clients use to connect.
- `--session-dir` – Specifies the directory where session state JSON files are persisted.
- `--persist` – Ensures sessions survive after clients disconnect.

According to the server architecture documentation in [`docs/SERVER_ARCHITECTURE.md`](https://github.com/1jehuang/jcode/blob/main/docs/SERVER_ARCHITECTURE.md), this configuration creates the infrastructure needed for the Create/Resume session flow. The server writes a unique JSON file for each session (e.g., [`fox.json`](https://github.com/1jehuang/jcode/blob/main/fox.json)) to the specified directory, which serves as the source of truth for resumption.

## Locate the Session Identifier

To resume a specific session, you need its **session ID** (e.g., `fox`). You can discover active sessions through three methods:

- **CLI output** – The client prints "Created session \<id\>" upon initial connection.
- **`jcode list`** – Run this sub-command while connected to enumerate all persisted sessions on the server.
- **Directory inspection** – List the contents of the session directory; each file is named `<session-id>.json`.

As documented in [`docs/MULTI_SESSION_CLIENT_ARCHITECTURE.md`](https://github.com/1jehuang/jcode/blob/main/docs/MULTI_SESSION_CLIENT_ARCHITECTURE.md), the `list` command queries the server for all available persisted sessions, making it easy to identify which ID to use for resumption.

## Resume the Session from Your Raspberry Pi

Once you have the session ID and confirmed the server is running, connect from your Raspberry Pi using the resume flag:

```bash
jcode --connect ws://<SERVER_IP>:7777 \
      --resume fox

```

Replace `<SERVER_IP>` with the IP address of your persistent server and `fox` with your actual session ID.

The `--connect` parameter specifies the WebSocket endpoint, while `--resume <id>` instructs the client to attach to existing on-disk state rather than initializing a new session. The client fetches the stored history, current model selections, and open tool contexts, restoring the exact interface state you left behind.

## Under the Hood: The Resume Mechanism

The resumption process follows a strict RPC protocol defined in [`crates/jcode-protocol/src/lib.rs`](https://github.com/1jehuang/jcode/blob/main/crates/jcode-protocol/src/lib.rs) at line 167.

When you execute `--resume`, the client sends a `resume_session` RPC (`jcode-protocol::resume_session`) to the server. The server-side handler `handle_resume_session` (located in [`src/server/client_session.rs`](https://github.com/1jehuang/jcode/blob/main/src/server/client_session.rs)) loads the corresponding JSON file from the session directory, rebuilds the in-memory `Session` struct, and returns the current state to the client.

The client-side implementation in [`src/tui/workspace_client.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/workspace_client.rs) then re-hydrates the UI, restores the model picker cache, and continues normal operation. The Swift iOS audit in [`docs/MOBILE_SWIFT_AUDIT.md`](https://github.com/1jehuang/jcode/blob/main/docs/MOBILE_SWIFT_AUDIT.md) (line 128) confirms that `resume_session` is treated as a first-class RPC operation across all platforms.

## Common Pitfalls and Solutions

| Issue | Solution |
|-------|----------|
| **"Session not found" error** | Verify the server was started with `--persist` and that `<session-id>.json` exists in the session directory. |
| **Network unreachable** | Ensure the Pi can reach the server's IP and port (check firewall rules and Wi-Fi connectivity). |
| **Version mismatch** | Both client and server must run the same jcode binary version to maintain RPC payload compatibility. |
| **Concurrent resume attempts** | Only one client may hold a live session. A second `--resume` will "take over" the session, causing the first client to disconnect, as documented in the test file [`src/server/client_session_tests/resume.rs`](https://github.com/1jehuang/jcode/blob/main/src/server/client_session_tests/resume.rs). |

## Summary

- Run `jcode --listen ws://0.0.0.0:7777 --session-dir <path> --persist` to create a stateful server that survives disconnections.
- Identify your target session ID using `jcode list` or by inspecting the JSON files in the session directory.
- From the Raspberry Pi, execute `jcode --connect ws://<SERVER_IP>:7777 --resume <session-id>` to restore the full session state.
- The resume mechanism uses the `resume_session` RPC defined in [`crates/jcode-protocol/src/lib.rs`](https://github.com/1jehuang/jcode/blob/main/crates/jcode-protocol/src/lib.rs), handled by `handle_resume_session` in [`src/server/client_session.rs`](https://github.com/1jehuang/jcode/blob/main/src/server/client_session.rs).
- Ensure version parity between client and server to avoid serialization errors.

## Frequently Asked Questions

### Can I resume a session if the server was not started with `--persist`?

No. Without the `--persist` flag, the server destroys session data immediately upon client disconnect. The session JSON files are never written to disk, making resumption impossible. You must restart the server with `--persist` and create a new session to enable future resumptions.

### What happens if two clients attempt to resume the same session simultaneously?

The jcode server enforces single-client ownership. When a second client issues `--resume` for an active session, the server transfers ownership to the new connection and disconnects the previous client. This "takeover" behavior is tested in [`src/server/client_session_tests/resume.rs`](https://github.com/1jehuang/jcode/blob/main/src/server/client_session_tests/resume.rs), ensuring that session state transfers cleanly without corruption.

### Where exactly are session states stored on the server?

Session states are stored as individual JSON files in the directory specified by `--session-dir`. Each file is named `<session-id>.json` and contains the full serialized state including conversation history, model configuration, and tool contexts. These files act as the atomic unit of persistence for the resume functionality.

### Do I need identical jcode versions on both the server and Raspberry Pi?

Yes. The RPC protocol between client and server must match exactly. Version mismatches can cause payload deserialization failures or subtle state corruption. Always deploy the same jcode binary version (or compatible semver equivalents) on both the persistent server and your Raspberry Pi client.