claude-plan-viewer 1.4.1 → 1.5.0

package/README.md

@@ -2,10 +2,13 @@
 
 > Browse, search, and read your Claude Code plans in a clean web UI
 
+[![Website](https://img.shields.io/badge/Website-claudeplans.dev-blue)](https://claudeplans.dev)
 [![npm version](https://img.shields.io/npm/v/claude-plan-viewer.svg)](https://www.npmjs.com/package/claude-plan-viewer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logo=bun&logoColor=white)](https://bun.sh)
 
+**[📖 Documentation](https://claudeplans.dev)** | **[🚀 Quick Start](https://claudeplans.dev/getting-started/quickstart)** | **[📚 API Reference](https://claudeplans.dev/reference/api)**
+
 ![screenshot](screenshot.png)
 
 ## Features
@@ -66,6 +69,10 @@ claude-plan-viewer
 # Start on specific port
 claude-plan-viewer --port 8080
 claude-plan-viewer -p 8080
+
+# Listen on all network interfaces (accessible from other devices)
+claude-plan-viewer --host 0.0.0.0
+claude-plan-viewer -H 0.0.0.0
 ```
 
 The server will automatically find an available port if the requested port is in use.
@@ -75,6 +82,7 @@ The server will automatically find an available port if the requested port is in
 | Flag                  | Short | Description                                               |
 | --------------------- | ----- | --------------------------------------------------------- |
 | `--port <number>`     | `-p`  | Port to start the server on (default: 3000)               |
+| `--host <address>`    | `-H`  | Host to bind to (default: localhost)                      |
 | `--claude-dir <path>` | `-c`  | Path to `.claude` directory (default: `~/.claude`)        |
 | `--json`              | `-j`  | Export all plans as JSON and exit                         |
 | `--output <file>`     | `-o`  | Output file for JSON export (prints to stdout if omitted) |

package/index.ts

@@ -1,11 +1,14 @@
 #!/usr/bin/env bun
 import { readdir, stat, watch } from "node:fs/promises";
+import { createReadStream } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { createInterface } from "node:readline";
 import index from "./src/index.html";
 import apiDocs from "./src/api-docs.html";
 import pkg from "./package.json";
 import openapi from "./openapi.json";
+import getPort, { portNumbers } from "get-port";
 
 // Resolved at startup based on --claude-dir flag or CLAUDE_DIR env var
 let PLANS_DIR: string;
@@ -22,6 +25,7 @@ function initializeDirectories(claudeDir: string): void {
 
 interface CliArgs {
   port?: number;
+  host?: string;
   json?: boolean;
   output?: string;
   fromFile?: string;
@@ -43,6 +47,11 @@ function parseCliArgs(): CliArgs {
         args.port = parseInt(nextArg, 10);
         i++;
       }
+    } else if (arg === "--host" || arg === "-H") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.host = nextArg;
+        i++;
+      }
     } else if (arg === "--json" || arg === "-j") {
       args.json = true;
     } else if (arg === "--output" || arg === "-o") {
@@ -78,6 +87,8 @@ Usage: claude-plan-viewer [options]
 
 Options:
   -p, --port <number>       Port to start server on (default: 3000)
+  -H, --host <address>      Host to bind to (default: localhost)
+                            Use 0.0.0.0 to listen on all interfaces
   -c, --claude-dir <path>   Path to .claude directory (default: ~/.claude)
                             Can also be set via CLAUDE_DIR environment variable
   -j, --json                Export all plans as JSON and exit
@@ -89,6 +100,7 @@ Options:
 Examples:
   claude-plan-viewer                        Start viewer on default port
   claude-plan-viewer -p 8080                Start on port 8080
+  claude-plan-viewer -H 0.0.0.0             Listen on all network interfaces
   claude-plan-viewer -c /path/to/.claude    Use custom .claude directory
   claude-plan-viewer -j -o plans.json       Export plans to file
   claude-plan-viewer -f plans.json          Load plans from exported file
@@ -147,24 +159,7 @@ async function loadPlansFromFile(filepath: string): Promise<PlanMetadata[]> {
 
 // Find an available port starting from the requested port
 async function findAvailablePort(startPort: number = 3000): Promise<number> {
-  let port = startPort;
-  const maxAttempts = 100;
-
-  for (let i = 0; i < maxAttempts; i++) {
-    try {
-      const testServer = Bun.serve({
-        port,
-        fetch: () => new Response(),
-      });
-      testServer.stop();
-      return port;
-    } catch {
-      port++;
-    }
-  }
-  throw new Error(
-    `No available port found in range ${startPort}-${startPort + maxAttempts}`,
-  );
+  return getPort({ port: portNumbers(startPort, startPort + 100) });
 }
 
 // Cross-platform open file in default editor
@@ -192,10 +187,6 @@ interface PlanMetadata {
   sessionId: string | null;
 }
 
-interface Plan extends PlanMetadata {
-  content: string;
-}
-
 // Extract project name from a full path (cross-platform)
 // e.g., "/Users/helge/code/plans-viewer" -> "plans-viewer"
 // e.g., "C:\Users\name\code\my-app" -> "my-app"
@@ -212,48 +203,27 @@ function extractProjectName(cwd: string): string {
   return lastSlash === -1 ? trimmed : trimmed.slice(lastSlash + 1);
 }
 
-// Extract cwd (working directory) from JSONL content
-function extractCwdFromJsonl(content: string): string | null {
-  if (!content) return null;
-  const match = content.match(/"cwd":"([^"]+)"/);
-  if (!match || !match[1]) return null;
-  // Unescape JSON string (convert \\\\ to \\)
-  return match[1].replace(/\\\\/g, "\\");
-}
-
-// Extract slug -> sessionId mapping from JSONL content
-// Each line in JSONL may contain both "slug" and "sessionId" fields
-function extractSlugSessionMap(content: string): Map<string, string> {
-  if (!content) return new Map();
-  const slugSessionMap = new Map<string, string>();
-
-  // Process each line to find slug and sessionId pairs
-  const lines = content.split("\n");
-  for (const line of lines) {
-    if (!line.trim()) continue;
-
-    const slugMatch = line.match(/"slug":"([\w-]+)"/);
-    const sessionMatch = line.match(/"sessionId":"([^"]+)"/);
-
-    if (slugMatch && slugMatch[1] && sessionMatch && sessionMatch[1]) {
-      slugSessionMap.set(slugMatch[1], sessionMatch[1]);
-    }
-  }
-
-  return slugSessionMap;
-}
+// Stream a JSONL file line-by-line without loading the entire file into memory
+async function processJsonlLineByLine(
+  path: string,
+  onLine: (line: string) => void
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const stream = createReadStream(path, {
+      encoding: "utf-8",
+      highWaterMark: 64 * 1024,
+    });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
 
-// Extract unique slugs from JSONL content (for backwards compatibility)
-function extractSlugsFromJsonl(content: string): string[] {
-  if (!content) return [];
-  const slugs = new Set<string>();
-  const matches = content.matchAll(/"slug":"([\w-]+)"/g);
-  for (const match of matches) {
-    if (match[1]) {
-      slugs.add(match[1]);
-    }
-  }
-  return Array.from(slugs);
+    rl.on("line", (line) => {
+      if (line.length > 0) onLine(line);
+    });
+    rl.on("close", resolve);
+    rl.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+  });
 }
 
 interface SlugMetadata {
@@ -265,74 +235,67 @@ interface ProjectMapping {
   [slug: string]: SlugMetadata;
 }
 
-// Build a mapping of plan slugs to project names and session IDs by scanning Claude Code's project metadata
-async function buildProjectMapping(): Promise<ProjectMapping> {
+// Build a mapping of plan slugs to project names and session IDs by scanning Claude Code's project metadata.
+// Streams JSONL files line-by-line to avoid loading multi-GB project data into memory.
+// Only tracks slugs that correspond to actual plan files.
+async function buildProjectMapping(
+  neededSlugs?: Set<string>
+): Promise<ProjectMapping> {
   const mapping: ProjectMapping = {};
 
   try {
     const projectDirs = await readdir(PROJECTS_DIR);
 
-    // Process all project directories in parallel
-    const results = await Promise.all(
-      projectDirs.map(async (dir) => {
-        const dirPath = join(PROJECTS_DIR, dir);
-        try {
-          const dirStats = await stat(dirPath);
-          if (!dirStats.isDirectory()) return null;
-
-          // Find JSONL files
-          const files = await readdir(dirPath);
-          const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
-          if (jsonlFiles.length === 0) return null;
-
-          // Read all JSONL files in parallel
-          const fileContents = await Promise.all(
-            jsonlFiles.map(async (file) => {
-              try {
-                return await Bun.file(join(dirPath, file)).text();
-              } catch {
-                return null;
-              }
-            })
-          );
+    for (const dir of projectDirs) {
+      const dirPath = join(PROJECTS_DIR, dir);
+      try {
+        const dirStats = await stat(dirPath);
+        if (!dirStats.isDirectory()) continue;
 
-          let projectName: string | null = null;
-          const slugSessionMap = new Map<string, string>();
+        const files = await readdir(dirPath);
+        const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
+        if (jsonlFiles.length === 0) continue;
 
-          // Process file contents
-          for (const content of fileContents) {
-            if (!content) continue;
+        let projectName: string | null = null;
+        const slugSessionMap = new Map<string, string>();
 
-            // Get project name from cwd (only need to find it once)
-            if (!projectName) {
-              const cwd = extractCwdFromJsonl(content);
-              if (cwd) {
-                projectName = extractProjectName(cwd);
+        // Process files sequentially to keep memory bounded
+        for (const file of jsonlFiles) {
+          try {
+            await processJsonlLineByLine(join(dirPath, file), (line) => {
+              // Extract project name from cwd (only need first occurrence)
+              if (!projectName) {
+                const cwdMatch = line.match(/"cwd":"([^"]+)"/);
+                if (cwdMatch?.[1]) {
+                  const cwd = cwdMatch[1].replace(/\\\\/g, "\\");
+                  projectName = extractProjectName(cwd);
+                }
               }
-            }
 
-            // Collect slug -> sessionId mappings
-            const fileSlugSessions = extractSlugSessionMap(content);
-            for (const [slug, sessionId] of fileSlugSessions) {
-              slugSessionMap.set(slug, sessionId);
-            }
+              // Extract slug-sessionId pairs, filtering to only needed slugs
+              const slugMatch = line.match(/"slug":"([\w-]+)"/);
+              if (
+                slugMatch?.[1] &&
+                (!neededSlugs || neededSlugs.has(slugMatch[1]))
+              ) {
+                const sessionMatch = line.match(/"sessionId":"([^"]+)"/);
+                if (sessionMatch?.[1]) {
+                  slugSessionMap.set(slugMatch[1], sessionMatch[1]);
+                }
+              }
+            });
+          } catch {
+            // Skip unreadable files
           }
-
-          return { projectName, slugSessionMap };
-        } catch {
-          return null;
         }
-      })
-    );
 
-    // Merge results into mapping
-    for (const result of results) {
-      if (!result?.projectName) continue;
-      for (const [slug, sessionId] of result.slugSessionMap) {
-        mapping[slug] = {
-          project: result.projectName,
-          sessionId: sessionId,
-        };
+        if (projectName) {
+          for (const [slug, sessionId] of slugSessionMap) {
+            mapping[slug] = { project: projectName, sessionId };
+          }
+        }
+      } catch {
+        // Skip inaccessible directories
       }
     }
   } catch {
@@ -347,37 +310,39 @@ let cachedProjectMapping: ProjectMapping | null = null;
 const contentCache = new Map<string, string>();
 
 async function loadPlans(): Promise<PlanMetadata[]> {
-  // Build or use cached project mapping
+  const files = await readdir(PLANS_DIR);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+  // Build or use cached project mapping, passing needed slugs for targeted lookup
   let projectMapping: ProjectMapping;
   if (!cachedProjectMapping) {
-    projectMapping = await buildProjectMapping();
+    const neededSlugs = new Set(mdFiles.map((f) => f.replace(".md", "")));
+    projectMapping = await buildProjectMapping(neededSlugs);
     cachedProjectMapping = projectMapping;
   } else {
     projectMapping = cachedProjectMapping;
   }
 
-  const files = await readdir(PLANS_DIR);
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-
   const plans = await Promise.all(
     mdFiles.map(async (filename) => {
       const filepath = join(PLANS_DIR, filename);
       const file = Bun.file(filepath);
 
-      const [content, stats] = await Promise.all([file.text(), stat(filepath)]);
+      const [content, stats] = await Promise.all([
+        file.text(),
+        stat(filepath),
+      ]);
 
       const titleMatch = content.match(/^#\s+(.+)$/m);
       const title = titleMatch?.[1]
         ? titleMatch[1].replace(/^Plan:\s*/i, "")
         : filename.replace(".md", "");
 
-      // Look up project from metadata using plan slug (filename without .md)
       const slug = filename.replace(".md", "");
       const lineCount = content.split("\n").length;
       const wordCount = content.split(/\s+/).filter(Boolean).length;
 
       const metadata = projectMapping[slug];
-      // Cache content separately for search and lazy loading
       contentCache.set(filename, content);
 
       return {
@@ -440,12 +405,11 @@ async function watchPlansDirectory() {
 }
 
 // Main server startup
-async function startServer() {
-  const args = parseCliArgs();
-  const port = await findAvailablePort(args.port ?? 3000);
+async function startServer(port: number, host?: string) {
 
   const server = Bun.serve({
     port,
+    hostname: host,
     routes: {
       "/": index,
       "/api": () => Response.redirect("/api/", 301),
@@ -509,7 +473,10 @@ async function startServer() {
       "/api/refresh": {
         POST: async () => {
           const before = cachedPlans?.length ?? 0;
-          invalidateAllCaches();
+          // Only invalidate plans and content; project mapping is expensive
+          // to rebuild (streams all JSONL files) and rarely changes
+          invalidatePlansCache();
+          invalidateContentCache();
           await loadPlans();
           const after = cachedPlans?.length ?? 0;
           return Response.json({ success: true, before, after });
@@ -542,16 +509,10 @@ async function startServer() {
   return server;
 }
 
-// ANSI color codes
-const c = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
-  dim: "\x1b[2m",
-  green: "\x1b[32m",
-  cyan: "\x1b[36m",
-  yellow: "\x1b[33m",
-  magenta: "\x1b[35m",
-};
+// OSC 8 hyperlink escape sequence for clickable terminal URLs
+function link(url: string, text?: string): string {
+  return `\x1b]8;;${url}\x07${text ?? url}\x1b]8;;\x07`;
+}
 
 // Main entry point
 (async () => {
@@ -576,8 +537,13 @@ const c = {
     process.exit(0);
   }
 
-  // Pre-load plans from file if --from-file is provided
+  // Start server first
+  const port = await findAvailablePort(args.port ?? 3000);
+  const server = await startServer(port, args.host);
+
+  // Pre-load plans from file or directory
   let planCount: number;
+  let projectCount = 0;
   let sourceDisplay: string;
 
   if (args.fromFile) {
@@ -585,32 +551,30 @@ const c = {
     planCount = plans.length;
     sourceDisplay = args.fromFile;
   } else {
-    planCount = (await readdir(PLANS_DIR)).filter((f) =>
-      f.endsWith(".md"),
-    ).length;
     sourceDisplay = PLANS_DIR;
     // Only watch for file changes when not using --from-file
     watchPlansDirectory();
+
+    await loadPlans();
+
+    const projects = new Set(
+      (cachedPlans || []).map((p) => p.project).filter(Boolean)
+    );
+    projectCount = projects.size;
+    planCount = cachedPlans?.length ?? 0;
   }
 
-  const server = await startServer();
+  const localUrl = `http://localhost:${server.port}/`;
+  const apiUrl = `http://localhost:${server.port}/api/`;
+  const dirUrl = `file://${claudeDir}`;
 
-  console.log();
-  console.log(`${c.bold}${c.magenta}  📋 Claude Plan Viewer${c.reset}`);
-  console.log(`${c.dim}  ─────────────────────────────${c.reset}`);
-  console.log(`${c.green}  ✓${c.reset} Server running`);
-  if (!args.fromFile) {
-    console.log(`${c.green}  ✓${c.reset} Watching for file changes`);
+  console.log(`\nclaude-plan-viewer v${pkg.version}\n`);
+  console.log(`  ➜  Web:    ${link(localUrl)}`);
+  console.log(`  ➜  API:    ${link(apiUrl)}`);
+  if (args.fromFile) {
+    console.log(`  ➜  Source: ${sourceDisplay}`);
+  } else {
+    console.log(`  ➜  Dir:    ${link(dirUrl)} (${projectCount} projects)`);
   }
-  console.log();
-  console.log(
-    `${c.dim}  Local:${c.reset}   ${c.cyan}${c.bold}http://localhost:${server.port}${c.reset}`,
-  );
-  console.log(
-    `${c.dim}  API:${c.reset}     ${c.cyan}http://localhost:${server.port}/api/${c.reset}`,
-  );
-  console.log(
-    `${c.dim}  Plans:${c.reset}   ${c.yellow}${planCount} plans${c.reset} in ${c.dim}${sourceDisplay}${c.reset}`,
-  );
-  console.log();
+  console.log(`\n  Serving ${planCount} plans\n`);
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-viewer",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A web-based viewer for Claude Code plan files",
   "type": "module",
   "bin": {
@@ -29,7 +29,10 @@
     "install:local": "bun scripts/install-local.ts",
     "uninstall:link": "bun unlink",
     "uninstall:local": "bun scripts/uninstall-local.ts",
-    "format": "bunx prettier --write src"
+    "format": "bunx prettier --write src",
+    "website:dev": "cd website/docs && bun run dev",
+    "website:build": "cd website/docs && bun run build",
+    "website:preview": "cd website/docs && bun run preview"
   },
   "keywords": [
     "claude",
@@ -47,7 +50,7 @@
   "bugs": {
     "url": "https://github.com/HelgeSverre/claude-plan-viewer/issues"
   },
-  "homepage": "https://github.com/HelgeSverre/claude-plan-viewer#readme",
+  "homepage": "https://claudeplans.dev",
   "engines": {
     "bun": ">=1.0.0"
   },
@@ -63,6 +66,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "get-port": "^7.1.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-markdown": "^10.1.0",

package/src/api-docs.html

@@ -9,9 +9,20 @@
     <div id="app"></div>
     <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
     <script>
-      Scalar.createApiReference("#app", {
-        url: "/api/openapi.json",
-      });
+      const darkModeQuery = window.matchMedia("(prefers-color-scheme: dark)");
+
+      function createApiReference() {
+        document.getElementById("app").innerHTML = "";
+        Scalar.createApiReference("#app", {
+          url: "/api/openapi.json",
+          darkMode: darkModeQuery.matches,
+          hideDarkModeToggle: true,
+          hideClientButton: true,
+        });
+      }
+
+      createApiReference();
+      darkModeQuery.addEventListener("change", createApiReference);
     </script>
   </body>
 </html>

package/src/index.html

@@ -1,13 +1,33 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Claude Plans Viewer</title>
-    <link rel="stylesheet" href="./styles/styles.css" />
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./client/index.tsx"></script>
-  </body>
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Claude Plans Viewer</title>
+        <meta
+            name="description"
+            content="Browse, search, and read your Claude Code plans in a clean web UI"
+        />
+        <meta name="author" content="Helge Sverre" />
+        <meta property="og:title" content="Claude Plans Viewer" />
+        <meta
+            property="og:description"
+            content="Browse, search, and read your Claude Code plans in a clean web UI"
+        />
+        <meta property="og:type" content="website" />
+        <meta property="og:url" content="https://claudeplans.dev" />
+        <meta property="og:site_name" content="Claude Plans Viewer" />
+        <meta name="twitter:card" content="summary_large_image" />
+        <meta name="twitter:title" content="Claude Plans Viewer" />
+        <meta
+            name="twitter:description"
+            content="Browse, search, and read your Claude Code plans in a clean web UI"
+        />
+        <link rel="canonical" href="https://claudeplans.dev" />
+        <link rel="stylesheet" href="./styles/styles.css" />
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="./client/index.tsx"></script>
+    </body>
 </html>