# Where Are Background Session Logs Stored in OpenClaude? Storage Paths and Access Methods

> Discover where OpenClaude background session logs are stored locally and in the cloud. Learn to access logs via file reads, CLI commands, or the VS Code interface.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Background session logs in OpenClaude are stored as JSONL files at `~/.openclaude/projects/<sanitized-cwd>/<sessionId>.jsonl` locally, with optional cloud persistence via the session-ingress API, and can be accessed through direct file reads, the `/session` CLI command, or VS Code's "Resume Conversation" interface.**

OpenClaude persists every interactive and background session as a **JSON Lines (JSONL)** log file, creating a complete chronological transcript of messages, tool calls, and internal events. Whether you are debugging a failed tool invocation or auditing an asynchronous task, understanding where these **background session logs** reside and how to parse them is essential for operational visibility. This guide details the exact file paths, construction logic, and programmatic access methods based on the OpenClaude source code.

## Local Storage Location and Path Construction

OpenClaude writes session logs to your local filesystem using a deterministic directory hierarchy. The storage location depends on whether you are using a legacy installation or the current version.

### How OpenClaude Constructs the Log Path

The `SessionManager` class in [`vscode-extension/openclaude-vscode/src/chat/sessionManager.js`](https://github.com/Gitlawb/openclaude/blob/main/vscode-extension/openclaude-vscode/src/chat/sessionManager.js) builds the log path through a chain of resolution functions:

1. **Base configuration directory** – The `resolveConfigDir()` function selects `~/.openclaude` by default, falling back to `~/.claude` for legacy installations (lines 5-9).

2. **Projects directory** – `getProjectsDir()` joins the config directory with the `projects` subdirectory (lines 46-48).

3. **Per-repository sanitization** – `getProjectDir(cwd)` sanitizes the current working directory by replacing non-alphanumeric characters with hyphens, then appends this sanitized string to the projects path (lines 50-52).

4. **Session file resolution** – `SessionManager._extractSessionMeta` returns the final `filePath` pointing to `<sessionId>.jsonl` within that directory (lines 64-71).

The complete path follows this pattern:

```

~/.openclaude/projects/<sanitized-cwd>/<sessionId>.jsonl

```

## How to Access Background Session Logs

You can retrieve session data through three primary interfaces: direct filesystem access, the CLI/VS Code extension, or remote cloud storage.

### Direct File System Access

For programmatic analysis or external tooling, read the JSONL file directly using Node.js filesystem APIs. The following implementation mirrors the path construction logic found in `SessionManager`:

```typescript
import { readFile } from 'fs/promises';
import { homedir } from 'os';
import path from 'path';

async function readSessionLog(cwd: string, sessionId: string) {
  // Match OpenClaude's sanitization logic exactly
  const sanitized = cwd.replace(/[^a-zA0-9]/g, '-');
  const logPath = path.join(
    homedir(),
    '.openclaude',
    'projects',
    sanitized,
    `${sessionId}.jsonl`,
  );
  
  const raw = await readFile(logPath, 'utf8');
  return raw
    .split('\n')
    .filter(Boolean)
    .map(JSON.parse); // Returns array of log entry objects
}

```

Each line in the JSONL file represents a discrete event—such as user messages, assistant responses, or tool invocations—in chronological order.

### Via the OpenClaude CLI and VS Code Extension

The interactive interface provides convenient access without writing custom scripts:

- **Remote URL generation** – Execute the `/session` slash-command inside the OpenClaude REPL. Defined in [`src/data/commands.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/data/commands.ts) (lines 76-78), this command displays a shareable URL and QR code for cloud-stored logs.

- **Session enumeration** – Use the VS Code extension's "Resume Conversation" UI, which internally calls `SessionManager.listSessions()` to enumerate all JSONL files in the projects directory, displaying titles, timestamps, and preview snippets.

### Remote Cloud Storage Access

When authenticated with a valid Claude Code token, OpenClaude synchronizes logs to cloud storage in real-time. The `appendSessionLog` function in [`src/services/api/sessionIngress.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/sessionIngress.ts) transmits each log entry to the session-ingress API using optimistic concurrency (via the `Last-Uuid` header).

After session completion, the `/session` command retrieves the cloud-hosted URL. This remote copy contains identical JSONL content to the local file, accessible via browser or mobile QR scan.

```typescript
// Simplified flow from sessionIngress.ts
export async function appendSessionLog(sessionId, entry, url) {
  const token = getSessionIngressAuthToken(); // JWT authentication
  // PUT request to cloud storage with concurrency control
}

```

## Summary

- **Local path structure**: Logs reside at `~/.openclaude/projects/<sanitized-cwd>/<sessionId>.jsonl`, constructed by `SessionManager` using `resolveConfigDir()` and path sanitization logic.
- **File format**: **JSON Lines (JSONL)** containing chronological transcripts of all session events.
- **CLI access**: The `/session` command generates shareable URLs and QR codes; `SessionManager.listSessions()` enumerates local history.
- **Cloud persistence**: `appendSessionLog` in [`src/services/api/sessionIngress.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/sessionIngress.ts) handles real-time cloud synchronization for authenticated users.

## Frequently Asked Questions

### What file format does OpenClaude use for session logs?

OpenClaude uses **JSON Lines (JSONL)** format. Each line represents a separate JSON object containing a timestamped event—such as a message, tool call, or internal state change—allowing for efficient appending and streaming parsing without loading entire files into memory.

### How does OpenClaude sanitize the directory path for session storage?

The `getProjectDir(cwd)` function in [`vscode-extension/openclaude-vscode/src/chat/sessionManager.js`](https://github.com/Gitlawb/openclaude/blob/main/vscode-extension/openclaude-vscode/src/chat/sessionManager.js) sanitizes the current working directory by replacing all non-alphanumeric characters with hyphens using the regex `/[^a-zA0-9]/g`. This ensures valid directory names across different operating systems while maintaining a predictable mapping to your project location.

### Can I access background session logs without using the OpenClaude CLI?

Yes. Since logs are standard JSONL files stored on local disk, you can read them directly using any programming language or text editor. Navigate to `~/.openclaude/projects/<sanitized-directory-name>/` and open the `<sessionId>.jsonl` file. Alternatively, if cloud sync is enabled, access the logs via the shareable URL obtained from the `/session` command output.

### Where are legacy OpenClaude session logs stored?

Legacy installations use `~/.claude` as the base configuration directory instead of `~/.openclaude`. The `resolveConfigDir()` function in [`sessionManager.js`](https://github.com/Gitlawb/openclaude/blob/main/sessionManager.js) automatically detects legacy installs and falls back to this path, maintaining the same `projects/<sanitized-cwd>/<sessionId>.jsonl` subdirectory structure.