@teddysc/claude-run 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamran Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+<div align="center">
+
+# Claude Run
+
+Browse your Claude Code conversation history in a beautiful web UI
+
+[![npm version](https://img.shields.io/npm/v/claude-run.svg)](https://www.npmjs.com/package/claude-run)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+<img src=".github/claude-run.gif" alt="Claude Run Demo" width="800" />
+
+</div>
+
+<br />
+
+Run the project simply by executing
+
+```bash
+npx claude-run
+```
+
+The browser will open automatically at http://localhost:12001.
+
+## Features
+
+- **Real-time streaming** - Watch conversations update live as Claude responds
+- **Search** - Find sessions by prompt text or project name
+- **Filter by project** - Focus on specific projects
+- **Resume sessions** - Copy the resume command to continue any conversation in your terminal
+- **Collapsible sidebar** - Maximize your viewing area
+- **Dark mode** - Easy on the eyes
+- **Clean UI** - Familiar chat interface with collapsible tool calls
+
+## Usage
+
+Install globally via npm:
+
+```bash
+npm install -g claude-run
+```
+
+Then run it from any directory:
+
+```bash
+claude-run
+```
+
+The browser will open automatically at http://localhost:12001, showing all your Claude Code conversations.
+
+```bash
+claude-run [options]
+
+Options:
+  -V, --version        Show version number
+  -p, --port <number>  Port to listen on (default: 12001)
+  -d, --dir <path>     Claude directory (default: ~/.claude)
+  --no-open            Do not open browser automatically
+  -h, --help           Show help
+```
+
+## How It Works
+
+Claude Code stores conversation history in `~/.claude/`. This tool reads that data and presents it in a web interface with:
+
+- **Session list** - All your conversations, sorted by recency
+- **Project filter** - Focus on a specific project
+- **Conversation view** - Full message history with tool calls
+- **Session header** - Shows conversation title, project name, and timestamp
+- **Resume command** - Copies the command to resume the conversation
+- **Real-time updates** - SSE streaming for live conversations
+
+## Requirements
+
+- Node.js 20+
+- Claude Code installed and used at least once
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/kamranahmedse/claude-run.git
+cd claude-run
+
+# Install dependencies
+pnpm install
+
+# Start development servers
+pnpm dev
+
+# Build for production
+pnpm build
+```
+
+## License
+
+MIT © Kamran Ahmed

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,596 @@
+#!/usr/bin/env node
+
+// api/index.ts
+import { program } from "commander";
+
+// api/server.ts
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { streamSSE } from "hono/streaming";
+import { serve } from "@hono/node-server";
+
+// api/storage.ts
+import { readdir, readFile, stat, open } from "fs/promises";
+import { join, basename } from "path";
+import { homedir } from "os";
+import { createInterface } from "readline";
+var claudeDir = join(homedir(), ".claude");
+var projectsDir = join(claudeDir, "projects");
+var fileIndex = /* @__PURE__ */ new Map();
+var historyCache = null;
+var pendingRequests = /* @__PURE__ */ new Map();
+function initStorage(dir) {
+  claudeDir = dir ?? join(homedir(), ".claude");
+  projectsDir = join(claudeDir, "projects");
+}
+function getClaudeDir() {
+  return claudeDir;
+}
+function invalidateHistoryCache() {
+  historyCache = null;
+}
+function addToFileIndex(sessionId, filePath) {
+  fileIndex.set(sessionId, filePath);
+}
+function encodeProjectPath(path) {
+  return path.replace(/[/.]/g, "-");
+}
+function getProjectName(projectPath) {
+  const parts = projectPath.split("/").filter(Boolean);
+  return parts[parts.length - 1] || projectPath;
+}
+async function buildFileIndex() {
+  try {
+    const projectDirs = await readdir(projectsDir, { withFileTypes: true });
+    const directories = projectDirs.filter((d) => d.isDirectory());
+    await Promise.all(
+      directories.map(async (dir) => {
+        try {
+          const projectPath = join(projectsDir, dir.name);
+          const files = await readdir(projectPath);
+          for (const file of files) {
+            if (file.endsWith(".jsonl")) {
+              const sessionId = basename(file, ".jsonl");
+              fileIndex.set(sessionId, join(projectPath, file));
+            }
+          }
+        } catch {
+        }
+      })
+    );
+  } catch {
+  }
+}
+async function loadHistoryCache() {
+  try {
+    const historyPath = join(claudeDir, "history.jsonl");
+    const content = await readFile(historyPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+      }
+    }
+    historyCache = entries;
+    return entries;
+  } catch {
+    historyCache = [];
+    return [];
+  }
+}
+async function dedupe(key, fn) {
+  const existing = pendingRequests.get(key);
+  if (existing) {
+    return existing;
+  }
+  const promise = fn().finally(() => {
+    pendingRequests.delete(key);
+  });
+  pendingRequests.set(key, promise);
+  return promise;
+}
+async function findSessionByTimestamp(encodedProject, timestamp) {
+  try {
+    const projectPath = join(projectsDir, encodedProject);
+    const files = await readdir(projectPath);
+    const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
+    const fileStats = await Promise.all(
+      jsonlFiles.map(async (file) => {
+        const filePath = join(projectPath, file);
+        const fileStat = await stat(filePath);
+        return { file, mtime: fileStat.mtimeMs };
+      })
+    );
+    let closestFile = null;
+    let closestTimeDiff = Infinity;
+    for (const { file, mtime } of fileStats) {
+      const timeDiff = Math.abs(mtime - timestamp);
+      if (timeDiff < closestTimeDiff) {
+        closestTimeDiff = timeDiff;
+        closestFile = file;
+      }
+    }
+    if (closestFile) {
+      return basename(closestFile, ".jsonl");
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function findSessionFile(sessionId) {
+  if (fileIndex.has(sessionId)) {
+    return fileIndex.get(sessionId);
+  }
+  const targetFile = `${sessionId}.jsonl`;
+  try {
+    const projectDirs = await readdir(projectsDir, { withFileTypes: true });
+    const directories = projectDirs.filter((d) => d.isDirectory());
+    const results = await Promise.all(
+      directories.map(async (dir) => {
+        try {
+          const projectPath = join(projectsDir, dir.name);
+          const files = await readdir(projectPath);
+          if (files.includes(targetFile)) {
+            return join(projectPath, targetFile);
+          }
+        } catch {
+        }
+        return null;
+      })
+    );
+    const filePath = results.find((r) => r !== null);
+    if (filePath) {
+      fileIndex.set(sessionId, filePath);
+      return filePath;
+    }
+  } catch (err) {
+    console.error("Error finding session file:", err);
+  }
+  return null;
+}
+async function loadStorage() {
+  await Promise.all([buildFileIndex(), loadHistoryCache()]);
+}
+async function getSessions() {
+  return dedupe("getSessions", async () => {
+    const entries = historyCache ?? await loadHistoryCache();
+    const sessions = [];
+    const seenIds = /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      let sessionId = entry.sessionId;
+      if (!sessionId) {
+        const encodedProject = encodeProjectPath(entry.project);
+        sessionId = await findSessionByTimestamp(encodedProject, entry.timestamp);
+      }
+      if (!sessionId || seenIds.has(sessionId)) {
+        continue;
+      }
+      seenIds.add(sessionId);
+      sessions.push({
+        id: sessionId,
+        display: entry.display,
+        timestamp: entry.timestamp,
+        project: entry.project,
+        projectName: getProjectName(entry.project)
+      });
+    }
+    return sessions.sort((a, b) => b.timestamp - a.timestamp);
+  });
+}
+async function getProjects() {
+  const entries = historyCache ?? await loadHistoryCache();
+  const projects = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (entry.project) {
+      projects.add(entry.project);
+    }
+  }
+  return [...projects].sort();
+}
+async function getConversation(sessionId) {
+  return dedupe(`getConversation:${sessionId}`, async () => {
+    const filePath = await findSessionFile(sessionId);
+    if (!filePath) {
+      return [];
+    }
+    const messages = [];
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const lines = content.trim().split("\n").filter(Boolean);
+      for (const line of lines) {
+        try {
+          const msg = JSON.parse(line);
+          if (msg.type === "user" || msg.type === "assistant") {
+            messages.push(msg);
+          } else if (msg.type === "summary") {
+            messages.unshift(msg);
+          }
+        } catch {
+        }
+      }
+    } catch (err) {
+      console.error("Error reading conversation:", err);
+    }
+    return messages;
+  });
+}
+async function getConversationStream(sessionId, fromOffset = 0) {
+  const filePath = await findSessionFile(sessionId);
+  if (!filePath) {
+    return { messages: [], nextOffset: 0 };
+  }
+  const messages = [];
+  let fileHandle;
+  try {
+    const fileStat = await stat(filePath);
+    const fileSize = fileStat.size;
+    if (fromOffset >= fileSize) {
+      return { messages: [], nextOffset: fromOffset };
+    }
+    fileHandle = await open(filePath, "r");
+    const stream = fileHandle.createReadStream({
+      start: fromOffset,
+      encoding: "utf-8"
+    });
+    const rl = createInterface({
+      input: stream,
+      crlfDelay: Infinity
+    });
+    let bytesConsumed = 0;
+    for await (const line of rl) {
+      const lineBytes = Buffer.byteLength(line, "utf-8") + 1;
+      if (line.trim()) {
+        try {
+          const msg = JSON.parse(line);
+          if (msg.type === "user" || msg.type === "assistant") {
+            messages.push(msg);
+          }
+          bytesConsumed += lineBytes;
+        } catch {
+          break;
+        }
+      } else {
+        bytesConsumed += lineBytes;
+      }
+    }
+    const actualOffset = fromOffset + bytesConsumed;
+    const nextOffset = actualOffset > fileSize ? fileSize : actualOffset;
+    return { messages, nextOffset };
+  } catch (err) {
+    console.error("Error reading conversation stream:", err);
+    return { messages: [], nextOffset: fromOffset };
+  } finally {
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}
+
+// api/watcher.ts
+import { watch } from "chokidar";
+import { basename as basename2, join as join2 } from "path";
+var watcher = null;
+var claudeDir2 = "";
+var debounceTimers = /* @__PURE__ */ new Map();
+var debounceMs = 20;
+var historyChangeListeners = /* @__PURE__ */ new Set();
+var sessionChangeListeners = /* @__PURE__ */ new Set();
+function initWatcher(dir) {
+  claudeDir2 = dir;
+}
+function emitChange(filePath) {
+  if (filePath.endsWith("history.jsonl")) {
+    for (const callback of historyChangeListeners) {
+      callback();
+    }
+  } else if (filePath.endsWith(".jsonl")) {
+    const sessionId = basename2(filePath, ".jsonl");
+    for (const callback of sessionChangeListeners) {
+      callback(sessionId, filePath);
+    }
+  }
+}
+function handleChange(path) {
+  const existing = debounceTimers.get(path);
+  if (existing) {
+    clearTimeout(existing);
+  }
+  const timer = setTimeout(() => {
+    debounceTimers.delete(path);
+    emitChange(path);
+  }, debounceMs);
+  debounceTimers.set(path, timer);
+}
+function startWatcher() {
+  if (watcher) {
+    return;
+  }
+  const historyPath = join2(claudeDir2, "history.jsonl");
+  const projectsDir2 = join2(claudeDir2, "projects");
+  const usePolling = process.env.CLAUDE_RUN_USE_POLLING === "1";
+  watcher = watch([historyPath, projectsDir2], {
+    persistent: true,
+    ignoreInitial: true,
+    usePolling,
+    ...usePolling && { interval: 100 },
+    depth: 2
+  });
+  watcher.on("change", handleChange);
+  watcher.on("add", handleChange);
+  watcher.on("error", (error) => {
+    console.error("Watcher error:", error);
+  });
+}
+function stopWatcher() {
+  if (watcher) {
+    watcher.close();
+    watcher = null;
+  }
+  for (const timer of debounceTimers.values()) {
+    clearTimeout(timer);
+  }
+  debounceTimers.clear();
+}
+function onHistoryChange(callback) {
+  historyChangeListeners.add(callback);
+}
+function offHistoryChange(callback) {
+  historyChangeListeners.delete(callback);
+}
+function onSessionChange(callback) {
+  sessionChangeListeners.add(callback);
+}
+function offSessionChange(callback) {
+  sessionChangeListeners.delete(callback);
+}
+
+// api/server.ts
+import { join as join3, dirname } from "path";
+import { fileURLToPath } from "url";
+import { readFileSync, existsSync } from "fs";
+import open2 from "open";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+function getWebDistPath() {
+  const prodPath = join3(__dirname, "web");
+  if (existsSync(prodPath)) {
+    return prodPath;
+  }
+  return join3(__dirname, "..", "dist", "web");
+}
+function createServer(options) {
+  const {
+    port,
+    host = "127.0.0.1",
+    claudeDir: claudeDir3,
+    dev = false,
+    open: shouldOpen = true
+  } = options;
+  initStorage(claudeDir3);
+  initWatcher(getClaudeDir());
+  const app = new Hono();
+  if (dev) {
+    app.use(
+      "*",
+      cors({
+        origin: ["http://localhost:12000"],
+        allowMethods: ["GET", "POST", "OPTIONS"],
+        allowHeaders: ["Content-Type"]
+      })
+    );
+  }
+  app.get("/api/sessions", async (c) => {
+    const sessions = await getSessions();
+    return c.json(sessions);
+  });
+  app.get("/api/projects", async (c) => {
+    const projects = await getProjects();
+    return c.json(projects);
+  });
+  app.get("/api/sessions/stream", async (c) => {
+    return streamSSE(c, async (stream) => {
+      let isConnected = true;
+      const knownSessions = /* @__PURE__ */ new Map();
+      const cleanup = () => {
+        isConnected = false;
+        offHistoryChange(handleHistoryChange);
+      };
+      const handleHistoryChange = async () => {
+        if (!isConnected) {
+          return;
+        }
+        try {
+          const sessions = await getSessions();
+          const newOrUpdated = sessions.filter((s) => {
+            const known = knownSessions.get(s.id);
+            return known === void 0 || known !== s.timestamp;
+          });
+          for (const s of sessions) {
+            knownSessions.set(s.id, s.timestamp);
+          }
+          if (newOrUpdated.length > 0) {
+            await stream.writeSSE({
+              event: "sessionsUpdate",
+              data: JSON.stringify(newOrUpdated)
+            });
+          }
+        } catch {
+          cleanup();
+        }
+      };
+      onHistoryChange(handleHistoryChange);
+      c.req.raw.signal.addEventListener("abort", cleanup);
+      try {
+        const sessions = await getSessions();
+        for (const s of sessions) {
+          knownSessions.set(s.id, s.timestamp);
+        }
+        await stream.writeSSE({
+          event: "sessions",
+          data: JSON.stringify(sessions)
+        });
+        while (isConnected) {
+          await stream.writeSSE({
+            event: "heartbeat",
+            data: JSON.stringify({ timestamp: Date.now() })
+          });
+          await stream.sleep(3e4);
+        }
+      } catch {
+      } finally {
+        cleanup();
+      }
+    });
+  });
+  app.get("/api/conversation/:id", async (c) => {
+    const sessionId = c.req.param("id");
+    const messages = await getConversation(sessionId);
+    return c.json(messages);
+  });
+  app.get("/api/conversation/:id/stream", async (c) => {
+    const sessionId = c.req.param("id");
+    const offsetParam = c.req.query("offset");
+    let offset = offsetParam ? parseInt(offsetParam, 10) : 0;
+    return streamSSE(c, async (stream) => {
+      let isConnected = true;
+      const cleanup = () => {
+        isConnected = false;
+        offSessionChange(handleSessionChange);
+      };
+      const handleSessionChange = async (changedSessionId) => {
+        if (changedSessionId !== sessionId || !isConnected) {
+          return;
+        }
+        const { messages: newMessages, nextOffset: newOffset } = await getConversationStream(sessionId, offset);
+        offset = newOffset;
+        if (newMessages.length > 0) {
+          try {
+            await stream.writeSSE({
+              event: "messages",
+              data: JSON.stringify(newMessages)
+            });
+          } catch {
+            cleanup();
+          }
+        }
+      };
+      onSessionChange(handleSessionChange);
+      c.req.raw.signal.addEventListener("abort", cleanup);
+      try {
+        const { messages, nextOffset } = await getConversationStream(
+          sessionId,
+          offset
+        );
+        offset = nextOffset;
+        await stream.writeSSE({
+          event: "messages",
+          data: JSON.stringify(messages)
+        });
+        while (isConnected) {
+          await stream.writeSSE({
+            event: "heartbeat",
+            data: JSON.stringify({ timestamp: Date.now() })
+          });
+          await stream.sleep(3e4);
+        }
+      } catch {
+      } finally {
+        cleanup();
+      }
+    });
+  });
+  const webDistPath = getWebDistPath();
+  app.use("/*", serveStatic({ root: webDistPath }));
+  app.get("/*", async (c) => {
+    const indexPath = join3(webDistPath, "index.html");
+    try {
+      const html = readFileSync(indexPath, "utf-8");
+      return c.html(html);
+    } catch {
+      return c.text("UI not found. Run 'pnpm build' first.", 404);
+    }
+  });
+  onHistoryChange(() => {
+    invalidateHistoryCache();
+  });
+  onSessionChange((sessionId, filePath) => {
+    addToFileIndex(sessionId, filePath);
+  });
+  startWatcher();
+  let httpServer = null;
+  return {
+    app,
+    port,
+    start: async () => {
+      await loadStorage();
+      const openUrl = `http://${host}:${dev ? 12e3 : port}/`;
+      console.log(`
+  claude-run is running at ${openUrl}
+`);
+      if (!dev && shouldOpen) {
+        open2(openUrl).catch(console.error);
+      }
+      httpServer = serve({
+        fetch: app.fetch,
+        port,
+        hostname: host
+      });
+      return httpServer;
+    },
+    stop: () => {
+      stopWatcher();
+      if (httpServer) {
+        httpServer.close();
+      }
+    }
+  };
+}
+
+// api/index.ts
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2 } from "path";
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename2);
+function getVersion() {
+  try {
+    const pkgPath = join4(__dirname2, "..", "package.json");
+    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+    return pkg.version;
+  } catch {
+    return "0.1.0";
+  }
+}
+program.name("claude-run").description(
+  "A beautiful web UI for browsing Claude Code conversation history"
+).version(getVersion()).option("-p, --port <number>", "Port to listen on", "12001").option("-H, --host <address>", "Host address to listen on", "127.0.0.1").option(
+  "-d, --dir <path>",
+  "Claude directory path",
+  join4(homedir2(), ".claude")
+).option("--dev", "Enable CORS for development").option("--no-open", "Do not open browser automatically").parse();
+var opts = program.opts();
+var server = createServer({
+  port: parseInt(opts.port, 10),
+  host: opts.host,
+  claudeDir: opts.dir,
+  dev: opts.dev,
+  open: opts.open
+});
+process.on("SIGINT", () => {
+  console.log("\nShutting down...");
+  server.stop();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  server.stop();
+  process.exit(0);
+});
+server.start().catch((err) => {
+  console.error("Failed to start server:", err);
+  process.exit(1);
+});