@atercates/claude-deck 0.2.7 → 0.2.9

package/README.md

@@ -1,6 +1,6 @@
 # ClaudeDeck
 
-A mobile-first web UI for managing AI coding sessions.
+Self-hosted web UI for managing Claude Code sessions.
 
 [![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/cSjutkCGAh)
 
@@ -10,79 +10,110 @@ https://github.com/user-attachments/assets/0e2e66f7-037e-4739-99ec-608d1840df0a
 
 ## 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:
+### Quick Install
 
 ```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):
+The installer will:
 
-- macOS (Apple Silicon): `.dmg`
-- Linux: `.deb` or `.AppImage`
+- Install Node.js 24 if needed (via [n](https://github.com/tj/n))
+- Install pnpm
+- Ask for port, SSH host/port (for VS Code remote button)
+- Clone, build, and start as a systemd service
+- First visit prompts you to create an account
 
-> **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.
+### Non-Interactive
 
-> **Don't want to self-host?** Try [ClaudeDeck Cloud](https://runagentos.com) - pre-configured cloud VMs for AI coding.
+```bash
+bash install.sh --port 3011 --ssh-host myserver.com --ssh-port 22 -y
+```
 
 ### Manual Install
 
 ```bash
 git clone https://github.com/ATERCATES/claude-deck
 cd claude-deck
-npm install
-npm run dev  # http://localhost:3011
+pnpm install
+pnpm build
+pnpm start  # 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)
+- tmux (with `set -g mouse on` in `~/.tmux.conf`)
+- [Claude Code](https://github.com/anthropics/claude-code)
+
+## Configuration
+
+Create a `.env` file in the project root:
+
+```bash
+PORT=3011
+
+# SSH config for "Open in VS Code" remote button (optional)
+SSH_HOST=myserver.example.com
+SSH_PORT=22
+```
 
 ## 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
+- **Session management** - Resume, create, and organize Claude Code sessions
+- **Mobile-first** - Full functionality from your phone
 - **Multi-pane layout** - Run up to 4 sessions side-by-side
+- **Active session monitoring** - Real-time status (running/waiting/idle)
 - **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
+- **VS Code integration** - Open projects in VS Code with one click (supports SSH remote)
+- **Auth** - Login with username/password, optional TOTP 2FA
 
-## CLI Commands
+## Service Management
 
 ```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
+sudo systemctl start claudedeck
+sudo systemctl stop claudedeck
+sudo systemctl restart claudedeck
+sudo systemctl status claudedeck
+sudo journalctl -u claudedeck -f   # tail logs
+```
+
+## Reverse Proxy (nginx)
+
+For HTTPS access behind nginx:
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 443 ssl;
+    server_name claudedeck.example.com;
+
+    ssl_certificate     /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:3011;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+}
 ```
 
 ## Mobile Access
@@ -95,12 +126,17 @@ Use [Tailscale](https://tailscale.com) for secure access from your phone:
 
 ## Documentation
 
-For configuration and advanced usage, see the [docs](https://www.runagentos.com/docs).
+Detailed technical docs are in `docs/`:
+
+- [`docs/architecture.md`](docs/architecture.md) - System overview, data flow, directory structure
+- [`docs/decisions.md`](docs/decisions.md) - Why SQLite, why tmux, why JSONL
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) - Common issues and fixes
+- [`docs/setup.md`](docs/setup.md) - Requirements, Docker, PWA, production deployment
 
 ## 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.
+- **[aTerm](https://github.com/ATERCATES/aTerm)** - Native desktop terminal workspace for AI-assisted coding
+- **[LumifyHub](https://lumifyhub.io)** - Team collaboration platform with real-time chat and structured documentation
 
 ## License
 

package/package.json

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

package/scripts/install.sh

@@ -5,6 +5,9 @@
 # Usage:
 #   curl -fsSL https://raw.githubusercontent.com/ATERCATES/claude-deck/main/scripts/install.sh | bash
 #
+# Or with options:
+#   bash install.sh --port 3011 --ssh-host myserver.com --ssh-port 22
+#
 
 set -e
 
@@ -12,37 +15,257 @@ set -e
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
 BOLD='\033[1m'
+DIM='\033[2m'
 NC='\033[0m'
 
-log_info() { echo -e "${BLUE}==>${NC} $1"; }
+log_info()    { echo -e "${BLUE}==>${NC} $1"; }
 log_success() { echo -e "${GREEN}==>${NC} $1"; }
-log_error() { echo -e "${RED}==>${NC} $1"; }
+log_warn()    { echo -e "${YELLOW}==>${NC} $1"; }
+log_error()   { echo -e "${RED}==>${NC} $1"; }
 
+INSTALL_DIR="$HOME/.claude-deck"
 REPO_URL="https://github.com/ATERCATES/claude-deck.git"
-INSTALL_DIR="$HOME/.claude-deck/repo"
+NODE_MIN_VERSION=24
+
+# ─── Parse CLI flags ──────────────────────────────────────────────────────────
+
+FLAG_PORT=""
+FLAG_SSH_HOST=""
+FLAG_SSH_PORT=""
+FLAG_NONINTERACTIVE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)        FLAG_PORT="$2";        shift 2 ;;
+    --ssh-host)    FLAG_SSH_HOST="$2";    shift 2 ;;
+    --ssh-port)    FLAG_SSH_PORT="$2";    shift 2 ;;
+    --yes|-y)      FLAG_NONINTERACTIVE=true; shift ;;
+    *)             shift ;;
+  esac
+done
+
+# ─── Interactive prompts ──────────────────────────────────────────────────────
+
+ask() {
+  local prompt="$1" default="$2" var="$3"
+  if [[ -t 0 ]] && [[ "$FLAG_NONINTERACTIVE" == false ]]; then
+    if [[ -n "$default" ]]; then
+      read -rp "$(echo -e "${BOLD}$prompt${NC} ${DIM}[$default]${NC}: ")" value
+      eval "$var=\"${value:-$default}\""
+    else
+      read -rp "$(echo -e "${BOLD}$prompt${NC}: ")" value
+      eval "$var=\"$value\""
+    fi
+  else
+    eval "$var=\"$default\""
+  fi
+}
+
+# ─── Header ───────────────────────────────────────────────────────────────────
 
 echo ""
-echo -e "${BOLD}ClaudeDeck Installer${NC}"
+echo -e "${BOLD}  ClaudeDeck Installer${NC}"
+echo -e "${DIM}  Self-hosted web UI for Claude Code sessions${NC}"
 echo ""
 
-# Check for git
+# ─── Check prerequisites ─────────────────────────────────────────────────────
+
+log_info "Checking prerequisites..."
+
 if ! command -v git &> /dev/null; then
-    log_error "git is required. Please install git first."
+  log_error "git is required. Install it with: sudo apt install git"
+  exit 1
+fi
+
+if ! command -v tmux &> /dev/null; then
+  log_warn "tmux is not installed (required for session management)"
+  ask "Install tmux now? (y/n)" "y" INSTALL_TMUX
+  if [[ "$INSTALL_TMUX" == "y" ]]; then
+    sudo apt install -y tmux
+    log_success "tmux installed"
+  else
+    log_error "tmux is required. Install it manually and re-run."
     exit 1
+  fi
+fi
+
+# ─── Node.js ──────────────────────────────────────────────────────────────────
+
+install_node() {
+  log_info "Installing Node.js $NODE_MIN_VERSION..."
+  local N_PREFIX="$HOME/.n"
+  mkdir -p "$N_PREFIX"
+  curl -fsSL https://raw.githubusercontent.com/tj/n/master/bin/n -o /tmp/n
+  chmod +x /tmp/n
+  N_PREFIX="$N_PREFIX" /tmp/n "$NODE_MIN_VERSION"
+  rm -f /tmp/n
+  export PATH="$N_PREFIX/bin:$PATH"
+  log_success "Node.js $(node --version) installed"
+}
+
+# Check for existing node
+NODE_OK=false
+if command -v node &> /dev/null; then
+  NODE_VERSION=$(node --version | sed 's/v//' | cut -d. -f1)
+  if [[ "$NODE_VERSION" -ge "$NODE_MIN_VERSION" ]]; then
+    NODE_OK=true
+    log_success "Node.js $(node --version) found"
+  fi
 fi
 
-# Clone or update repo
-if [[ -d "$INSTALL_DIR" ]]; then
-    log_info "Updating existing installation..."
-    cd "$INSTALL_DIR"
-    git pull --ff-only
+# Check ~/.n/bin as well
+if [[ "$NODE_OK" == false ]] && [[ -x "$HOME/.n/bin/node" ]]; then
+  export PATH="$HOME/.n/bin:$PATH"
+  NODE_VERSION=$(node --version | sed 's/v//' | cut -d. -f1)
+  if [[ "$NODE_VERSION" -ge "$NODE_MIN_VERSION" ]]; then
+    NODE_OK=true
+    log_success "Node.js $(node --version) found in ~/.n"
+  fi
+fi
+
+if [[ "$NODE_OK" == false ]]; then
+  install_node
+fi
+
+# pnpm
+if ! command -v pnpm &> /dev/null; then
+  log_info "Installing pnpm..."
+  npm install -g pnpm > /dev/null 2>&1
+  log_success "pnpm $(pnpm --version) installed"
 else
-    log_info "Downloading ClaudeDeck..."
-    mkdir -p "$(dirname "$INSTALL_DIR")"
-    git clone "$REPO_URL" "$INSTALL_DIR"
-    cd "$INSTALL_DIR"
+  log_success "pnpm $(pnpm --version) found"
 fi
 
-# Run the install command
-exec "$INSTALL_DIR/scripts/claude-deck" install
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+echo ""
+log_info "Configuration"
+echo ""
+
+PORT="${FLAG_PORT}"
+SSH_HOST="${FLAG_SSH_HOST}"
+SSH_PORT="${FLAG_SSH_PORT}"
+
+ask "Port" "3011" PORT
+ask "SSH host for VS Code remote button (leave empty to skip)" "" SSH_HOST
+
+if [[ -n "$SSH_HOST" ]]; then
+  ask "SSH port" "22" SSH_PORT
+fi
+
+echo ""
+
+# ─── Install ──────────────────────────────────────────────────────────────────
+
+if [[ -d "$INSTALL_DIR/repo" ]]; then
+  log_info "Updating existing installation..."
+  cd "$INSTALL_DIR/repo"
+  git pull --ff-only
+else
+  log_info "Cloning ClaudeDeck..."
+  mkdir -p "$INSTALL_DIR"
+  git clone "$REPO_URL" "$INSTALL_DIR/repo"
+  cd "$INSTALL_DIR/repo"
+fi
+
+# Dependencies
+log_info "Installing dependencies..."
+pnpm install > /dev/null 2>&1
+
+# Approve native builds if needed
+if grep -q "onlyBuiltDependencies" package.json 2>/dev/null; then
+  : # already configured
+else
+  node -e "
+    const pkg = require('./package.json');
+    pkg.pnpm = pkg.pnpm || {};
+    pkg.pnpm.onlyBuiltDependencies = ['better-sqlite3', 'esbuild', 'node-pty', 'sharp'];
+    require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+  "
+  pnpm install > /dev/null 2>&1
+fi
+
+# Write .env
+log_info "Writing .env..."
+cat > "$INSTALL_DIR/repo/.env" << EOF
+PORT=$PORT
+EOF
+
+if [[ -n "$SSH_HOST" ]]; then
+  echo "SSH_HOST=$SSH_HOST" >> "$INSTALL_DIR/repo/.env"
+fi
+if [[ -n "$SSH_PORT" ]] && [[ "$SSH_PORT" != "22" ]]; then
+  echo "SSH_PORT=$SSH_PORT" >> "$INSTALL_DIR/repo/.env"
+fi
+
+# Build
+log_info "Building for production (this may take a minute)..."
+pnpm build
+
+# tmux config
+if [[ ! -f "$HOME/.tmux.conf" ]] || ! grep -q "mouse on" "$HOME/.tmux.conf" 2>/dev/null; then
+  log_info "Enabling tmux mouse support..."
+  echo "set -g mouse on" >> "$HOME/.tmux.conf"
+fi
+
+# ─── Systemd service ─────────────────────────────────────────────────────────
+
+NODE_BIN=$(which node)
+TSX_BIN="$INSTALL_DIR/repo/node_modules/.bin/tsx"
+
+SERVICE_FILE="[Unit]
+Description=ClaudeDeck
+After=network.target
+
+[Service]
+Type=simple
+User=$USER
+WorkingDirectory=$INSTALL_DIR/repo
+Environment=NODE_ENV=production
+Environment=PATH=$(dirname "$NODE_BIN"):$INSTALL_DIR/repo/node_modules/.bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ExecStart=$TSX_BIN --env-file=.env server.ts
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target"
+
+INSTALL_SERVICE=false
+if [[ -t 0 ]] && [[ "$FLAG_NONINTERACTIVE" == false ]]; then
+  echo ""
+  ask "Install as systemd service? (y/n)" "y" INSTALL_SVC_ANSWER
+  [[ "$INSTALL_SVC_ANSWER" == "y" ]] && INSTALL_SERVICE=true
+else
+  INSTALL_SERVICE=true
+fi
+
+if [[ "$INSTALL_SERVICE" == true ]]; then
+  log_info "Installing systemd service..."
+  echo "$SERVICE_FILE" | sudo tee /etc/systemd/system/claudedeck.service > /dev/null
+  sudo systemctl daemon-reload
+  sudo systemctl enable claudedeck > /dev/null 2>&1
+  sudo systemctl restart claudedeck
+  sleep 2
+
+  if systemctl is-active --quiet claudedeck; then
+    log_success "Service running on port $PORT"
+  else
+    log_error "Service failed to start. Check: sudo journalctl -u claudedeck -f"
+  fi
+fi
+
+# ─── Done ─────────────────────────────────────────────────────────────────────
+
+echo ""
+echo -e "${GREEN}${BOLD}  ClaudeDeck installed!${NC}"
+echo ""
+echo -e "  ${BOLD}Local:${NC}    http://localhost:$PORT"
+if [[ -n "$SSH_HOST" ]]; then
+  echo -e "  ${BOLD}Remote:${NC}   Configure your reverse proxy to point to port $PORT"
+fi
+echo ""
+echo -e "  ${DIM}First visit will prompt you to create an account.${NC}"
+echo -e "  ${DIM}Commands: sudo systemctl {start|stop|restart|status} claudedeck${NC}"
+echo ""