feat(scratchpad): add per-session scratchpad viewer

CHANGELOG.md

@@ -9,6 +9,7 @@ For the full list of merged PRs per release, see [GitHub Releases](https://githu
 ## [Unreleased]
 
 ### Added
+- Session scratchpad viewer: open a session's Claude Code scratchpad directory (`/tmp/claude-<uid>/<project>/<session-id>/scratchpad/`) in its own tab from the session context menu or the `⋯` menu, with a lazily-loaded file tree, text / Markdown / image preview, and live refresh.
 - `general.autoExpandAIGroups` setting: automatically expands all AI response groups when opening a transcript or when new AI responses arrive in a live session. Defaults to off. Persists across restarts.
 - Strict IPC input validation guards for project / session / subagent / search limits.
 - `get-waterfall-data` IPC endpoint implementation.

README.md

@@ -82,6 +82,7 @@ The only workaround is `--verbose`, which dumps raw JSON, internal system prompt
 | Nothing about thinking | Extended thinking content, fully visible |
 | `--verbose` JSON dump | Structured, filterable, navigable interface — no noise |
 | Per-project Claude memory hidden in `~/.claude/projects/.../memory/` | `MEMORY.md` rendered as a clickable index of layers; open any layer in your editor |
+| Session scratch files buried in `/tmp/claude-<uid>/...` | Each session's scratchpad as a live file tree, with code, Markdown and images previewed inline |
 | Copy from terminal = wrapped lines, ANSI codes, broken Markdown | Real selectable text, one-click copy on every message and code block |
 
 **Zero configuration. No API keys. No wrappers. Works with every session you've ever run.**
@@ -131,6 +132,10 @@ Copying Claude Code output from the terminal mangles it — selection wraps at t
 
 Claude Code stores per-project memory at `~/.claude/projects/<project>/memory/` — a `MEMORY.md` index plus one `.md` file per layer (working style, architecture notes, etc.). claude-devtools surfaces this as a sidebar entry that opens a dedicated pane: layer list on the left, full markdown rendering on the right with frontmatter shown as a metadata card, Obsidian-style `[[wikilinks]]` for cross-layer navigation, and an icon-driven "Open in…" launcher that hands any layer (or the whole memory folder) off to Finder/Explorer, Cursor, VS Code, Zed, Xcode, iTerm, Ghostty, Terminal — or copies the absolute path.
 
+### Session Scratchpad
+
+Claude Code gives every session a private scratch directory at `/tmp/claude-<uid>/<project>/<session-id>/scratchpad/` (or under `CLAUDE_CODE_TMPDIR`), where it drops drafts, downloaded data, screenshots and throwaway scripts. Right-click a session in the sidebar, or use the `⋯` menu of an open session, and choose **Open Scratchpad** to browse it: a lazily-expanded file tree on the left, and the selected file on the right — syntax-highlighted code, Markdown with a code/preview toggle, or an inline image. The view refreshes while it is open, so files a live session writes appear as they land. Local sessions only.
+
 ### [Team & Subagent Trees](https://claude-dev.tools/docs/subagents)
 
 Isolated execution trees per agent with tool traces, token metrics, duration, and cost. Nested agents render recursively.

src/main/http/index.ts

@@ -12,6 +12,7 @@ import { registerEventRoutes } from './events';
 import { registerMemoryRoutes } from './memory';
 import { registerNotificationRoutes } from './notifications';
 import { registerProjectRoutes } from './projects';
+import { registerScratchpadRoutes } from './scratchpad';
 import { registerSearchRoutes } from './search';
 import { registerSessionRoutes } from './sessions';
 import { registerSshRoutes } from './ssh';
@@ -61,6 +62,7 @@ export function registerHttpRoutes(
   registerSshRoutes(app, services.sshConnectionManager, sshModeSwitchCallback);
   registerUpdaterRoutes(app, services);
   registerMemoryRoutes(app, services);
+  registerScratchpadRoutes(app);
   registerEventRoutes(app);
 
   logger.info('All HTTP routes registered');

src/main/http/scratchpad.ts

@@ -0,0 +1,64 @@
+/**
+ * HTTP route handlers for the per-session Scratchpad viewer.
+ *
+ * Mirrors the read paths of the IPC surface. Opening files in the OS file
+ * manager has no meaning for a browser client, so it is not exposed here.
+ */
+
+import { scratchpadReader } from '@main/services/discovery/ScratchpadReader';
+import { createLogger } from '@shared/utils/logger';
+
+import { validateScratchpadArgs } from '../ipc/guards';
+
+import type { ScratchpadListResult, ScratchpadReadFileResult } from '@shared/types';
+import type { FastifyInstance } from 'fastify';
+
+const logger = createLogger('HTTP:scratchpad');
+
+interface ScratchpadQuery {
+  projectId?: string;
+  sessionId?: string;
+  path?: string;
+}
+
+export function registerScratchpadRoutes(app: FastifyInstance): void {
+  app.get<{ Querystring: ScratchpadQuery }>(
+    '/api/scratchpad/list',
+    async (request): Promise<ScratchpadListResult> => {
+      const { projectId, sessionId, path } = request.query;
+      const args = validateScratchpadArgs(projectId, sessionId, path);
+      if (!args.valid) return { success: false, error: args.error };
+      try {
+        const listing = await scratchpadReader.list(
+          args.projectId,
+          args.sessionId,
+          args.relativePath
+        );
+        return { success: true, ...listing };
+      } catch (error) {
+        logger.error('Error in GET /api/scratchpad/list:', error);
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  );
+
+  app.get<{ Querystring: ScratchpadQuery }>(
+    '/api/scratchpad/file',
+    async (request): Promise<ScratchpadReadFileResult> => {
+      const { projectId, sessionId, path } = request.query;
+      const args = validateScratchpadArgs(projectId, sessionId, path);
+      if (!args.valid) return { success: false, error: args.error };
+      try {
+        const result = await scratchpadReader.readFile(
+          args.projectId,
+          args.sessionId,
+          args.relativePath
+        );
+        return { success: true, ...result };
+      } catch (error) {
+        logger.error('Error in GET /api/scratchpad/file:', error);
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  );
+}

src/main/ipc/guards.ts

@@ -146,3 +146,35 @@ export function coerceSearchMaxResults(value: unknown, defaultValue: number = 50
 export function coercePageLimit(value: unknown, defaultValue: number = 20): number {
   return coerceLimit(value, defaultValue, MAX_PAGE_LIMIT);
 }
+
+type ScratchpadArgsResult =
+  | { valid: true; projectId: string; sessionId: string; relativePath: string }
+  | { valid: false; error: string };
+
+/**
+ * Validate the (projectId, sessionId, relativePath) triple shared by every
+ * scratchpad call. A missing relativePath means the scratchpad root.
+ */
+export function validateScratchpadArgs(
+  projectId: unknown,
+  sessionId: unknown,
+  relativePath: unknown
+): ScratchpadArgsResult {
+  const projectIdResult = validateProjectId(projectId);
+  if (!projectIdResult.valid || !projectIdResult.value) {
+    return { valid: false, error: projectIdResult.error ?? 'Invalid projectId' };
+  }
+  const sessionIdResult = validateSessionId(sessionId);
+  if (!sessionIdResult.valid || !sessionIdResult.value) {
+    return { valid: false, error: sessionIdResult.error ?? 'Invalid sessionId' };
+  }
+  if (relativePath !== undefined && relativePath !== null && typeof relativePath !== 'string') {
+    return { valid: false, error: 'relativePath must be a string' };
+  }
+  return {
+    valid: true,
+    projectId: projectIdResult.value,
+    sessionId: sessionIdResult.value,
+    relativePath: relativePath ?? '',
+  };
+}

src/main/ipc/handlers.ts

@@ -31,6 +31,11 @@ import {
   registerProjectHandlers,
   removeProjectHandlers,
 } from './projects';
+import {
+  initializeScratchpadHandlers,
+  registerScratchpadHandlers,
+  removeScratchpadHandlers,
+} from './scratchpad';
 import { initializeSearchHandlers, registerSearchHandlers, removeSearchHandlers } from './search';
 import {
   initializeSessionHandlers,
@@ -81,6 +86,7 @@ export function initializeIpcHandlers(
   initializeSshHandlers(sshManager, registry, contextCallbacks.rewire);
   initializeContextHandlers(registry, contextCallbacks.rewire);
   initializeMemoryHandlers(registry);
+  initializeScratchpadHandlers(registry);
   initializeConfigHandlers({
     onClaudeRootPathUpdated: contextCallbacks.onClaudeRootPathUpdated,
   });
@@ -98,6 +104,7 @@ export function initializeIpcHandlers(
   registerSshHandlers(ipcMain);
   registerContextHandlers(ipcMain);
   registerMemoryHandlers(ipcMain);
+  registerScratchpadHandlers(ipcMain);
   registerWindowHandlers(ipcMain);
 
   logger.info('All handlers registered');
@@ -120,6 +127,7 @@ export function removeIpcHandlers(): void {
   removeSshHandlers(ipcMain);
   removeContextHandlers(ipcMain);
   removeMemoryHandlers(ipcMain);
+  removeScratchpadHandlers(ipcMain);
   removeWindowHandlers(ipcMain);
 
   logger.info('All handlers removed');

src/main/ipc/scratchpad.ts

@@ -0,0 +1,123 @@
+/**
+ * IPC Handlers for the per-session Scratchpad viewer.
+ *
+ * Surface:
+ * - scratchpad:list      → ScratchpadListResult (one directory level)
+ * - scratchpad:readFile  → ScratchpadReadFileResult (text, image or binary stub)
+ * - scratchpad:openPath  → reveal a file in the OS file manager, or open a directory
+ *
+ * Read-only. Scratchpads live in the local temp directory, so SSH contexts are
+ * rejected rather than resolved against the wrong machine.
+ */
+
+import { scratchpadReader } from '@main/services/discovery/ScratchpadReader';
+import { createLogger } from '@shared/utils/logger';
+import { type IpcMain, type IpcMainInvokeEvent, shell } from 'electron';
+import * as fs from 'fs';
+
+import { validateScratchpadArgs } from './guards';
+
+import type { ServiceContextRegistry } from '../services';
+import type {
+  ScratchpadListResult,
+  ScratchpadOpenResult,
+  ScratchpadReadFileResult,
+} from '@shared/types';
+
+const SCRATCHPAD_LIST = 'scratchpad:list';
+const SCRATCHPAD_READ_FILE = 'scratchpad:readFile';
+const SCRATCHPAD_OPEN_PATH = 'scratchpad:openPath';
+
+const logger = createLogger('IPC:scratchpad');
+
+let registry: ServiceContextRegistry;
+
+export function initializeScratchpadHandlers(contextRegistry: ServiceContextRegistry): void {
+  registry = contextRegistry;
+}
+
+export function registerScratchpadHandlers(ipcMain: IpcMain): void {
+  ipcMain.handle(SCRATCHPAD_LIST, handleList);
+  ipcMain.handle(SCRATCHPAD_READ_FILE, handleReadFile);
+  ipcMain.handle(SCRATCHPAD_OPEN_PATH, handleOpenPath);
+  logger.info('Scratchpad handlers registered');
+}
+
+export function removeScratchpadHandlers(ipcMain: IpcMain): void {
+  ipcMain.removeHandler(SCRATCHPAD_LIST);
+  ipcMain.removeHandler(SCRATCHPAD_READ_FILE);
+  ipcMain.removeHandler(SCRATCHPAD_OPEN_PATH);
+}
+
+function sshUnsupported(): { success: false; error: string } | null {
+  return registry?.getActive().type === 'ssh'
+    ? { success: false, error: 'Scratchpads are only available for local sessions' }
+    : null;
+}
+
+async function handleList(
+  _event: IpcMainInvokeEvent,
+  projectId: unknown,
+  sessionId: unknown,
+  relativeDir: unknown
+): Promise<ScratchpadListResult> {
+  const args = validateScratchpadArgs(projectId, sessionId, relativeDir);
+  if (!args.valid) return { success: false, error: args.error };
+  const unsupported = sshUnsupported();
+  if (unsupported) return unsupported;
+  try {
+    const listing = await scratchpadReader.list(args.projectId, args.sessionId, args.relativePath);
+    return { success: true, ...listing };
+  } catch (error) {
+    logger.error('Error in scratchpad:list:', error);
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function handleReadFile(
+  _event: IpcMainInvokeEvent,
+  projectId: unknown,
+  sessionId: unknown,
+  relativePath: unknown
+): Promise<ScratchpadReadFileResult> {
+  const args = validateScratchpadArgs(projectId, sessionId, relativePath);
+  if (!args.valid) return { success: false, error: args.error };
+  const unsupported = sshUnsupported();
+  if (unsupported) return unsupported;
+  try {
+    const result = await scratchpadReader.readFile(
+      args.projectId,
+      args.sessionId,
+      args.relativePath
+    );
+    return { success: true, ...result };
+  } catch (error) {
+    logger.error('Error in scratchpad:readFile:', error);
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function handleOpenPath(
+  _event: IpcMainInvokeEvent,
+  projectId: unknown,
+  sessionId: unknown,
+  relativePath: unknown
+): Promise<ScratchpadOpenResult> {
+  const args = validateScratchpadArgs(projectId, sessionId, relativePath);
+  if (!args.valid) return { success: false, error: args.error };
+  const unsupported = sshUnsupported();
+  if (unsupported) return unsupported;
+  try {
+    const rootPath = scratchpadReader.getRootPath(args.projectId, args.sessionId);
+    const target = await scratchpadReader.resolveInside(rootPath, args.relativePath);
+    if ((await fs.promises.stat(target)).isDirectory()) {
+      const error = await shell.openPath(target);
+      return error ? { success: false, error } : { success: true };
+    }
+    shell.showItemInFolder(target);
+    return { success: true };
+  } catch (error) {
+    logger.error('Error in scratchpad:openPath:', error);
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}