Where Are Pi Session Files Stored? Pi Web Session Storage Explained

Pi Web stores session files as .jsonl records in ~/.pi/agent/sessions by default, with paths organized by encoded working-directory and timestamp-based filenames.

Pi Web, the web interface for the Pi coding agent (agegr/pi-web), persists conversation history locally in JSON Lines format. Knowing where Pi session files are stored enables you to backup conversations, debug issues, or build custom tooling around your interaction history.

Default Session Directory Structure

By default, Pi Web writes all conversation data to the Pi agent data directory located at ~/.pi/agent/sessions. This base directory is resolved through the getAgentDir() helper function defined in lib/session-reader.ts.

Each session exists as a separate .jsonl file with the following path structure:

~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl

The directory hierarchy serves two purposes:

• <encoded-cwd>: A directory name generated from the session's working directory path, grouping conversations by project location.
• <timestamp>_<uuid>.jsonl: The actual session file combining a Unix timestamp and UUID for unique identification.

This structure is documented in the repository's README.md (lines 81-83) and visualized in AGENTS.md, which shows the GET /api/sessions endpoint reading from this location.

Overriding the Default Storage Location

You can redirect Pi Web to read sessions from a custom location by setting the PI_CODING_AGENT_DIR environment variable. When defined, the application uses <PI_CODING_AGENT_DIR>/sessions instead of the default ~/.pi/agent/sessions.

This is useful for:

• Relocating session storage to external drives or network shares
• Running isolated Pi Web instances with separate conversation histories
• Container deployments requiring persistent volumes at specific mount points

Programmatic Access to Session Files

The lib/session-reader.ts module exports utilities for discovering and reading session files without manually traversing the filesystem.

List All Available Sessions

Use listAllSessions() to retrieve metadata for every session in the default data directory:

import { listAllSessions } from "@/lib/session-reader";

async function listSessions() {
  const sessions = await listAllSessions();
  sessions.forEach(s => console.log(s.id, s.path));
}

Resolve a Session Path by ID

The resolveSessionPath() function computes the absolute filesystem path for a given session identifier:

import { resolveSessionPath } from "@/lib/session-reader";

async function getPath(id: string) {
  const path = await resolveSessionPath(id);
  console.log(`Session ${id} → ${path}`);
}

Read Session Headers

Since session files are JSON Lines format, readSessionHeader() efficiently reads only the first line (containing metadata like ID and working directory) without loading the entire conversation:

import { readSessionHeader } from "@/lib/session-reader";

async function showHeader(sessionPath: string) {
  const header = readSessionHeader(sessionPath);
  console.log(header?.id, header?.cwd);
}

Key Implementation Files

Several modules in the Pi Web codebase handle session file locations:

• lib/session-reader.ts: Core utilities including getAgentDir(), listAllSessions(), and resolveSessionPath() that locate and parse session files.
• lib/session-path.ts: Generates stable cache keys derived from session file paths.
• lib/session-file-references.ts: Manages references between sessions, such as parent-child relationships in conversation threads.
• AGENTS.md: Architecture documentation confirming the ~/.pi/agent/sessions path used by the REST API.

Summary

• Pi session files live in ~/.pi/agent/sessions by default, following the pattern <encoded-cwd>/<timestamp>_<uuid>.jsonl.
• Set PI_CODING_AGENT_DIR to relocate the entire sessions directory to a custom path.
• The session file format is JSON Lines (.jsonl), with metadata in the first line and subsequent lines containing conversation events.
• Use lib/session-reader.ts for programmatic access rather than manual file system operations.

Frequently Asked Questions

Can I move existing Pi session files to a new directory?

Yes. After setting the PI_CODING_AGENT_DIR environment variable to your new location, copy the contents of the old ~/.pi/agent/sessions directory to <PI_CODING_AGENT_DIR>/sessions. Pi Web will treat the moved files as existing sessions on the next startup.

What format are Pi session files stored in?

Pi Web uses JSON Lines (.jsonl), where each line represents a JSON object. The first line contains session metadata (ID, working directory, creation time), and subsequent lines store conversation events and agent responses.

How does Pi Web organize sessions from different projects?

Sessions are grouped by encoded working-directory paths. The listAllSessions() function in lib/session-reader.ts scans subdirectories within the sessions folder, where each subdirectory name encodes the original project path where the Pi agent was invoked.

Is there a configuration file for changing the session storage path?

No configuration file is used. Pi Web exclusively relies on the PI_CODING_AGENT_DIR environment variable to determine where session files are stored. If this variable is unset, the application falls back to the default ~/.pi/agent location.

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