Skip to main content
Claw Code keeps a lightweight session store under .port_sessions/ in the working directory. These two commands let you persist a new session and reload an existing one.

​
flush-transcript

Persists and flushes a temporary session transcript. 
python3 -m src.main flush-transcript <prompt>

​
Arguments

​
prompt
string
required
A prompt string to submit to the QueryEnginePort before the transcript is persisted. This seeds the session with at least one message so the saved file is non-empty.

​
What it does

  1. Builds a QueryEnginePort from the current workspace.
  2. Calls engine.submit_message(prompt) to add the prompt to the session.
  3. Calls engine.persist_session(), which flushes the TranscriptStore and writes a JSON file to .port_sessions/<session_id>.json.
  4. Prints the path to the saved file and the flushed flag.

​
Output format

.port_sessions/a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6.json
flushed=True
LineDescription
Line 1Relative or absolute path to the saved session JSON file
Line 2flushed=True confirms the TranscriptStore was flushed successfully

​
Session file format

The JSON file written to .port_sessions/ follows the StoredSession schema: 
{
  "session_id": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6",
  "messages": [
    "explain the bootstrap sequence"
  ],
  "input_tokens": 42,
  "output_tokens": 18
}

​
Example

python3 -m src.main flush-transcript "explain the bootstrap sequence"

.port_sessions/a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6.json
flushed=True
The session_id is a random UUID hex string generated when the QueryEnginePort is created. Copy it from the output path to use with load-session.

​
load-session

Loads a previously persisted session by its session ID and prints a summary. 
python3 -m src.main load-session <session_id>

​
Arguments

​
session_id
string
required
The UUID hex string identifying the session. This must match the filename (without the .json extension) in .port_sessions/.

​
What it does

Reads .port_sessions/<session_id>.json, deserialises the StoredSession, and prints a three-line summary.

​
Output format

<session_id>
<N> messages
in=<input_tokens> out=<output_tokens>
LineDescription
Line 1The session ID
Line 2Number of stored messages (prompts) in the session
Line 3Token usage totals: input tokens and output tokens

​
Example

python3 -m src.main load-session a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6

a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6
1 messages
in=42 out=18
load-session reads the file from .port_sessions/ in the current working directory. Run it from the project root, or the file will not be found.

​
When to use these commands

Use flush-transcript at the end of an exploration workflow to checkpoint your session before closing the terminal. Use load-session to verify that the file was written correctly and to inspect the token usage before deciding whether to restore the session in a future workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us