@atercates/claude-deck 0.2.15 → 0.2.16

package/app/api/tunnels/[port]/route.ts

@@ -0,0 +1,57 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isCloudflaredInstalled, startTunnel, stopTunnel } from "@/lib/tunnels";
+
+export async function POST(
+  _request: NextRequest,
+  { params }: { params: Promise<{ port: string }> }
+) {
+  try {
+    const { port: portStr } = await params;
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port <= 0) {
+      return NextResponse.json({ error: "Invalid port" }, { status: 400 });
+    }
+
+    const installed = await isCloudflaredInstalled();
+    if (!installed) {
+      return NextResponse.json(
+        {
+          error: "cloudflared is not installed",
+          code: "CLOUDFLARED_NOT_FOUND",
+        },
+        { status: 400 }
+      );
+    }
+
+    const result = await startTunnel(port);
+    return NextResponse.json(result);
+  } catch (error) {
+    console.error("Error starting tunnel:", error);
+    return NextResponse.json(
+      { error: "Failed to start tunnel" },
+      { status: 500 }
+    );
+  }
+}
+
+export async function DELETE(
+  _request: NextRequest,
+  { params }: { params: Promise<{ port: string }> }
+) {
+  try {
+    const { port: portStr } = await params;
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port <= 0) {
+      return NextResponse.json({ error: "Invalid port" }, { status: 400 });
+    }
+
+    await stopTunnel(port);
+    return NextResponse.json({ ok: true });
+  } catch (error) {
+    console.error("Error stopping tunnel:", error);
+    return NextResponse.json(
+      { error: "Failed to stop tunnel" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/tunnels/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from "next/server";
+import { isCloudflaredInstalled, getTunnelsList } from "@/lib/tunnels";
+
+export async function GET() {
+  try {
+    const [installed, tunnels] = await Promise.all([
+      isCloudflaredInstalled(),
+      Promise.resolve(getTunnelsList()),
+    ]);
+    return NextResponse.json({ installed, tunnels });
+  } catch (error) {
+    console.error("Error getting tunnels:", error);
+    return NextResponse.json(
+      { error: "Failed to get tunnels" },
+      { status: 500 }
+    );
+  }
+}

package/components/SessionList/ActiveSessionsSection.tsx

@@ -1,9 +1,25 @@
 "use client";
 
-import { useMemo, useState, useEffect } from "react";
+import { useMemo, useState, useEffect, useCallback } from "react";
 import { cn } from "@/lib/utils";
-import { ChevronRight, Activity, AlertCircle, Moon } from "lucide-react";
+import {
+  ChevronRight,
+  Activity,
+  AlertCircle,
+  Moon,
+  Globe,
+  Share2,
+  X,
+  Loader2,
+  Copy,
+  Check,
+} from "lucide-react";
 import type { SessionStatus } from "@/components/views/types";
+import {
+  useCloudflaredStatus,
+  useStartTunnel,
+  useStopTunnel,
+} from "@/data/tunnels/queries";
 
 interface ActiveSessionsSectionProps {
   sessionStatuses: Record<string, SessionStatus>;
@@ -37,11 +53,13 @@ export function ActiveSessionsSection({
   const hasWaiting = activeSessions.some((s) => s.status === "waiting");
   const [expanded, setExpanded] = useState(hasWaiting);
 
-  // Auto-expand when a session starts waiting
   useEffect(() => {
     if (hasWaiting) setExpanded(true);
   }, [hasWaiting]);
 
+  const { data: cfStatus } = useCloudflaredStatus();
+  const cloudflaredInstalled = cfStatus?.installed ?? false;
+
   if (activeSessions.length === 0) return null;
 
   return (
@@ -92,6 +110,19 @@ export function ActiveSessionsSection({
                     {session.lastLine}
                   </span>
                 )}
+                {session.listeningPorts &&
+                  session.listeningPorts.length > 0 && (
+                    <div className="mt-0.5 space-y-0.5">
+                      {session.listeningPorts.map((port) => (
+                        <PortBadge
+                          key={port}
+                          port={port}
+                          tunnelUrl={session.tunnelUrls?.[port]}
+                          cloudflaredInstalled={cloudflaredInstalled}
+                        />
+                      ))}
+                    </div>
+                  )}
               </div>
             </button>
           ))}
@@ -101,6 +132,112 @@ export function ActiveSessionsSection({
   );
 }
 
+function PortBadge({
+  port,
+  tunnelUrl,
+  cloudflaredInstalled,
+}: {
+  port: number;
+  tunnelUrl?: string;
+  cloudflaredInstalled: boolean;
+}) {
+  const startTunnel = useStartTunnel();
+  const stopTunnel = useStopTunnel();
+  const [copied, setCopied] = useState(false);
+
+  const isStarting = startTunnel.isPending;
+  const hasTunnel = !!tunnelUrl;
+
+  const handleShare = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      if (hasTunnel) {
+        stopTunnel.mutate(port);
+      } else {
+        startTunnel.mutate(port);
+      }
+    },
+    [hasTunnel, port, startTunnel, stopTunnel]
+  );
+
+  const handleCopy = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      if (tunnelUrl) {
+        navigator.clipboard.writeText(tunnelUrl);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      }
+    },
+    [tunnelUrl]
+  );
+
+  return (
+    <div className="flex flex-col gap-0.5">
+      <div className="flex items-center gap-1">
+        <a
+          href={`http://localhost:${port}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          onClick={(e) => e.stopPropagation()}
+          className="inline-flex items-center gap-0.5 rounded bg-sky-500/15 px-1.5 py-0.5 font-mono text-[10px] text-sky-400 transition-colors hover:bg-sky-500/25"
+        >
+          <Globe className="h-2.5 w-2.5" />
+          {port}
+        </a>
+        {cloudflaredInstalled && (
+          <button
+            onClick={handleShare}
+            disabled={isStarting}
+            className={cn(
+              "rounded p-0.5 transition-colors",
+              hasTunnel
+                ? "text-emerald-400 hover:bg-emerald-500/20"
+                : "text-muted-foreground hover:bg-muted hover:text-foreground"
+            )}
+            title={hasTunnel ? "Stop sharing" : "Share via tunnel"}
+          >
+            {isStarting ? (
+              <Loader2 className="h-3 w-3 animate-spin" />
+            ) : hasTunnel ? (
+              <X className="h-3 w-3" />
+            ) : (
+              <Share2 className="h-3 w-3" />
+            )}
+          </button>
+        )}
+      </div>
+      {tunnelUrl && (
+        <div className="flex items-center gap-1">
+          <a
+            href={tunnelUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            onClick={(e) => e.stopPropagation()}
+            className="inline-flex max-w-[180px] items-center gap-0.5 truncate rounded bg-emerald-500/15 px-1.5 py-0.5 font-mono text-[10px] text-emerald-400 transition-colors hover:bg-emerald-500/25"
+          >
+            <Globe className="h-2.5 w-2.5 flex-shrink-0" />
+            {tunnelUrl
+              .replace("https://", "")
+              .replace(".trycloudflare.com", "")}
+          </a>
+          <button
+            onClick={handleCopy}
+            className="text-muted-foreground hover:text-foreground rounded p-0.5 transition-colors"
+            title="Copy URL"
+          >
+            {copied ? (
+              <Check className="h-3 w-3 text-emerald-400" />
+            ) : (
+              <Copy className="h-3 w-3" />
+            )}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
 function StatusIcon({ status }: { status: string }) {
   if (status === "running") {
     return (

package/components/Terminal/hooks/websocket-connection.ts

@@ -34,7 +34,14 @@ export function createWebSocketConnection(
   intentionalCloseRef: React.MutableRefObject<boolean>
 ): WebSocketManager {
   const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-  const ws = new WebSocket(`${protocol}//${window.location.host}/ws/terminal`);
+  let ptyId: string | null = null;
+
+  function buildWsUrl() {
+    const base = `${protocol}//${window.location.host}/ws/terminal`;
+    return ptyId ? `${base}?ptyId=${ptyId}` : base;
+  }
+
+  const ws = new WebSocket(buildWsUrl());
   wsRef.current = ws;
 
   const sendResize = (cols: number, rows: number) => {
@@ -93,10 +100,11 @@ export function createWebSocketConnection(
     callbacks.onConnectionStateChange("reconnecting");
     reconnectDelayRef.current = WS_RECONNECT_BASE_DELAY;
 
-    // Create fresh connection with saved handlers
-    const newWs = new WebSocket(
-      `${protocol}//${window.location.host}/ws/terminal`
-    );
+    // Reattach to the same PTY if we have an ID
+    if (ptyId) {
+      term.clear();
+    }
+    const newWs = new WebSocket(buildWsUrl());
     wsRef.current = newWs;
     newWs.onopen = savedHandlers.onopen;
     newWs.onmessage = savedHandlers.onmessage;
@@ -135,6 +143,10 @@ export function createWebSocketConnection(
     resetInactivityTimer();
     try {
       const msg = JSON.parse(event.data);
+      if (msg.type === "pty-id") {
+        ptyId = msg.ptyId;
+        return;
+      }
       if (msg.type === "output") {
         const buffer = term.buffer.active;
         const scrollYBefore = buffer.viewportY;

package/components/views/types.ts

@@ -10,6 +10,8 @@ export interface SessionStatus {
   lastLine?: string;
   waitingContext?: string;
   claudeSessionId?: string | null;
+  listeningPorts?: number[];
+  tunnelUrls?: Record<number, string>;
 }
 
 export interface ViewProps {

package/data/tunnels/queries.ts

@@ -0,0 +1,51 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+const tunnelKeys = {
+  status: () => ["tunnels", "status"] as const,
+};
+
+export function useCloudflaredStatus() {
+  return useQuery({
+    queryKey: tunnelKeys.status(),
+    queryFn: async () => {
+      const res = await fetch("/api/tunnels");
+      if (!res.ok) return { installed: false, tunnels: [] };
+      return res.json() as Promise<{
+        installed: boolean;
+        tunnels: { port: number; url: string | null }[];
+      }>;
+    },
+    staleTime: 60_000,
+  });
+}
+
+export function useStartTunnel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (port: number) => {
+      const res = await fetch(`/api/tunnels/${port}`, { method: "POST" });
+      if (!res.ok) {
+        const data = await res.json();
+        throw new Error(data.error || "Failed to start tunnel");
+      }
+      return res.json() as Promise<{ port: number; url: string | null }>;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: tunnelKeys.status() });
+    },
+  });
+}
+
+export function useStopTunnel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (port: number) => {
+      const res = await fetch(`/api/tunnels/${port}`, { method: "DELETE" });
+      if (!res.ok) throw new Error("Failed to stop tunnel");
+      return res.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: tunnelKeys.status() });
+    },
+  });
+}

package/lib/claude/watcher.ts

@@ -3,7 +3,11 @@ import path from "path";
 import os from "os";
 import { WebSocket } from "ws";
 import { invalidateProject, invalidateAll } from "./jsonl-cache";
-import { onStateFileChange, invalidateSessionName } from "../status-monitor";
+import {
+  onStateFileChange,
+  invalidateSessionName,
+  getStatusSnapshot,
+} from "../status-monitor";
 import { STATES_DIR } from "../hooks/setup";
 
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
@@ -13,6 +17,11 @@ const updateClients = new Set<WebSocket>();
 export function addUpdateClient(ws: WebSocket): void {
   updateClients.add(ws);
   ws.on("close", () => updateClients.delete(ws));
+
+  const snapshot = getStatusSnapshot();
+  if (Object.keys(snapshot).length > 0) {
+    ws.send(JSON.stringify({ type: "session-statuses", statuses: snapshot }));
+  }
 }
 
 export function broadcast(msg: object): void {

package/lib/db/migrations.ts

@@ -6,7 +6,17 @@ interface Migration {
   up: (db: Database.Database) => void;
 }
 
-const migrations: Migration[] = [];
+const migrations: Migration[] = [
+  {
+    id: 1,
+    name: "add_session_listening_ports",
+    up: (db) => {
+      db.exec(
+        "ALTER TABLE sessions ADD COLUMN listening_ports TEXT NOT NULL DEFAULT '[]'"
+      );
+    },
+  },
+];
 
 export function runMigrations(db: Database.Database): void {
   db.exec(`

package/lib/db/types.ts

@@ -29,6 +29,7 @@ export interface Session {
   conductor_session_id: string | null;
   worker_task: string | null;
   worker_status: "pending" | "running" | "completed" | "failed" | null;
+  listening_ports: string;
 }
 
 export interface Project {

package/lib/dev-servers.ts

@@ -2,7 +2,12 @@ import { spawn, exec } from "child_process";
 import { promisify } from "util";
 import fs from "fs";
 import path from "path";
-import { queries, type DevServer, type DevServerType, type DevServerStatus } from "./db";
+import {
+  queries,
+  type DevServer,
+  type DevServerType,
+  type DevServerStatus,
+} from "./db";
 
 const execAsync = promisify(exec);
 
@@ -49,53 +54,60 @@ async function isPidRunning(pid: number): Promise<boolean> {
   }
 }
 
-// Check if a port is in use
-async function isPortInUse(port: number): Promise<boolean> {
-  try {
-    const { stdout } = await execAsync(
-      `lsof -i :${port} -t 2>/dev/null || true`
-    );
-    return stdout.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-// Get PID using a port
-async function getPidOnPort(port: number): Promise<number | null> {
-  try {
-    const { stdout } = await execAsync(
-      `lsof -i :${port} -t 2>/dev/null | head -1`
-    );
-    const pid = parseInt(stdout.trim(), 10);
-    return isNaN(pid) ? null : pid;
-  } catch {
-    return null;
+// Detect which TCP ports a process is listening on via lsof
+async function detectListeningPorts(
+  pid: number,
+  retries = 5
+): Promise<number[]> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const { stdout } = await execAsync(
+        `lsof -P -iTCP -sTCP:LISTEN -a -p ${pid} -Fn 2>/dev/null || true`
+      );
+      const ports = [
+        ...new Set(
+          stdout
+            .split("\n")
+            .filter((line) => line.startsWith("n"))
+            .map((line) => parseInt(line.slice(line.lastIndexOf(":") + 1), 10))
+            .filter((port) => !isNaN(port) && port > 0)
+        ),
+      ].sort((a, b) => a - b);
+
+      if (ports.length > 0) return ports;
+    } catch {
+      // lsof failed, retry
+    }
+    if (i < retries - 1) {
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
   }
+  return [];
 }
 
 // Check Node.js server status
 async function checkNodeStatus(server: DevServer): Promise<DevServerStatus> {
-  if (server.pid) {
-    const running = await isPidRunning(server.pid);
-    if (running) return "running";
-  }
+  if (!server.pid) return "stopped";
 
-  // Check if any of its ports are in use
-  const ports: number[] = JSON.parse(server.ports || "[]");
-  for (const port of ports) {
-    if (await isPortInUse(port)) {
-      // Port is in use, try to get the PID
-      const pid = await getPidOnPort(port);
-      if (pid) {
-        // Update PID in database
-        await queries.updateDevServerPid(pid, "running", server.id);
-        return "running";
-      }
+  const running = await isPidRunning(server.pid);
+  if (!running) return "stopped";
+
+  const ports = await detectListeningPorts(server.pid, 1);
+  if (ports.length > 0) {
+    const current = JSON.stringify(ports);
+    if (current !== server.ports) {
+      await queries.updateDevServer(
+        "running",
+        server.pid,
+        null,
+        current,
+        server.id
+      );
+      server.ports = current;
     }
   }
 
-  return "stopped";
+  return "running";
 }
 
 // Check Docker service status
@@ -269,7 +281,13 @@ export async function startServer(
         opts.command,
         opts.workingDirectory
       );
-      await queries.updateDevServer("running", null, containerId, JSON.stringify(ports), id);
+      await queries.updateDevServer(
+        "running",
+        null,
+        containerId,
+        JSON.stringify(ports),
+        id
+      );
     } else {
       const { pid } = await spawnNodeServer(
         id,
@@ -277,7 +295,15 @@ export async function startServer(
         opts.workingDirectory,
         ports
       );
-      await queries.updateDevServer("running", pid, null, JSON.stringify(ports), id);
+      const detectedPorts = await detectListeningPorts(pid);
+      const resolvedPorts = detectedPorts.length > 0 ? detectedPorts : ports;
+      await queries.updateDevServer(
+        "running",
+        pid,
+        null,
+        JSON.stringify(resolvedPorts),
+        id
+      );
     }
   } catch (error) {
     await queries.updateDevServerStatus("failed", id);
@@ -314,19 +340,6 @@ export async function stopServer(id: string): Promise<void> {
         // Process may already be dead
       }
     }
-
-    // Also check ports and kill anything on them
-    const ports: number[] = JSON.parse(server.ports || "[]");
-    for (const port of ports) {
-      const pid = await getPidOnPort(port);
-      if (pid) {
-        try {
-          process.kill(pid, "SIGTERM");
-        } catch {
-          // Ignore
-        }
-      }
-    }
   }
 
   await queries.updateDevServerStatus("stopped", id);
@@ -345,7 +358,13 @@ export async function restartServer(id: string): Promise<DevServer> {
       server.command,
       server.working_directory
     );
-    await queries.updateDevServer("running", null, containerId, server.ports, id);
+    await queries.updateDevServer(
+      "running",
+      null,
+      containerId,
+      server.ports,
+      id
+    );
   } else {
     const ports: number[] = JSON.parse(server.ports || "[]");
     const { pid } = await spawnNodeServer(
@@ -354,7 +373,15 @@ export async function restartServer(id: string): Promise<DevServer> {
       server.working_directory,
       ports
     );
-    await queries.updateDevServer("running", pid, null, server.ports, id);
+    const detectedPorts = await detectListeningPorts(pid);
+    const resolvedPorts = detectedPorts.length > 0 ? detectedPorts : ports;
+    await queries.updateDevServer(
+      "running",
+      pid,
+      null,
+      JSON.stringify(resolvedPorts),
+      id
+    );
   }
 
   return (await queries.getDevServer(id))!;
@@ -415,23 +442,14 @@ export async function detectNodeServer(
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
     const scripts = packageJson.scripts || {};
 
-    // Look for common dev server scripts
     const devScripts = ["dev", "start", "serve", "develop"];
     for (const script of devScripts) {
       if (scripts[script]) {
-        // Try to detect port from script
-        const scriptContent = scripts[script];
-        let port = 3000; // default
-        const portMatch = scriptContent.match(/(?:port|PORT)[=\s]+(\d+)/i);
-        if (portMatch) {
-          port = parseInt(portMatch[1], 10);
-        }
-
         return {
           type: "node",
           name: packageJson.name || path.basename(workingDir),
           command: `npm run ${script}`,
-          ports: [port],
+          ports: [],
         };
       }
     }

package/lib/status-monitor.ts

@@ -20,6 +20,7 @@ import {
 import type { AgentType } from "./providers";
 import { broadcast } from "./claude/watcher";
 import { getDb } from "./db";
+import { getTunnelUrls } from "./tunnels";
 import { STATES_DIR } from "./hooks/setup";
 import { getSessionInfo } from "@anthropic-ai/claude-agent-sdk";
 
@@ -54,6 +55,8 @@ export interface SessionStatusSnapshot {
   waitingContext?: string;
   claudeSessionId: string | null;
   agentType: AgentType;
+  listeningPorts: number[];
+  tunnelUrls: Record<number, string>;
 }
 
 // --- State ---
@@ -88,6 +91,88 @@ function listStateFiles(): Map<string, StateFile> {
   return map;
 }
 
+// --- Port detection ---
+
+interface ListeningProcess {
+  pid: string;
+  port: number;
+  cwd: string;
+}
+
+let cachedListeners: { data: ListeningProcess[]; ts: number } | null = null;
+const LISTENER_CACHE_TTL = 2500;
+
+async function getListeningProcesses(): Promise<ListeningProcess[]> {
+  const now = Date.now();
+  if (cachedListeners && now - cachedListeners.ts < LISTENER_CACHE_TTL) {
+    return cachedListeners.data;
+  }
+
+  try {
+    const { stdout } = await execAsync(
+      `lsof -P -iTCP -sTCP:LISTEN -Fn 2>/dev/null || true`
+    );
+
+    // Parse lsof output: lines alternate between p (pid) and n (name)
+    const results: ListeningProcess[] = [];
+    let currentPid = "";
+    for (const line of stdout.split("\n")) {
+      if (line.startsWith("p")) {
+        currentPid = line.slice(1);
+      } else if (line.startsWith("n") && currentPid) {
+        const port = parseInt(line.slice(line.lastIndexOf(":") + 1), 10);
+        if (!isNaN(port) && port > 0) {
+          results.push({ pid: currentPid, port, cwd: "" });
+        }
+      }
+    }
+
+    // Deduplicate by pid+port
+    const unique = [
+      ...new Map(results.map((r) => [`${r.pid}:${r.port}`, r])).values(),
+    ];
+
+    // Batch-resolve cwds
+    if (unique.length > 0) {
+      const pids = [...new Set(unique.map((r) => r.pid))].join(",");
+      try {
+        const { stdout: cwdOut } = await execAsync(
+          `lsof -a -p ${pids} -d cwd -Fpn 2>/dev/null || true`
+        );
+        const cwdMap = new Map<string, string>();
+        let pid = "";
+        for (const line of cwdOut.split("\n")) {
+          if (line.startsWith("p")) pid = line.slice(1);
+          else if (line.startsWith("n") && pid) cwdMap.set(pid, line.slice(1));
+        }
+        for (const entry of unique) {
+          entry.cwd = cwdMap.get(entry.pid) || "";
+        }
+      } catch {
+        // cwd resolution failed, proceed without
+      }
+    }
+
+    cachedListeners = { data: unique, ts: now };
+    return unique;
+  } catch {
+    return [];
+  }
+}
+
+async function detectSessionPorts(
+  sessionCwd: string | null
+): Promise<number[]> {
+  if (!sessionCwd) return [];
+
+  const listeners = await getListeningProcesses();
+  return [
+    ...new Set(
+      listeners.filter((l) => l.cwd.startsWith(sessionCwd)).map((l) => l.port)
+    ),
+  ].sort((a, b) => a - b);
+}
+
 // --- tmux ---
 
 async function listTmuxSessions(): Promise<Map<string, string>> {
@@ -149,14 +234,22 @@ async function buildSnapshot(
   const entries = await Promise.all(
     [...tmuxSessions.entries()].map(async ([sessionId, tmuxName]) => {
       const meta = await resolveSessionMeta(sessionId);
-      return { sessionId, tmuxName, ...meta };
+      const ports = await detectSessionPorts(meta.cwd);
+      return { sessionId, tmuxName, ports, ...meta };
     })
   );
 
-  for (const { sessionId, tmuxName, name, cwd } of entries) {
+  const db = getDb();
+  const allTunnels = getTunnelUrls();
+  for (const { sessionId, tmuxName, name, cwd, ports } of entries) {
     const agentType = getProviderIdFromSessionName(tmuxName) || "claude";
     const state = stateFiles.get(sessionId);
 
+    const tunnelUrls: Record<number, string> = {};
+    for (const port of ports) {
+      if (allTunnels[port]) tunnelUrls[port] = allTunnels[port];
+    }
+
     snap[sessionId] = {
       sessionName: name,
       cwd,
@@ -167,12 +260,21 @@ async function buildSnapshot(
         : {}),
       claudeSessionId: sessionId,
       agentType,
+      listeningPorts: ports,
+      tunnelUrls,
     };
+
+    try {
+      db.prepare(
+        "UPDATE sessions SET listening_ports = ? WHERE id = ? OR claude_session_id = ?"
+      ).run(JSON.stringify(ports), sessionId, sessionId);
+    } catch {
+      // DB update failure shouldn't break the monitor
+    }
   }
 
   // Filter out hidden sessions
   try {
-    const db = getDb();
     const hiddenRows = db
       .prepare("SELECT item_id FROM hidden_items WHERE item_type = 'session'")
       .all() as { item_id: string }[];
@@ -200,7 +302,9 @@ function snapshotChanged(
       !p ||
       p.status !== n.status ||
       p.lastLine !== n.lastLine ||
-      p.sessionName !== n.sessionName
+      p.sessionName !== n.sessionName ||
+      JSON.stringify(p.listeningPorts) !== JSON.stringify(n.listeningPorts) ||
+      JSON.stringify(p.tunnelUrls) !== JSON.stringify(n.tunnelUrls)
     )
       return true;
   }

package/lib/tunnels.ts

@@ -0,0 +1,157 @@
+import { spawn, exec, type ChildProcess } from "child_process";
+import { promisify } from "util";
+import fs from "fs";
+import path from "path";
+import { broadcast } from "./claude/watcher";
+
+const execAsync = promisify(exec);
+const LOGS_DIR = path.join(process.env.HOME || "~", ".claude-deck", "logs");
+
+const URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+const URL_TIMEOUT_MS = 20000;
+
+interface Tunnel {
+  port: number;
+  pid: number;
+  url: string | null;
+  process: ChildProcess;
+}
+
+// Use globalThis to share the Map across Next.js module boundaries
+// (API routes and the custom server may load this module separately)
+const GLOBAL_KEY = "__claudeDeckTunnels" as const;
+const activeTunnels: Map<number, Tunnel> =
+  ((globalThis as Record<string, unknown>)[GLOBAL_KEY] as Map<
+    number,
+    Tunnel
+  >) ??
+  (() => {
+    const map = new Map<number, Tunnel>();
+    (globalThis as Record<string, unknown>)[GLOBAL_KEY] = map;
+    return map;
+  })();
+
+export async function isCloudflaredInstalled(): Promise<boolean> {
+  try {
+    await execAsync("cloudflared --version 2>/dev/null");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function startTunnel(
+  port: number
+): Promise<{ port: number; url: string | null }> {
+  const existing = activeTunnels.get(port);
+  if (existing) return { port: existing.port, url: existing.url };
+
+  const logPath = path.join(LOGS_DIR, `tunnel_${port}.log`);
+  const logStream = fs.createWriteStream(logPath, { flags: "a" });
+
+  const child = spawn(
+    "cloudflared",
+    [
+      "tunnel",
+      "--url",
+      `http://localhost:${port}`,
+      "--http-host-header",
+      `localhost:${port}`,
+    ],
+    {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    }
+  );
+
+  const tunnel: Tunnel = {
+    port,
+    pid: child.pid || 0,
+    url: null,
+    process: child,
+  };
+  activeTunnels.set(port, tunnel);
+
+  const url = await new Promise<string | null>((resolve) => {
+    const timeout = setTimeout(() => resolve(null), URL_TIMEOUT_MS);
+    let resolved = false;
+
+    const handleData = (chunk: Buffer) => {
+      const text = chunk.toString();
+      logStream.write(text);
+      if (resolved) return;
+      const match = text.match(URL_PATTERN);
+      if (match) {
+        resolved = true;
+        clearTimeout(timeout);
+        resolve(match[0]);
+      }
+    };
+
+    child.stdout?.on("data", handleData);
+    child.stderr?.on("data", handleData);
+
+    child.on("exit", () => {
+      if (!resolved) {
+        clearTimeout(timeout);
+        resolve(null);
+      }
+    });
+  });
+
+  tunnel.url = url;
+
+  child.on("exit", () => {
+    activeTunnels.delete(port);
+    logStream.end();
+    broadcastTunnelUpdate();
+  });
+
+  broadcastTunnelUpdate();
+  return { port, url };
+}
+
+export async function stopTunnel(port: number): Promise<void> {
+  const tunnel = activeTunnels.get(port);
+  if (!tunnel) return;
+
+  try {
+    tunnel.process.kill("SIGTERM");
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    if (!tunnel.process.killed) {
+      tunnel.process.kill("SIGKILL");
+    }
+  } catch {
+    // Process may already be dead
+  }
+
+  activeTunnels.delete(port);
+  broadcastTunnelUpdate();
+}
+
+export function getTunnelUrls(): Record<number, string> {
+  const result: Record<number, string> = {};
+  for (const [port, tunnel] of activeTunnels) {
+    if (tunnel.url) result[port] = tunnel.url;
+  }
+  return result;
+}
+
+export function getTunnelsList(): { port: number; url: string | null }[] {
+  return [...activeTunnels.values()].map((t) => ({ port: t.port, url: t.url }));
+}
+
+export function stopAllTunnels(): void {
+  for (const [, tunnel] of activeTunnels) {
+    try {
+      tunnel.process.kill("SIGTERM");
+    } catch {
+      // ignore
+    }
+  }
+  activeTunnels.clear();
+}
+
+function broadcastTunnelUpdate(): void {
+  broadcast({ type: "tunnels-updated", tunnels: getTunnelUrls() });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atercates/claude-deck",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "claude-deck": "./scripts/claude-deck"

package/scripts/lib/prerequisites.sh

@@ -388,6 +388,72 @@ install_ripgrep() {
     esac
 }
 
+check_cloudflared() {
+    if command -v cloudflared &> /dev/null; then
+        local cf_path=$(command -v cloudflared)
+        local cf_version=$(cloudflared --version 2>/dev/null | awk '{print $2}' || echo "unknown")
+        log_success "Found cloudflared $cf_version at $cf_path"
+        return 0
+    fi
+
+    source_node_managers
+
+    if command -v cloudflared &> /dev/null; then
+        local cf_path=$(command -v cloudflared)
+        local cf_version=$(cloudflared --version 2>/dev/null | awk '{print $2}' || echo "unknown")
+        log_success "Found cloudflared $cf_version at $cf_path"
+        return 0
+    fi
+
+    return 1
+}
+
+install_cloudflared() {
+    if command -v cloudflared &> /dev/null; then
+        return 0
+    fi
+
+    log_info "Installing cloudflared (Cloudflare Tunnel)..."
+
+    case "$OS" in
+        macos)
+            if ! groups | grep -q admin; then
+                log_info "Non-admin user - downloading pre-built cloudflared binary"
+                local arch
+                arch=$(uname -m)
+                local url
+                if [[ "$arch" == "arm64" ]]; then
+                    url="https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz"
+                else
+                    url="https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64.tgz"
+                fi
+
+                mkdir -p "$HOME/.local/bin"
+                curl -fsSL "$url" | tar -xz -C "$HOME/.local/bin"
+                chmod +x "$HOME/.local/bin/cloudflared"
+                export PATH="$HOME/.local/bin:$PATH"
+                log_success "cloudflared installed to ~/.local/bin/cloudflared"
+            else
+                install_homebrew
+                brew install cloudflared
+            fi
+            ;;
+        debian)
+            curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
+            echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
+            sudo apt-get update
+            sudo apt-get install -y cloudflared
+            ;;
+        redhat)
+            sudo rpm -i "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-x86_64.rpm" 2>/dev/null || true
+            ;;
+        *)
+            log_warn "Please install cloudflared manually: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/"
+            return 1
+            ;;
+    esac
+}
+
 check_and_install_prerequisites() {
     log_info "Checking prerequisites..."
 
@@ -415,30 +481,39 @@ check_and_install_prerequisites() {
 
     if [[ ${#missing[@]} -eq 0 ]]; then
         log_success "All prerequisites met"
-        return 0
-    fi
+    else
+        log_warn "Missing prerequisites: ${missing[*]}"
 
-    log_warn "Missing prerequisites: ${missing[*]}"
-
-    if is_interactive; then
-        if ! prompt_yn "Install missing prerequisites?"; then
-            log_error "Please install manually: ${missing[*]}"
-            exit 1
+        if is_interactive; then
+            if ! prompt_yn "Install missing prerequisites?"; then
+                log_error "Please install manually: ${missing[*]}"
+                exit 1
+            fi
         fi
-    fi
 
-    for dep in "${missing[@]}"; do
-        case "$dep" in
-            node) install_node ;;
-            git) install_git ;;
-            tmux) install_tmux ;;
-            ripgrep) install_ripgrep ;;
-        esac
-    done
+        for dep in "${missing[@]}"; do
+            case "$dep" in
+                node) install_node ;;
+                git) install_git ;;
+                tmux) install_tmux ;;
+                ripgrep) install_ripgrep ;;
+            esac
+        done
 
-    log_success "Prerequisites installed"
+        log_success "Prerequisites installed"
+    fi
 
     configure_tmux
+
+    # Optional: cloudflared for tunnel sharing
+    if ! check_cloudflared; then
+        log_info "cloudflared not found (optional - enables port sharing via Cloudflare Tunnel)"
+        if is_interactive; then
+            if prompt_yn "Install cloudflared for tunnel sharing?"; then
+                install_cloudflared
+            fi
+        fi
+    fi
 }
 
 configure_tmux() {

package/server.ts

@@ -13,6 +13,7 @@ import {
   COOKIE_NAME,
   hasUsers,
 } from "./lib/auth";
+import { stopAllTunnels } from "./lib/tunnels";
 
 const dev = process.env.NODE_ENV !== "production";
 const hostname = process.env.HOST || (dev ? "localhost" : "0.0.0.0");
@@ -89,65 +90,86 @@ app.prepare().then(async () => {
     ws.on("close", () => clearInterval(interval));
   }
 
-  // Terminal connections
-  terminalWss.on("connection", (ws: WebSocket) => {
-    setupHeartbeat(ws);
-    let ptyProcess: pty.IPty;
-    try {
-      const shell = process.env.SHELL || "/bin/zsh";
-      // Use minimal env - only essentials for shell to work
-      // This lets Next.js/Vite/etc load .env.local without interference from parent process env
-      const minimalEnv: { [key: string]: string } = {
-        PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
-        HOME: process.env.HOME || "/",
-        USER: process.env.USER || "",
-        SHELL: shell,
-        TERM: "xterm-256color",
-        COLORTERM: "truecolor",
-        LANG: process.env.LANG || "en_US.UTF-8",
-      };
-
-      ptyProcess = pty.spawn(shell, [], {
-        name: "xterm-256color",
-        cols: 80,
-        rows: 24,
-        cwd: process.env.HOME || "/",
-        env: minimalEnv,
-      });
-    } catch (err) {
-      console.error("Failed to spawn pty:", err);
-      ws.send(
-        JSON.stringify({ type: "error", message: "Failed to start terminal" })
-      );
-      ws.close();
-      return;
-    }
+  // --- Persistent PTY pool ---
+  // PTYs survive WebSocket disconnects. Clients attach/reattach by ptyId.
+  interface PtyEntry {
+    process: pty.IPty;
+    ws: WebSocket | null;
+    buffer: string[];
+  }
+  const ptyPool = new Map<string, PtyEntry>();
+  const MAX_SCROLLBACK_BUFFER = 50000;
+
+  function spawnPty(): { id: string; entry: PtyEntry } {
+    const shell = process.env.SHELL || "/bin/zsh";
+    const minimalEnv: { [key: string]: string } = {
+      PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+      HOME: process.env.HOME || "/",
+      USER: process.env.USER || "",
+      SHELL: shell,
+      TERM: "xterm-256color",
+      COLORTERM: "truecolor",
+      LANG: process.env.LANG || "en_US.UTF-8",
+    };
+
+    const proc = pty.spawn(shell, [], {
+      name: "xterm-256color",
+      cols: 80,
+      rows: 24,
+      cwd: process.env.HOME || "/",
+      env: minimalEnv,
+    });
+
+    const id = `pty_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+    const entry: PtyEntry = { process: proc, ws: null, buffer: [] };
 
-    ptyProcess.onData((data: string) => {
-      if (ws.readyState === WebSocket.OPEN) {
-        ws.send(JSON.stringify({ type: "output", data }));
+    proc.onData((data: string) => {
+      entry.buffer.push(data);
+      if (entry.buffer.length > MAX_SCROLLBACK_BUFFER) {
+        entry.buffer.splice(0, entry.buffer.length - MAX_SCROLLBACK_BUFFER);
+      }
+      if (entry.ws?.readyState === WebSocket.OPEN) {
+        entry.ws.send(JSON.stringify({ type: "output", data }));
       }
     });
 
-    ptyProcess.onExit(({ exitCode }) => {
-      if (ws.readyState === WebSocket.OPEN) {
-        ws.send(JSON.stringify({ type: "exit", code: exitCode }));
-        ws.close();
+    proc.onExit(({ exitCode }) => {
+      if (entry.ws?.readyState === WebSocket.OPEN) {
+        entry.ws.send(JSON.stringify({ type: "exit", code: exitCode }));
       }
+      ptyPool.delete(id);
     });
 
+    ptyPool.set(id, entry);
+    return { id, entry };
+  }
+
+  function attachWsToPty(ws: WebSocket, entry: PtyEntry, _ptyId: string) {
+    // Detach previous WebSocket if any
+    if (entry.ws && entry.ws !== ws && entry.ws.readyState === WebSocket.OPEN) {
+      entry.ws.onclose = null;
+      entry.ws.onerror = null;
+      entry.ws.close(1000, "Replaced by new connection");
+    }
+    entry.ws = ws;
+
+    // Replay buffered output so the client sees prior terminal state
+    if (entry.buffer.length > 0) {
+      ws.send(JSON.stringify({ type: "output", data: entry.buffer.join("") }));
+    }
+
     ws.on("message", (message: Buffer) => {
       try {
         const msg = JSON.parse(message.toString());
         switch (msg.type) {
           case "input":
-            ptyProcess.write(msg.data);
+            entry.process.write(msg.data);
             break;
           case "resize":
-            ptyProcess.resize(msg.cols, msg.rows);
+            entry.process.resize(msg.cols, msg.rows);
             break;
           case "command":
-            ptyProcess.write(msg.data + "\r");
+            entry.process.write(msg.data + "\r");
             break;
         }
       } catch (err) {
@@ -156,13 +178,42 @@ app.prepare().then(async () => {
     });
 
     ws.on("close", () => {
-      ptyProcess.kill();
+      if (entry.ws === ws) entry.ws = null;
+      // PTY stays alive — no kill
     });
 
-    ws.on("error", (err) => {
-      console.error("WebSocket error:", err);
-      ptyProcess.kill();
+    ws.on("error", () => {
+      if (entry.ws === ws) entry.ws = null;
     });
+  }
+
+  // Terminal connections
+  terminalWss.on("connection", (ws: WebSocket, request) => {
+    setupHeartbeat(ws);
+
+    const { query } = parse(request.url || "", true);
+    const requestedPtyId = typeof query.ptyId === "string" ? query.ptyId : null;
+
+    // Try to reattach to existing PTY
+    if (requestedPtyId && ptyPool.has(requestedPtyId)) {
+      const entry = ptyPool.get(requestedPtyId)!;
+      ws.send(JSON.stringify({ type: "pty-id", ptyId: requestedPtyId }));
+      attachWsToPty(ws, entry, requestedPtyId);
+      return;
+    }
+
+    // Spawn new PTY
+    try {
+      const { id, entry } = spawnPty();
+      ws.send(JSON.stringify({ type: "pty-id", ptyId: id }));
+      attachWsToPty(ws, entry, id);
+    } catch (err) {
+      console.error("Failed to spawn pty:", err);
+      ws.send(
+        JSON.stringify({ type: "error", message: "Failed to start terminal" })
+      );
+      ws.close();
+    }
   });
 
   await initDb();
@@ -172,6 +223,13 @@ app.prepare().then(async () => {
   startWatcher();
   startStatusMonitor();
 
+  const shutdown = () => {
+    stopAllTunnels();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
   server.listen(port, () => {
     console.log(`> ClaudeDeck ready on http://${hostname}:${port}`);
   });