This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

VibeTunnel is a macOS application that allows users to access their terminal sessions through any web browser. It consists of:

• Native macOS app (Swift/SwiftUI) in mac/
• iOS companion app in ios/
• Web frontend (TypeScript/LitElement) and Node.js/Bun server for terminal session management in web/

When the user says "release" or asks to create a release, ALWAYS read and follow mac/docs/release.md for the complete release process.

1. NEVER, EVER, UNDER ANY CIRCUMSTANCES CREATE A NEW BRANCH WITHOUT EXPLICIT USER PERMISSION

   • If you are on a branch (not main), you MUST stay on that branch
   • The user will tell you when to create a new branch with commands like "create a new branch" or "switch to a new branch"
   • Creating branches without permission causes massive frustration and cleanup work
   • Even if changes seem unrelated to the current branch, STAY ON THE CURRENT BRANCH

2. NEVER commit and/or push before the user has tested your changes!

   • Always wait for user confirmation before committing
   • The user needs to verify changes work correctly first

3. ABSOLUTELY FORBIDDEN: NEVER USE git rebase --skip EVER

   • This command can cause data loss and repository corruption
   • If you encounter rebase conflicts, ask the user for help

4. NEVER create duplicate files with version numbers or suffixes

   • When refactoring or improving code, directly modify the existing files
   • DO NOT create new versions with different file names (e.g., file_v2.ts, file_new.ts)
   • Users hate having to manually clean up duplicate files

5. Web Development Workflow - Development vs Production Mode

   • Production Mode: Mac app embeds a pre-built web server during Xcode build
     • Every web change requires: clean → build → run (rebuilds embedded server)
     • Simply restarting serves STALE, CACHED version
   • Development Mode (recommended for web development):
     • Enable "Use Development Server" in VibeTunnel Settings → Debug
     • Mac app runs pnpm run dev instead of embedded server
     • Provides hot reload - web changes automatically rebuild without Mac app rebuild
     • Restart VibeTunnel server (not full rebuild) to pick up web changes

6. Never kill all sessions

   • You are running inside a session yourself; killing all sessions would terminate your own process

• Our workflow: start from main → create branch → make PR → merge → return to main
• PRs sometimes contain multiple different features and that's okay
• Always check current branch with git branch before making changes
• If unsure about branching, ASK THE USER FIRST
• "Adopt" means REVIEW, not merge! When asked to "adopt" a PR, switch to its branch and review the changes. NEVER merge without explicit permission.

When creating pull requests, use the vt command to update the terminal title:

• Run vt title "Brief summary - github.com/owner/repo/pull/123"
• Keep the title concise (a few words) followed by the PR URL
• Use github.com URL format (not https://) for easy identification
• Update the title periodically as work progresses
• If vt command fails (only works inside VibeTunnel), simply ignore the error and continue

DEVELOPMENT MODES:

• Standalone Development: pnpm run dev runs independently on port 4020
• Mac App Integration: Enable "Development Server" in VibeTunnel settings (recommended)
  • Mac app automatically runs pnpm run dev and manages the process
  • Provides seamless integration with Mac app features
  • Hot reload works with full VibeTunnel functionality

In the web/ directory:

# Development
pnpm run dev                   # Standalone development server (port 4020)
pnpm run dev --port 4021       # Alternative port for external device testing

# Code quality (MUST run before commit)
pnpm run lint          # Check for linting errors
pnpm run lint:fix      # Auto-fix linting errors
pnpm run format        # Format with Prettier
pnpm run typecheck     # Check TypeScript types

# Testing (only when requested)
pnpm run test
pnpm run test:coverage
pnpm run test:e2e

In the mac/ directory:

# Build commands
./scripts/build.sh                    # Build release
./scripts/build.sh --configuration Debug  # Build debug
./scripts/build.sh --sign            # Build with code signing

# Other scripts
./scripts/clean.sh                   # Clean build artifacts
./scripts/lint.sh                    # Run linting
./scripts/create-dmg.sh             # Create installer

1. Session Creation: POST /api/sessions spawns new terminal
2. Input: POST /api/sessions/:id/input sends keyboard/mouse input
3. Output:
   • SSE stream at /api/sessions/:id/stream (text)
   • WebSocket at /buffers (binary, efficient rendering)
4. Resize: POST /api/sessions/:id/resize (missing in some implementations)

• Mac App: mac/VibeTunnel/VibeTunnelApp.swift
• Web Frontend: web/src/client/app.ts
• Server: web/src/server/server.ts
• Process spawning and forwarding tool: web/src/server/fwd.ts
• Server Management: mac/VibeTunnel/Core/Services/ServerManager.swift

• Never run tests unless explicitly asked
• Mac tests: Swift Testing framework in VibeTunnelTests/
• Web tests: Vitest in web/src/test/

The CI workflow automatically runs both Node.js and Mac builds:

• Node.js CI: Runs for web OR Mac file changes to ensure web artifacts are always available
• Mac CI: Downloads web artifacts from Node.js CI, with fallback to build locally if missing
• Cross-dependency: Mac builds require web artifacts, so Node.js CI must complete first

When the user reports issues on external devices, use the development server method for testing:

# Run dev server accessible from external devices
cd web
pnpm run dev --port 4021 --bind 0.0.0.0

Then access from the external device using http://[mac-ip]:4021

Important: The production server runs on port 4020, so use 4021 for development to avoid conflicts.

For detailed instructions, see docs/TESTING_EXTERNAL_DEVICES.md

MCP servers extend Claude Code's capabilities with additional tools. Here's how to add them:

Important: MCP server configuration for Claude Code is different from Claude Desktop. Claude Code uses CLI commands, not JSON configuration files.

1. Open a terminal (outside of Claude Code)
2. Run the add command with the MCP server you want:

   # For Playwright (web testing)
   claude mcp add playwright -- npx -y @playwright/mcp@latest
   
   # For XcodeBuildMCP (iOS/macOS development)
   claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest

3. Restart Claude Code to load the new MCP servers
4. Verify installation by running /mcp in Claude Code

# Basic syntax for adding a stdio server
claude mcp add <name> -- <command> [args...]

# Examples:
# Add playwright MCP (highly recommended for web testing)
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Add XcodeBuildMCP for macOS development
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest

# Add with environment variables
claude mcp add my-server -e API_KEY=value -- /path/to/server

# List all configured servers
claude mcp list

# Remove a server
claude mcp remove <name>

1. Playwright MCP - Web testing and browser automation

   • Browser control, screenshots, automated testing
   • Install: claude mcp add playwright -- npx -y @playwright/mcp@latest

2. XcodeBuildMCP - macOS/iOS development (Mac only)

   • Xcode build, test, project management
   • Install: claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest

3. Peekaboo MCP - Visual analysis and screenshots (Mac only)

   • Take screenshots, analyze visual content with AI
   • Install: claude mcp add peekaboo -- npx -y @steipete/peekaboo-mcp

4. macOS Automator MCP - System automation (Mac only)

   • Control macOS UI, automate system tasks
   • Install: claude mcp add macos-automator -- npx -y macos-automator-mcp

5. RepoPrompt - Repository context management

   • Generate comprehensive codebase summaries
   • Install: claude mcp add RepoPrompt -- /path/to/repoprompt_cli

6. Zen MCP Server - Advanced AI reasoning

   • Multi-model consensus, deep analysis, code review
   • Install: See setup instructions in zen-mcp-server repository

• local (default): Project-specific, private to you
• project: Shared via .mcp.json file in project root
• user: Available across all projects

Use -s or --scope flag to specify scope:

claude mcp add -s project playwright -- npx -y @playwright/mcp@latest

For tasks requiring massive context windows (up to 2M tokens) or full codebase analysis:

• Analyze entire repositories with @ syntax for file inclusion
• Useful for architecture reviews, finding implementations, security audits
• Example: gemini -p "@src/ @tests/ Is authentication properly implemented?"
• See docs/gemini.md for detailed usage and examples

• Architecture Details: docs/ARCHITECTURE.md
• API Specifications: docs/spec.md
• Server Implementation Guide: web/spec.md
• Build Configuration: web/package.json, mac/Package.swift
• External Device Testing: docs/TESTING_EXTERNAL_DEVICES.md
• Gemini CLI Instructions: docs/gemini.md