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

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

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 (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 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.

// 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 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 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 automatically detects legacy installs and falls back to this path, maintaining the same projects/<sanitized-cwd>/<sessionId>.jsonl subdirectory structure.

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