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

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:

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, 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) 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, 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:

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 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) 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 then re-hydrates the UI, restores the model picker cache, and continues normal operation. The Swift iOS audit in 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.

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, handled by handle_resume_session in 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}