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

> Discover where Pi session files are stored by default in ~/.pi/agent/sessions. Learn about the .jsonl record format and path organization for Pi web session storage.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: deep-dive
- Published: 2026-07-30

---

**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`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts).

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

```text
~/.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`](https://github.com/agegr/pi-web/blob/main/README.md) (lines 81-83) and visualized in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts)**: Core utilities including `getAgentDir()`, `listAllSessions()`, and `resolveSessionPath()` that locate and parse session files.
- **[`lib/session-path.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-path.ts)**: Generates stable cache keys derived from session file paths.
- **[`lib/session-file-references.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-file-references.ts)**: Manages references between sessions, such as parent-child relationships in conversation threads.
- **[`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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.