claude-plan-viewer 1.3.0 → 1.4.0

package/README.md

@@ -52,7 +52,7 @@ Download a pre-built binary from the [releases page](https://github.com/HelgeSve
 
 ```bash
 bun run build
-./dist/plans-viewer
+./dist/claude-plan-viewer
 ```
 
 The binary is fully self-contained (~57MB) and works offline.
@@ -60,15 +60,79 @@ The binary is fully self-contained (~57MB) and works offline.
 ## Usage
 
 ```bash
-# Start on auto-assigned port
+# Start the web viewer
 claude-plan-viewer
 
 # Start on specific port
 claude-plan-viewer --port 8080
+claude-plan-viewer -p 8080
 ```
 
 The server will automatically find an available port if the requested port is in use.
 
+### CLI Options
+
+| Flag                  | Short | Description                                               |
+| --------------------- | ----- | --------------------------------------------------------- |
+| `--port <number>`     | `-p`  | Port to start the server on (default: 3000)               |
+| `--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) |
+| `--from-file <file>`  | `-f`  | Load plans from a JSON file instead of `~/.claude/plans`  |
+| `--version`           | `-v`  | Show version number                                       |
+| `--help`              | `-h`  | Show help message                                         |
+
+The `--claude-dir` option can also be set via the `CLAUDE_DIR` environment variable. CLI flag takes precedence over the environment variable.
+
+### Export plans to JSON
+
+```bash
+# Print all plans as JSON to stdout
+claude-plan-viewer --json
+
+# Export to a file
+claude-plan-viewer --json --output plans.json
+claude-plan-viewer -j -o plans.json
+```
+
+The JSON export includes all plan metadata and content, useful for backup or processing.
+
+### Load plans from file
+
+```bash
+# Start viewer with plans from an exported JSON file
+claude-plan-viewer --from-file plans.json
+claude-plan-viewer -f plans.json
+```
+
+This allows viewing plans offline or from a different machine. When using `--from-file`, file watching is disabled since the plans are loaded from the static JSON file.
+
+### Custom .claude directory
+
+```bash
+# Use a custom .claude directory
+claude-plan-viewer --claude-dir /path/to/.claude
+claude-plan-viewer -c /path/to/.claude
+
+# Or set via environment variable
+CLAUDE_DIR=/path/to/.claude claude-plan-viewer
+```
+
+This is useful when your Claude Code data is stored in a non-standard location.
+
+## API
+
+The viewer exposes a REST API for programmatic access:
+
+| Endpoint                        | Method | Description                |
+| ------------------------------- | ------ | -------------------------- |
+| `/api/plans`                    | GET    | List all plans (metadata)  |
+| `/api/plans/{filename}/content` | GET    | Get plan markdown content  |
+| `/api/projects`                 | GET    | List all project names     |
+| `/api/refresh`                  | POST   | Force cache refresh        |
+| `/api/open`                     | POST   | Open plan in system editor |
+| `/api/openapi.json`             | GET    | OpenAPI 3.0 specification  |
+
 ## Development
 
 ```bash
@@ -77,6 +141,22 @@ bun install
 
 # Run in development mode with hot reload
 bun run dev
+
+# Or run directly with hot reload
+bun --hot index.ts
+
+# To use flags in dev mode, add them after `--`
+# Example: using --from-file
+bun run index.ts -- --from-file plans.json
+```
+
+## Running tests
+
+```bash
+bun run test
+
+# Note: Use `bun run test` instead of `bun test` directly,
+# as the script specifies the test directory path
 ```
 
 ## Building
@@ -85,18 +165,18 @@ Build standalone binaries for different platforms:
 
 ```bash
 bun run build              # Current platform
+bun run build:all          # All platforms
 bun run build:macos-arm64  # macOS Apple Silicon
 bun run build:macos-x64    # macOS Intel
 bun run build:linux-x64    # Linux x64
 bun run build:linux-arm64  # Linux ARM64
 bun run build:windows      # Windows x64
-bun run build:all          # All platforms
 ```
 
 ## Requirements
 
 - [Bun](https://bun.sh) runtime (for development/npx usage)
-- Claude Code with plan files in `~/.claude/plans`
+- Claude Code with plan files in `~/.claude/plans` (or custom location via `--claude-dir`)
 
 Standalone binaries have no external dependencies.
 

package/index.ts

@@ -2,16 +2,32 @@
 import { readdir, stat, watch } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import index from "./index.html";
-import prismBundlePath from "./prism.bundle.js" with { type: "file" };
+import index from "./src/index.html";
+import apiDocs from "./src/api-docs.html";
+import pkg from "./package.json";
+import openapi from "./openapi.json";
 
-const PLANS_DIR = join(homedir(), ".claude", "plans");
-const PROJECTS_DIR = join(homedir(), ".claude", "projects");
+// Resolved at startup based on --claude-dir flag or CLAUDE_DIR env var
+let PLANS_DIR: string;
+let PROJECTS_DIR: string;
+
+function resolveClaudeDir(cliArg?: string): string {
+  return cliArg || process.env.CLAUDE_DIR || join(homedir(), ".claude");
+}
+
+function initializeDirectories(claudeDir: string): void {
+  PLANS_DIR = join(claudeDir, "plans");
+  PROJECTS_DIR = join(claudeDir, "projects");
+}
 
 interface CliArgs {
   port?: number;
   json?: boolean;
   output?: string;
+  fromFile?: string;
+  claudeDir?: string;
+  version?: boolean;
+  help?: boolean;
 }
 
 function parseCliArgs(): CliArgs {
@@ -34,12 +50,51 @@ function parseCliArgs(): CliArgs {
         args.output = nextArg;
         i++;
       }
+    } else if (arg === "--from-file" || arg === "-f") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.fromFile = nextArg;
+        i++;
+      }
+    } else if (arg === "--claude-dir" || arg === "-c") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.claudeDir = nextArg;
+        i++;
+      }
+    } else if (arg === "--version" || arg === "-v") {
+      args.version = true;
+    } else if (arg === "--help" || arg === "-h") {
+      args.help = true;
     }
   }
 
   return args;
 }
 
+function printHelp(): void {
+  console.log(`
+claude-plan-viewer - Browse and search Claude Code plans
+
+Usage: claude-plan-viewer [options]
+
+Options:
+  -p, --port <number>       Port to start server on (default: 3000)
+  -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
+  -o, --output <file>       Output file for JSON export (stdout if omitted)
+  -f, --from-file <file>    Load plans from JSON file instead of ~/.claude/plans
+  -v, --version             Show version number
+  -h, --help                Show this help message
+
+Examples:
+  claude-plan-viewer                        Start viewer on default port
+  claude-plan-viewer -p 8080                Start on port 8080
+  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
+`);
+}
+
 async function exportPlansAsJson(outputPath?: string): Promise<void> {
   const plans = await loadPlans();
 
@@ -58,6 +113,38 @@ async function exportPlansAsJson(outputPath?: string): Promise<void> {
   }
 }
 
+async function loadPlansFromFile(filepath: string): Promise<PlanMetadata[]> {
+  const file = Bun.file(filepath);
+  const exists = await file.exists();
+
+  if (!exists) {
+    console.error(`File not found: ${filepath}`);
+    process.exit(1);
+  }
+
+  const data = await file.json();
+  const plans: PlanMetadata[] = [];
+
+  for (const plan of data) {
+    contentCache.set(plan.filename, plan.content || "");
+    plans.push({
+      filename: plan.filename,
+      filepath: plan.filepath,
+      title: plan.title,
+      size: plan.size,
+      modified: plan.modified,
+      created: plan.created,
+      lineCount: plan.lineCount,
+      wordCount: plan.wordCount,
+      project: plan.project,
+      sessionId: plan.sessionId,
+    });
+  }
+
+  cachedPlans = plans;
+  return plans;
+}
+
 // Find an available port starting from the requested port
 async function findAvailablePort(startPort: number = 3000): Promise<number> {
   let port = startPort;
@@ -75,7 +162,9 @@ async function findAvailablePort(startPort: number = 3000): Promise<number> {
       port++;
     }
   }
-  throw new Error(`No available port found in range ${startPort}-${startPort + maxAttempts}`);
+  throw new Error(
+    `No available port found in range ${startPort}-${startPort + maxAttempts}`,
+  );
 }
 
 // Cross-platform open file in default editor
@@ -115,7 +204,9 @@ function extractProjectName(cwd: string): string {
   // Normalize: handle both / and \ separators
   const normalized = cwd.replace(/\\/g, "/");
   // Remove trailing slash
-  const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+  const trimmed = normalized.endsWith("/")
+    ? normalized.slice(0, -1)
+    : normalized;
   // Get last segment
   const lastSlash = trimmed.lastIndexOf("/");
   return lastSlash === -1 ? trimmed : trimmed.slice(lastSlash + 1);
@@ -181,48 +272,67 @@ async function buildProjectMapping(): Promise<ProjectMapping> {
   try {
     const projectDirs = await readdir(PROJECTS_DIR);
 
-    for (const dir of projectDirs) {
-      const dirPath = join(PROJECTS_DIR, dir);
-      const dirStats = await stat(dirPath);
-      if (!dirStats.isDirectory()) continue;
-
-      // Find JSONL files and extract cwd + slugs + sessionIds
-      const files = await readdir(dirPath);
-      const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
-
-      let projectName: string | null = null;
-      const slugSessionMap = new Map<string, string>();
-
-      for (const file of jsonlFiles) {
+    // Process all project directories in parallel
+    const results = await Promise.all(
+      projectDirs.map(async (dir) => {
+        const dirPath = join(PROJECTS_DIR, dir);
         try {
-          const content = await Bun.file(join(dirPath, file)).text();
+          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;
+              }
+            })
+          );
+
+          let projectName: string | null = null;
+          const slugSessionMap = new Map<string, string>();
+
+          // Process file contents
+          for (const content of fileContents) {
+            if (!content) continue;
+
+            // Get project name from cwd (only need to find it once)
+            if (!projectName) {
+              const cwd = extractCwdFromJsonl(content);
+              if (cwd) {
+                projectName = extractProjectName(cwd);
+              }
+            }
 
-          // Get project name from cwd (only need to find it once)
-          if (!projectName) {
-            const cwd = extractCwdFromJsonl(content);
-            if (cwd) {
-              projectName = extractProjectName(cwd);
+            // Collect slug -> sessionId mappings
+            const fileSlugSessions = extractSlugSessionMap(content);
+            for (const [slug, sessionId] of fileSlugSessions) {
+              slugSessionMap.set(slug, sessionId);
             }
           }
 
-          // Collect slug -> sessionId mappings
-          const fileSlugSessions = extractSlugSessionMap(content);
-          for (const [slug, sessionId] of fileSlugSessions) {
-            slugSessionMap.set(slug, sessionId);
-          }
+          return { projectName, slugSessionMap };
         } catch {
-          // Skip files that can't be read
-        }
-      }
-
-      // Map all slugs to this project with their session IDs
-      if (projectName) {
-        for (const [slug, sessionId] of slugSessionMap) {
-          mapping[slug] = {
-            project: projectName,
-            sessionId: sessionId,
-          };
+          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,
+        };
       }
     }
   } catch {
@@ -254,10 +364,7 @@ async function loadPlans(): Promise<PlanMetadata[]> {
       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]
@@ -285,17 +392,34 @@ async function loadPlans(): Promise<PlanMetadata[]> {
         project: metadata?.project || null,
         sessionId: metadata?.sessionId || null,
       };
-    })
+    }),
   );
 
   cachedPlans = plans;
   return plans;
 }
 
-function invalidateCache() {
+// Granular cache invalidation
+function invalidatePlansCache() {
   cachedPlans = null;
+}
+
+function invalidateProjectMapping() {
   cachedProjectMapping = null;
-  contentCache.clear();
+}
+
+function invalidateContentCache(filename?: string) {
+  if (filename) {
+    contentCache.delete(filename);
+  } else {
+    contentCache.clear();
+  }
+}
+
+function invalidateAllCaches() {
+  invalidatePlansCache();
+  invalidateProjectMapping();
+  invalidateContentCache();
 }
 
 // Watch plans directory for changes and invalidate cache
@@ -304,7 +428,10 @@ async function watchPlansDirectory() {
     const watcher = watch(PLANS_DIR);
     for await (const event of watcher) {
       if (event.filename?.endsWith(".md")) {
-        invalidateCache();
+        // Only invalidate plans metadata and the specific file's content
+        // Project mapping rarely changes, keep it cached
+        invalidatePlansCache();
+        invalidateContentCache(event.filename);
       }
     }
   } catch {
@@ -321,6 +448,9 @@ async function startServer() {
     port,
     routes: {
       "/": index,
+      "/api": () => Response.redirect("/api/", 301),
+      "/api/": apiDocs,
+      "/api/openapi.json": () => Response.json(openapi),
       "/api/projects": async () => {
         // Lazy load cache on first request
         if (!cachedPlans) {
@@ -328,7 +458,9 @@ async function startServer() {
         }
 
         const plans = cachedPlans || [];
-        const projects = [...new Set(plans.map(p => p.project).filter(Boolean))] as string[];
+        const projects = [
+          ...new Set(plans.map((p) => p.project).filter(Boolean)),
+        ] as string[];
         projects.sort((a, b) => a.localeCompare(b));
 
         return Response.json({ projects });
@@ -342,7 +474,7 @@ async function startServer() {
         const plans = cachedPlans || [];
 
         // Strip content from response - will be fetched separately via /api/plans/{id}/content
-        const plansWithoutContent = plans.map(p => ({
+        const plansWithoutContent = plans.map((p) => ({
           filename: p.filename,
           filepath: p.filepath,
           title: p.title,
@@ -376,9 +508,11 @@ async function startServer() {
       },
       "/api/refresh": {
         POST: async () => {
-          invalidateCache();
+          const before = cachedPlans?.length ?? 0;
+          invalidateAllCaches();
           await loadPlans();
-          return Response.json({ success: true });
+          const after = cachedPlans?.length ?? 0;
+          return Response.json({ success: true, before, after });
         },
       },
       "/api/open": {
@@ -396,10 +530,13 @@ async function startServer() {
         },
       },
     },
-    development: process.env.NODE_ENV !== "production" ? {
-      hmr: true,
-      console: true,
-    } : undefined,
+    development:
+      process.env.NODE_ENV !== "production"
+        ? {
+            hmr: true,
+            console: true,
+          }
+        : undefined,
   });
 
   return server;
@@ -420,24 +557,60 @@ const c = {
 (async () => {
   const args = parseCliArgs();
 
+  if (args.version) {
+    console.log(`claude-plan-viewer v${pkg.version}`);
+    process.exit(0);
+  }
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Initialize directory paths based on --claude-dir flag or CLAUDE_DIR env var
+  const claudeDir = resolveClaudeDir(args.claudeDir);
+  initializeDirectories(claudeDir);
+
   if (args.json) {
     await exportPlansAsJson(args.output);
     process.exit(0);
   }
 
-  const server = await startServer();
-  const planCount = (await readdir(PLANS_DIR)).filter(f => f.endsWith('.md')).length;
+  // Pre-load plans from file if --from-file is provided
+  let planCount: number;
+  let sourceDisplay: string;
 
-  // Start watching for file changes (runs in background)
-  watchPlansDirectory();
+  if (args.fromFile) {
+    const plans = await loadPlansFromFile(args.fromFile);
+    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();
+  }
+
+  const server = await startServer();
 
   console.log();
-  console.log(`${c.bold}${c.magenta}  📋 Plans Viewer${c.reset}`);
+  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`);
-  console.log(`${c.green}  ✓${c.reset} Watching for file changes`);
+  if (!args.fromFile) {
+    console.log(`${c.green}  ✓${c.reset} Watching for file changes`);
+  }
   console.log();
-  console.log(`${c.dim}  Local:${c.reset}   ${c.cyan}${c.bold}http://localhost:${server.port}${c.reset}`);
-  console.log(`${c.dim}  Plans:${c.reset}   ${c.yellow}${planCount} plans${c.reset} in ${c.dim}${PLANS_DIR}${c.reset}`);
+  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();
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-viewer",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A web-based viewer for Claude Code plan files",
   "type": "module",
   "bin": {
@@ -8,23 +8,27 @@
   },
   "files": [
     "index.ts",
-    "index.html",
-    "src",
-    "styles.css",
-    "prism.bundle.js"
+    "src"
   ],
   "scripts": {
     "start": "bun index.ts",
     "dev": "bun --hot index.ts",
-    "test": "bun test index.test.ts frontend.test.ts",
+    "test": "bun test test/",
+    "test:api": "bun test test/api.test.ts",
     "test:e2e": "bunx playwright test",
-    "build": "bun build --compile --minify --bytecode ./index.ts --outfile ./dist/plans-viewer",
-    "build:macos-arm64": "bun build --compile --target=bun-darwin-arm64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-macos-arm64",
-    "build:macos-x64": "bun build --compile --target=bun-darwin-x64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-macos-x64",
-    "build:linux-x64": "bun build --compile --target=bun-linux-x64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-linux-x64",
-    "build:linux-arm64": "bun build --compile --target=bun-linux-arm64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-linux-arm64",
-    "build:windows": "bun build --compile --target=bun-windows-x64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-windows.exe",
-    "build:all": "bun run build:macos-arm64 && bun run build:macos-x64 && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:windows"
+    "build": "bun build --compile --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer",
+    "build:macos-arm64": "bun build --compile --target=bun-darwin-arm64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-macos-arm64",
+    "build:macos-x64": "bun build --compile --target=bun-darwin-x64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-macos-x64",
+    "build:linux-x64": "bun build --compile --target=bun-linux-x64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-linux-x64",
+    "build:linux-arm64": "bun build --compile --target=bun-linux-arm64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-linux-arm64",
+    "build:windows": "bun build --compile --target=bun-windows-x64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-windows.exe",
+    "build:all": "bun run build:macos-arm64 && bun run build:macos-x64 && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:windows",
+    "clean": "rm -rf ./dist",
+    "install:link": "bun link",
+    "install:local": "bun scripts/install-local.ts",
+    "uninstall:link": "bun unlink",
+    "uninstall:local": "bun scripts/uninstall-local.ts",
+    "format": "bunx prettier --write src"
   },
   "keywords": [
     "claude",
@@ -49,8 +53,10 @@
   "devDependencies": {
     "@playwright/test": "^1.57.0",
     "@types/bun": "latest",
+    "@types/prismjs": "^1.26.5",
     "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3"
+    "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.13"
   },
   "peerDependencies": {
     "typescript": "^5.9.3"
@@ -58,6 +64,10 @@
   "dependencies": {
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
-    "react-select": "^5.10.2"
+    "react-markdown": "^10.1.0",
+    "react-select": "^5.10.2",
+    "react-syntax-highlighter": "^16.1.0",
+    "remark-gfm": "^4.0.1",
+    "swr": "^2.3.8"
   }
 }

package/src/api-docs.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Plans Viewer API</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      Scalar.createApiReference("#app", {
+        url: "/api/openapi.json",
+      });
+    </script>
+  </body>
+</html>