@atercates/claude-deck 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saad Naveed
+
+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,123 @@
+# ClaudeDeck
+
+A mobile-first web UI for managing AI coding sessions.
+
+[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/cSjutkCGAh)
+
+https://github.com/user-attachments/assets/0e2e66f7-037e-4739-99ec-608d1840df0a
+
+![ClaudeDeck Screenshot](screenshot-v2.png)
+
+## Installation
+
+### Via npm (Recommended)
+
+If you already have Node.js 24+ installed:
+
+```bash
+# Install globally
+npm install -g @atercates/claude-deck
+
+# Run setup (checks/installs tmux, ripgrep, builds app)
+claude-deck install
+
+# Start the server
+claude-deck start
+```
+
+### Via curl (Installs everything)
+
+For fresh installs without Node.js:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/atercates/claude-deck/main/scripts/install.sh | bash
+claude-deck start
+```
+
+### Desktop App
+
+Download native desktop apps from [Releases](https://github.com/atercates/claude-deck/releases):
+
+- macOS (Apple Silicon): `.dmg`
+- Linux: `.deb` or `.AppImage`
+
+> **Note:** The desktop app is a native wrapper around the web UI. You still need to install and run ClaudeDeck (via the installer script above) for the backend server. The desktop app just provides a convenient native window instead of using your browser.
+
+> **Don't want to self-host?** Try [ClaudeDeck Cloud](https://runagentos.com) - pre-configured cloud VMs for AI coding.
+
+### Manual Install
+
+```bash
+git clone https://github.com/atercates/claude-deck
+cd claude-deck
+npm install
+npm run dev  # http://localhost:3011
+```
+
+### Prerequisites
+
+- Node.js 24+
+- tmux
+- [ripgrep](https://github.com/BurntSushi/ripgrep) (for code search - auto-installed by installer script, or run `claude-deck update`)
+- At least one AI CLI: [Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://github.com/anomalyco/opencode), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Aider](https://aider.chat/), or [Cursor CLI](https://cursor.com/cli)
+
+## Supported Agents
+
+| Agent       | Resume | Fork | Auto-Approve                     |
+| ----------- | ------ | ---- | -------------------------------- |
+| Claude Code | ✅     | ✅   | `--dangerously-skip-permissions` |
+| Codex       | ❌     | ❌   | `--approval-mode full-auto`      |
+| OpenCode    | ❌     | ❌   | Config file                      |
+| Gemini CLI  | ❌     | ❌   | `--yolomode`                     |
+| Aider       | ❌     | ❌   | `--yes`                          |
+| Cursor CLI  | ❌     | ❌   | N/A                              |
+| Amp         | ❌     | ❌   | `--dangerously-allow-all`        |
+| Pi          | ❌     | ❌   | N/A                              |
+| Oh My Pi    | ❌     | ❌   | N/A                              |
+
+## Features
+
+- **Mobile-first** - Full functionality from your phone, not a dumbed-down responsive view
+- **Voice-to-text** - Dictate prompts to your coding sessions hands-free
+- **Multi-pane layout** - Run up to 4 sessions side-by-side
+- **Code search** - Fast codebase search with syntax-highlighted results (Cmd+K)
+- **File picker** - Browse and attach files to sessions, with direct upload from mobile
+- **Clone from GitHub** - Clone repos directly from the UI when creating projects
+- **Git integration** - Status, diffs, commits, PRs from the UI
+- **Git worktrees** - Isolated branches with auto-setup
+- **Dev servers** - Start/stop Node.js and Docker servers
+- **Session orchestration** - Conductor/worker model via MCP
+
+## CLI Commands
+
+```bash
+claude-deck run       # Start and open browser
+claude-deck start     # Start in background
+claude-deck stop      # Stop server
+claude-deck status    # Show URLs
+claude-deck logs      # Tail logs
+claude-deck update    # Update to latest
+```
+
+## Mobile Access
+
+Use [Tailscale](https://tailscale.com) for secure access from your phone:
+
+1. Install Tailscale on your dev machine and phone
+2. Sign in with the same account
+3. Access `http://100.x.x.x:3011` from your phone
+
+## Documentation
+
+For configuration and advanced usage, see the [docs](https://www.runagentos.com/docs).
+
+## Related Projects
+
+- **[aTerm](https://github.com/atercates/aTerm)** - A Tauri-based desktop terminal workspace for AI-assisted coding. While ClaudeDeck is a mobile-first web UI, aTerm is a native desktop app with multi-pane layouts optimized for running AI coding agents (Claude Code, Aider, OpenCode) alongside shells, dev servers, and a built-in git panel. Choose ClaudeDeck for mobile access and browser-based workflows, or aTerm for a native desktop terminal experience.
+- **[LumifyHub](https://lumifyhub.io)** - Team collaboration platform with real-time chat and structured documentation. Useful alongside ClaudeDeck for coordinating multi-agent work across a team — share session context, document architectural decisions from coding sessions, and track progress across parallel agent workflows.
+
+## License
+
+MIT License - Free and open source.
+
+See [LICENSE](LICENSE) for full terms.

package/app/api/claude/hidden/route.ts

@@ -0,0 +1,66 @@
+import { NextRequest, NextResponse } from "next/server";
+import { queries } from "@/lib/db";
+
+export async function GET() {
+  try {
+    const items = await queries.getAllHiddenItems();
+    return NextResponse.json({ items });
+  } catch (error) {
+    console.error("Error fetching hidden items:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch hidden items" },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const { itemType, itemId } = await request.json();
+
+    if (!itemType || !itemId) {
+      return NextResponse.json(
+        { error: "itemType and itemId are required" },
+        { status: 400 }
+      );
+    }
+
+    if (!["project", "session"].includes(itemType)) {
+      return NextResponse.json(
+        { error: "itemType must be 'project' or 'session'" },
+        { status: 400 }
+      );
+    }
+
+    await queries.hideItem(itemType, itemId);
+    return NextResponse.json({ hidden: true });
+  } catch (error) {
+    console.error("Error hiding item:", error);
+    return NextResponse.json(
+      { error: "Failed to hide item" },
+      { status: 500 }
+    );
+  }
+}
+
+export async function DELETE(request: NextRequest) {
+  try {
+    const { itemType, itemId } = await request.json();
+
+    if (!itemType || !itemId) {
+      return NextResponse.json(
+        { error: "itemType and itemId are required" },
+        { status: 400 }
+      );
+    }
+
+    await queries.unhideItem(itemType, itemId);
+    return NextResponse.json({ hidden: false });
+  } catch (error) {
+    console.error("Error unhiding item:", error);
+    return NextResponse.json(
+      { error: "Failed to unhide item" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/claude/projects/[name]/sessions/route.ts

@@ -0,0 +1,71 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCachedSessions, getCachedProjects } from "@/lib/claude/jsonl-cache";
+import { queries } from "@/lib/db";
+import fs from "fs";
+import path from "path";
+
+function resolveValidCwd(
+  cwd: string | null,
+  projectDirectory: string | null
+): string {
+  if (!cwd && projectDirectory) return projectDirectory;
+  if (!cwd) return process.env.HOME || "/";
+  if (fs.existsSync(cwd)) return cwd;
+  let dir = cwd;
+  while (dir && dir !== "/" && !fs.existsSync(dir)) {
+    dir = path.dirname(dir);
+  }
+  if (dir && dir !== "/" && fs.existsSync(dir)) return dir;
+  return projectDirectory || process.env.HOME || "/";
+}
+
+interface RouteParams {
+  params: Promise<{ name: string }>;
+}
+
+export async function GET(request: NextRequest, { params }: RouteParams) {
+  try {
+    const { name } = await params;
+    const { searchParams } = new URL(request.url);
+    const limit = parseInt(searchParams.get("limit") || "50", 10);
+    const offset = parseInt(searchParams.get("offset") || "0", 10);
+    const includeHidden = searchParams.get("includeHidden") === "true";
+
+    const [allSessions, allProjects] = await Promise.all([
+      getCachedSessions(name),
+      getCachedProjects(),
+    ]);
+
+    const project = allProjects.find((p) => p.name === name);
+    const projectDir = project?.directory || null;
+
+    const hiddenItems = await queries.getHiddenItems("session");
+    const hiddenSet = new Set(hiddenItems.map((h) => h.item_id));
+
+    const enriched = allSessions
+      .filter((s) => s.messageCount > 2 || s.cwd)
+      .map((s) => ({
+        ...s,
+        cwd: resolveValidCwd(s.cwd, projectDir),
+        hidden: hiddenSet.has(s.sessionId),
+      }));
+
+    const filtered = includeHidden
+      ? enriched
+      : enriched.filter((s) => !s.hidden);
+
+    const paginated = filtered.slice(offset, offset + limit);
+
+    return NextResponse.json({
+      sessions: paginated,
+      total: filtered.length,
+      hasMore: offset + limit < filtered.length,
+    });
+  } catch (error) {
+    console.error("Error fetching sessions:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch sessions" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/claude/projects/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from "next/server";
+import { getCachedProjects } from "@/lib/claude/jsonl-cache";
+import { queries } from "@/lib/db";
+
+export interface ClaudeProject {
+  name: string;
+  directory: string | null;
+  displayName: string;
+  sessionCount: number;
+  lastActivity: string | null;
+  hidden: boolean;
+}
+
+export async function GET() {
+  try {
+    const cachedProjects = await getCachedProjects();
+    const hiddenItems = await queries.getHiddenItems("project");
+    const hiddenSet = new Set(hiddenItems.map((h) => h.item_id));
+
+    const projects: ClaudeProject[] = cachedProjects.map((p) => ({
+      ...p,
+      hidden: hiddenSet.has(p.name),
+    }));
+
+    projects.sort((a, b) => {
+      if (a.hidden !== b.hidden) return a.hidden ? 1 : -1;
+      if (!a.lastActivity && !b.lastActivity) return 0;
+      if (!a.lastActivity) return 1;
+      if (!b.lastActivity) return -1;
+      return (
+        new Date(b.lastActivity).getTime() -
+        new Date(a.lastActivity).getTime()
+      );
+    });
+
+    return NextResponse.json({ projects });
+  } catch (error) {
+    console.error("Error discovering Claude projects:", error);
+    return NextResponse.json(
+      { error: "Failed to discover projects" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/code-search/available/route.ts

@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { isRipgrepAvailable } from "@/lib/code-search";
+
+export async function GET() {
+  try {
+    const available = isRipgrepAvailable();
+    return NextResponse.json({ available });
+  } catch (error) {
+    console.error("Error checking ripgrep availability:", error);
+    return NextResponse.json({ available: false });
+  }
+}

package/app/api/code-search/route.ts

@@ -0,0 +1,47 @@
+import { NextRequest, NextResponse } from "next/server";
+import { searchCode, formatSearchResults } from "@/lib/code-search";
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = request.nextUrl;
+    const query = searchParams.get("query");
+    const path = searchParams.get("path");
+    const maxResults = parseInt(searchParams.get("maxResults") || "100");
+    const contextLines = parseInt(searchParams.get("contextLines") || "2");
+
+    if (!query) {
+      return NextResponse.json(
+        { error: "Query parameter is required" },
+        { status: 400 }
+      );
+    }
+
+    if (!path) {
+      return NextResponse.json(
+        { error: "Path parameter is required" },
+        { status: 400 }
+      );
+    }
+
+    const expandedPath = path.replace(/^~/, process.env.HOME || "");
+
+    const rawMatches = searchCode(expandedPath, query, {
+      maxResults,
+      contextLines,
+    });
+
+    const results = formatSearchResults(rawMatches);
+
+    return NextResponse.json({
+      results,
+      query,
+      path: expandedPath,
+      count: results.length,
+    });
+  } catch (error) {
+    console.error("Code search error:", error);
+    const message =
+      error instanceof Error ? error.message : "Failed to search code";
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/dev-servers/[id]/logs/route.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getServerLogs } from "@/lib/dev-servers";
+
+// GET /api/dev-servers/[id]/logs - Get server logs
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const { searchParams } = new URL(request.url);
+    const lines = parseInt(searchParams.get("lines") || "100", 10);
+
+    const logs = await getServerLogs(id, lines);
+    return NextResponse.json({ logs });
+  } catch (error) {
+    console.error("Error getting dev server logs:", error);
+    return NextResponse.json(
+      { error: "Failed to get dev server logs" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/dev-servers/[id]/restart/route.ts

@@ -0,0 +1,20 @@
+import { NextRequest, NextResponse } from "next/server";
+import { restartServer } from "@/lib/dev-servers";
+
+// POST /api/dev-servers/[id]/restart - Restart a server
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const server = await restartServer(id);
+    return NextResponse.json({ server });
+  } catch (error) {
+    console.error("Error restarting dev server:", error);
+    return NextResponse.json(
+      { error: "Failed to restart dev server" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/dev-servers/[id]/route.ts

@@ -0,0 +1,51 @@
+import { NextRequest, NextResponse } from "next/server";
+import { queries, type DevServer } from "@/lib/db";
+import { getServerStatus, removeServer } from "@/lib/dev-servers";
+
+// GET /api/dev-servers/[id] - Get single server with live status
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const server = await queries.getDevServer(id) as DevServer | undefined;
+
+    if (!server) {
+      return NextResponse.json({ error: "Server not found" }, { status: 404 });
+    }
+
+    // Get live status
+    const liveStatus = await getServerStatus(server);
+    if (liveStatus !== server.status) {
+      await queries.updateDevServerStatus(liveStatus, id);
+      server.status = liveStatus;
+    }
+
+    return NextResponse.json({ server });
+  } catch (error) {
+    console.error("Error getting dev server:", error);
+    return NextResponse.json(
+      { error: "Failed to get dev server" },
+      { status: 500 }
+    );
+  }
+}
+
+// DELETE /api/dev-servers/[id] - Stop and remove server
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    await removeServer(id);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Error removing dev server:", error);
+    return NextResponse.json(
+      { error: "Failed to remove dev server" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/dev-servers/[id]/stop/route.ts

@@ -0,0 +1,20 @@
+import { NextRequest, NextResponse } from "next/server";
+import { stopServer } from "@/lib/dev-servers";
+
+// POST /api/dev-servers/[id]/stop - Stop a server
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    await stopServer(id);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Error stopping dev server:", error);
+    return NextResponse.json(
+      { error: "Failed to stop dev server" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/dev-servers/detect/route.ts

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from "next/server";
+import { detectServers } from "@/lib/dev-servers";
+import { queries, type Project } from "@/lib/db";
+
+// GET /api/dev-servers/detect?projectId=X - Auto-detect available dev servers
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const projectId = searchParams.get("projectId");
+
+    if (!projectId) {
+      return NextResponse.json(
+        { error: "projectId is required" },
+        { status: 400 }
+      );
+    }
+
+    const project = await queries.getProject(projectId) as
+      | Project
+      | undefined;
+    if (!project) {
+      return NextResponse.json({ error: "Project not found" }, { status: 404 });
+    }
+
+    // Expand ~ to home directory
+    const expandedPath = project.working_directory.startsWith("~")
+      ? project.working_directory.replace("~", process.env.HOME || "")
+      : project.working_directory;
+
+    const servers = await detectServers(expandedPath);
+    return NextResponse.json({ servers, workingDirectory: expandedPath });
+  } catch (error) {
+    console.error("Error detecting dev servers:", error);
+    return NextResponse.json(
+      { error: "Failed to detect dev servers" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/dev-servers/route.ts

@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getAllServers, startServer } from "@/lib/dev-servers";
+
+// GET /api/dev-servers - List all servers with live status
+export async function GET() {
+  try {
+    const servers = await getAllServers();
+    return NextResponse.json({ servers });
+  } catch (error) {
+    console.error("Error getting dev servers:", error);
+    return NextResponse.json(
+      { error: "Failed to get dev servers" },
+      { status: 500 }
+    );
+  }
+}
+
+// POST /api/dev-servers - Start a new server
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { projectId, type, name, command, workingDirectory, ports } = body;
+
+    if (!projectId || !type || !name || !command || !workingDirectory) {
+      return NextResponse.json(
+        { error: "Missing required fields" },
+        { status: 400 }
+      );
+    }
+
+    const server = await startServer({
+      projectId,
+      type,
+      name,
+      command,
+      workingDirectory,
+      ports,
+    });
+
+    return NextResponse.json({ server });
+  } catch (error) {
+    console.error("Error starting dev server:", error);
+    return NextResponse.json(
+      { error: "Failed to start dev server" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/exec/route.ts

@@ -0,0 +1,60 @@
+import { NextRequest, NextResponse } from "next/server";
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+
+// Max execution time (10 seconds)
+const TIMEOUT = 10000;
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { command } = body;
+
+    if (!command) {
+      return NextResponse.json(
+        { error: "No command specified" },
+        { status: 400 }
+      );
+    }
+
+    const startTime = Date.now();
+
+    try {
+      const { stdout, stderr } = await execAsync(command, {
+        timeout: TIMEOUT,
+        shell: "/bin/zsh",
+        env: {
+          ...process.env,
+          PATH: `/usr/local/bin:/opt/homebrew/bin:${process.env.PATH}`,
+          HOME: process.env.HOME,
+        },
+      });
+
+      const duration = Date.now() - startTime;
+
+      return NextResponse.json({
+        success: true,
+        output: stdout || stderr,
+        duration,
+      });
+    } catch (execError: unknown) {
+      const duration = Date.now() - startTime;
+      const error = execError as {
+        stdout?: string;
+        stderr?: string;
+        message?: string;
+      };
+
+      return NextResponse.json({
+        success: false,
+        output:
+          error.stderr || error.stdout || error.message || "Unknown error",
+        duration,
+      });
+    }
+  } catch {
+    return NextResponse.json({ error: "Invalid request" }, { status: 400 });
+  }
+}