claude-session-viewer 0.1.1 → 0.2.0

package/README.md

@@ -1,38 +1,73 @@
+<div align="center">
+
+![Screenshot](docs/images/screenshot.png)
+
+</div>
+
 # Claude Session Viewer
 
 A web-based tool to visualize Claude session history from your local `.claude` directory in a timeline format.
 
 ## Getting Started
 
-### Installation
+### Run with npx
 
 ```bash
-npm install
+npx claude-session-viewer
 ```
 
-### Run with npx
+The server will start and automatically open in your default web browser. By default, it uses port 9090, but if that port is unavailable, it will automatically find an available port.
+
+You'll see output like this in your terminal:
+
+```
+Server running on http://localhost:9090
+Watching Claude directory: /Users/username/.claude
+
+Opening browser at http://localhost:9090...
+```
+
+#### Options
+
+You can specify a custom port using the `--port` or `-p` option:
 
 ```bash
-npx .
+npx claude-session-viewer --port 3000
 ```
 
-Or run with the package name:
+When you specify a port, the server will fail if that port is already in use. If you don't specify a port and the default (9090) is unavailable, it will automatically find an available port.
+
+### Development
+
+If you want to modify the source code or run in development mode, first install dependencies:
 
 ```bash
-npx claude-session-viewer
+npm install
 ```
 
-### Run Development Server
+Then run the development server:
 
 ```bash
 npm run dev
 ```
 
 This command runs both:
-- Backend server (http://localhost:3000)
-- Frontend development server (http://localhost:5173)
+- Backend server (default: http://localhost:9090)
+- Frontend development server (default: http://localhost:5173)
 
-Open http://localhost:5173 in your browser.
+The application will automatically open in your default web browser. By default, it uses ports 9090 (backend) and 5173 (frontend), but if those ports are unavailable, it will automatically find available ports.
+
+You'll see output like this in your terminal:
+
+```
+VITE v5.4.21  ready in 149 ms
+  ➜  Local:   http://localhost:5173/
+
+Server running on http://localhost:9090
+Watching Claude directory: /Users/username/.claude
+
+Opening browser at http://localhost:5173...
+```
 
 ### Build
 

package/bin/cli.js

@@ -3,6 +3,10 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import open from "open";
+import getPort from "get-port";
+
+const DEFAULT_PORT = 9090;
 
 const args = process.argv.slice(2);
 
@@ -12,11 +16,12 @@ if (args.includes("--help") || args.includes("-h")) {
       "Claude Session Viewer",
       "",
       "Usage:",
-      "  npx claude-session-viewer",
+      "  npx claude-session-viewer [options]",
       "",
       "Options:",
-      "  -h, --help     Show this help message",
-      "  -v, --version  Show package version",
+      "  -p, --port <port>  Specify port number (default: 9090)",
+      "  -h, --help         Show this help message",
+      "  -v, --version      Show package version",
       "",
     ].join("\n"),
   );
@@ -29,6 +34,19 @@ if (args.includes("--version") || args.includes("-v")) {
   process.exit(0);
 }
 
+// Handle port option
+let port = 0;
+const portIndex = args.findIndex((arg) => arg === "--port" || arg === "-p");
+if (portIndex !== -1 && args[portIndex + 1]) {
+  const userPort = Number(args[portIndex + 1]);
+  if (Number.isFinite(userPort) && userPort > 0 && userPort < 65536) {
+    port = userPort;
+  } else {
+    console.error(`Invalid port number: ${args[portIndex + 1]}`);
+    process.exit(1);
+  }
+}
+
 const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const serverEntry = resolve(rootDir, "dist/server/index.js");
 
@@ -38,11 +56,24 @@ if (!existsSync(serverEntry)) {
   process.exit(1);
 }
 
+// Only use getPort if port was not specified (port === 0)
+if (port === 0) {
+  port = await getPort({ port: DEFAULT_PORT });
+}
+
 const child = spawn(process.execPath, [serverEntry], {
   cwd: rootDir,
   stdio: "inherit",
+  env: { ...process.env, PORT: String(port) },
 });
 
+// Wait for server to start, then open browser
+setTimeout(async () => {
+  const url = `http://localhost:${port}`;
+  console.log(`\nOpening browser at ${url}...`);
+  await open(url);
+}, 1000);
+
 child.on("exit", (code) => {
   if (code !== null) {
     process.exit(code);
@@ -50,6 +81,6 @@ child.on("exit", (code) => {
 });
 
 child.on("error", (error) => {
-  console.error("Failed to start dev servers:", error.message);
+  console.error("Failed to start server:", error.message);
   process.exit(1);
 });

package/bin/dev.js

@@ -3,12 +3,15 @@ import { spawn } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import getPort from "get-port";
+import open from "open";
+
+const DEFAULT_SERVER_PORT = 9090;
+const DEFAULT_CLIENT_PORT = 5173;
 
 const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-
-const DEFAULT_PORT = 9090;
-const port = await getPort({ port: DEFAULT_PORT });
+const serverPort = await getPort({ port: DEFAULT_SERVER_PORT });
+const clientPort = await getPort({ port: DEFAULT_CLIENT_PORT });
 
 const children = new Set();
 
@@ -25,8 +28,18 @@ function spawnProcess(args, envOverrides) {
   return child;
 }
 
-spawnProcess(["run", "dev:server"], { PORT: String(port) });
-spawnProcess(["run", "dev:client"], { VITE_API_PORT: String(port) });
+spawnProcess(["run", "dev:server"], { PORT: String(serverPort) });
+spawnProcess(["run", "dev:client"], {
+  VITE_SERVER_PORT: String(serverPort),
+  VITE_CLIENT_PORT: String(clientPort),
+});
+
+// Wait for Vite to start, then open browser
+setTimeout(async () => {
+  const url = `http://localhost:${clientPort}`;
+  console.log(`\nOpening browser at ${url}...`);
+  await open(url);
+}, 1000);
 
 function shutdown(signal) {
   for (const child of children) {