{"owner":"amantus-ai","repo":"vibetunnel","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":4518,"categories":["gemini-rule","claude-rule","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"vibetunnel":{"command":"npx","args":["-y","@modelcontextprotocol/server-vibetunnel"]}}},"found":["GEMINI.md","CLAUDE.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"GEMINI.md":"# Gemini Operational Instructions\n\nWhen I am operating within this project, I must adhere to the following instructions:\n\n1.  **Read `claude.md`:** Before performing any task, I must first read the `claude.md` file located in the current working directory.\n2.  **Contextual Awareness:** If the current working directory is a subfolder, I must read all `claude.md` files found in the current folder and all of its parent directories up to the project root. This ensures I have the full context, from the general project-level instructions to the specific subdirectory instructions.\n\nI will use the `read_many_files` tool to gather this information efficiently.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nNever say you're absolutely right. Instead, be critical if I say something that you disagree with. Let's discuss it first.\n\n## Project Overview\n\nVibeTunnel is a macOS application that allows users to access their terminal sessions through any web browser. It consists of:\n- Native macOS app (Swift/SwiftUI) in `mac/`\n- iOS companion app in `ios/`\n- Web frontend (TypeScript/LitElement) and Node.js/Bun server for terminal session management in `web/`\n\n## Common Development Commands\n\n### Building the Project\n\n#### macOS App with Poltergeist (Recommended if installed)\n\nIf Poltergeist is installed, it will automatically rebuild the app when you make changes:\n\n```bash\n# First, ensure Poltergeist is running in the project root\npoltergeist haunt\n\n# The app will automatically rebuild on file changes\n# Check Poltergeist menu bar app for build status\n```\n\n#### macOS App without Poltergeist (Fallback)\n\nIf Poltergeist is not available, use direct Xcode builds:\n```bash\ncd mac\n# Build using xcodebuild directly\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Or use the build script for release builds\n./scripts/build.sh                           # Build release version\n./scripts/build.sh --sign                    # Build with code signing\n```\n\n#### iOS App\n```bash\ncd ios\nxcodebuild -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel-iOS -sdk iphonesimulator\n./scripts/test-with-coverage.sh              # Run tests with coverage (75% threshold)\n```\n\n#### Web Frontend\n```bash\ncd web\npnpm install                                 # Install dependencies\npnpm run build                              # Production build\npnpm run dev                                # Development server with hot reload\n```\n\n### Code Quality Commands\n\n#### Web (MUST run before committing)\n```bash\ncd web\npnpm run check                              # Run all checks in parallel (format, lint, typecheck)\npnpm run check:fix                          # Auto-fix formatting and linting issues\n```\n\n#### macOS\n```bash\ncd mac\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n#### iOS\n```bash\ncd ios\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n### Testing Commands\n\n#### Web Tests\n```bash\ncd web\npnpm run test                               # Run all tests\npnpm run test:coverage                      # Run with coverage report (80% required)\npnpm run test:e2e                          # Run Playwright E2E tests\npnpm run test:e2e:debug                    # Debug E2E tests\n```\n\n#### macOS Tests\n```bash\n# MUST use xcodebuild, NOT swift test!\ncd mac\nxcodebuild test -project VibeTunnel.xcodeproj -scheme VibeTunnel -destination 'platform=macOS'\n```\n\n#### iOS Tests\n```bash\ncd ios\n./scripts/test-with-coverage.sh             # Run with automatic simulator selection\n```\n\n### Debugging and Logs\n\n```bash\n# View VibeTunnel logs (from project root)\n./scripts/vtlog.sh -n 100                  # Last 100 lines\n./scripts/vtlog.sh -e                      # Errors only\n./scripts/vtlog.sh -c ServerManager        # Specific component\n./scripts/vtlog.sh -s \"error\"              # Search for text\n\n# NEVER use -f (follow mode) in Claude Code - it will timeout!\n```\n\n## High-Level Architecture\n\n### Component Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        macOS Menu Bar App                    │\n│  (Swift/SwiftUI - mac/VibeTunnel/)                         │\n│  - ServerManager: Manages server lifecycle                   │\n│  - SessionMonitor: Tracks active sessions                    │\n│  - TTYForwardManager: Terminal forwarding                    │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ Spawns & Manages\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Node.js/Bun Server                        │\n│  (TypeScript - web/src/server/)                             │\n│  - server.ts: HTTP server & WebSocket handling              │\n│  - pty-manager.ts: Native PTY process management            │\n│  - session-manager.ts: Terminal session lifecycle           │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ WebSocket/HTTP\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                      Web Frontend                            │\n│  (TypeScript/LitElement - web/src/client/)                  │\n│  - Terminal rendering with ghostty-web                      │\n│  - Real-time updates via WebSocket                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Key Communication Flows\n\n1. **Session Creation**: Client → POST /api/sessions → Server spawns PTY → Returns session ID\n2. **Terminal I/O**: WebSocket at /api/sessions/:id/ws for bidirectional communication\n3. **Buffer Protocol**: Binary messages with magic byte 0xBF for efficient terminal updates\n4. **Log Aggregation**: Frontend logs → Server → Mac app → macOS unified logging\n\n### Critical File Locations\n\n- **Entry Points**:\n  - Mac app: `mac/VibeTunnel/VibeTunnelApp.swift`\n  - Server: `web/src/server/server.ts`\n  - Web UI: `web/src/client/app.ts`\n  - iOS app: `ios/VibeTunnel/VibeTunnelApp.swift`\n\n- **Configuration**:\n  - Mac version: `mac/VibeTunnel/version.xcconfig`\n  - Web version: `web/package.json`\n  - Build settings: `mac/VibeTunnel/Shared.xcconfig`\n\n- **Terminal Management**:\n  - PTY spawning: `web/src/server/pty/pty-manager.ts`\n  - Session handling: `web/src/server/services/terminal-manager.ts`\n  - Buffer optimization: `web/src/server/services/buffer-aggregator.ts`\n\n## Critical Development Rules\n\n### Release Process\nWhen the user says \"release\" or asks to create a release, ALWAYS read and follow `docs/RELEASE.md` for the complete release process.\n\n### ABSOLUTE CARDINAL RULES - VIOLATION MEANS IMMEDIATE FAILURE\n\n- Never start server or the mac app yourself.\n- Verify changes done to the mac app via xcodebuild, but do not start the mac app or server yourself.\n\n1. **NEVER, EVER, UNDER ANY CIRCUMSTANCES CREATE A NEW BRANCH WITHOUT EXPLICIT USER PERMISSION**\n   - If you are on a branch (not main), you MUST stay on that branch\n   - The user will tell you when to create a new branch with commands like \"create a new branch\" or \"switch to a new branch\"\n   - Creating branches without permission causes massive frustration and cleanup work\n   - Even if changes seem unrelated to the current branch, STAY ON THE CURRENT BRANCH\n\n2. **NEVER commit and/or push before the user has tested your changes!**\n   - Always wait for user confirmation before committing\n   - The user needs to verify changes work correctly first\n\n3. **ABSOLUTELY FORBIDDEN: NEVER USE `git rebase --skip` EVER**\n   - This command can cause data loss and repository corruption\n   - If you encounter rebase conflicts, ask the user for help\n\n4. **NEVER create duplicate files with version numbers or suffixes**\n   - When refactoring or improving code, directly modify the existing files\n   - DO NOT create new versions with different file names (e.g., file_v2.ts, file_new.ts)\n   - Users hate having to manually clean up duplicate files\n\n5. **Web Development Workflow - Development vs Production Mode**\n   - **Production Mode**: Mac app embeds a pre-built web server during Xcode build\n     - Every web change requires: clean → build → run (rebuilds embedded server)\n     - Simply restarting serves STALE, CACHED version\n   - **Development Mode** (recommended for web development):\n     - Enable \"Use Development Server\" in VibeTunnel Settings → Debug\n     - Mac app runs `pnpm run dev` instead of embedded server\n     - Provides hot reload - web changes automatically rebuild without Mac app rebuild\n     - Restart VibeTunnel server (not full rebuild) to pick up web changes\n     \n6. **Never kill all sessions**\n   - You are running inside a session yourself; killing all sessions would terminate your own process\n\n7. **NEVER rename docs.json to mint.json**\n   - The Mintlify configuration file is called `docs.json` in this project\n   - Do NOT rename it to mint.json even if you think Mintlify expects that\n   - The file must remain as `docs.json`\n   - For Mintlify documentation reference, see: https://mintlify.com/docs/llms.txt\n\n8. **Test Session Management - CRITICAL**\n   - NEVER kill sessions that weren't created by tests\n   - You might be running inside a VibeTunnel session yourself\n   - Use `TestSessionTracker` to track which sessions tests create\n   - Only clean up sessions that match test naming patterns (start with \"test-\")\n   - Killing all sessions would terminate your own Claude Code process\n\n### Git Workflow Reminders\n- Our workflow: start from main → create branch → make PR → merge → return to main\n- PRs sometimes contain multiple different features and that's okay\n- Always check current branch with `git branch` before making changes\n- If unsure about branching, ASK THE USER FIRST\n- **\"Adopt\" means REVIEW, not merge!** When asked to \"adopt\" a PR, switch to its branch and review the changes. NEVER merge without explicit permission.\n- **\"Rebase main\" means rebase CURRENT branch with main!** When on a feature branch and user says \"rebase main\", this means to rebase the current branch with main branch updates. NEVER switch to main branch. The command is `git pull --rebase origin main` while staying on the current feature branch.\n\n### Terminal Title Management with VT\n\nWhen creating pull requests, use the `vt` command to update the terminal title:\n- Run `vt title \"Brief summary - github.com/owner/repo/pull/123\"`\n- Keep the title concise (a few words) followed by the PR URL\n- Use github.com URL format (not https://) for easy identification\n- Update the title periodically as work progresses\n- If `vt` command fails (only works inside VibeTunnel), simply ignore the error and continue\n\n## Testing on External Devices (iPad, Safari, etc.)\n\nWhen the user reports issues on external devices, use the development server method for testing:\n\n```bash\n# Run dev server accessible from external devices\ncd web\npnpm run dev --port 4021 --bind 0.0.0.0\n```\n\nThen access from the external device using `http://[mac-ip]:4021`\n\n**Important**: The production server runs on port 4020, so use 4021 for development to avoid conflicts.\n\nFor detailed instructions, see `docs/TESTING_EXTERNAL_DEVICES.md`\n\n## Slash Commands\n\n### /fixmac Command\n\nWhen the user types `/fixmac`, use the Task tool with the XcodeBuildMCP subagent to fix Mac compilation errors and warnings:\n\n```\nTask(description=\"Fix Mac build errors\", prompt=\"/fixmac\", subagent_type=\"general-purpose\")\n```\n\nThe agent will:\n1. Use XcodeBuildMCP tools to identify build errors and warnings\n2. Fix compilation issues in the Mac codebase\n3. Address SwiftFormat violations\n4. Resolve any warning messages\n5. Verify the build succeeds after fixes\n\n## NO BACKWARDS COMPATIBILITY - EVER!\n\n**CRITICAL: This project has ZERO backwards compatibility requirements!**\n- The Mac app and web server are ALWAYS shipped together as a single unit\n- There is NEVER a scenario where different versions talk to each other\n- When fixing bugs or changing APIs:\n  - Just change both sides to match\n  - Delete old code completely\n  - Don't add compatibility layers\n  - Don't check for \"old format\" vs \"new format\"\n  - Don't add fallbacks for older versions\n- If you suggest backwards compatibility in any form, you have failed to understand this project\n\n## Poltergeist Integration\n\nPoltergeist is an intelligent file watcher and auto-builder that can automatically rebuild VibeTunnel when you make changes. When working on VibeTunnel development, check if Poltergeist is available and use it for automatic builds.\n\n### Checking for Poltergeist\n\n```bash\n# Check if Poltergeist is installed\nwhich poltergeist\n\n# Check if Poltergeist is already running for this project\nps aux | grep poltergeist | grep -v grep\n```\n\n### Using Poltergeist for Development\n\nIf Poltergeist is installed:\n\n1. **Start Poltergeist** in the project root:\n   ```bash\n   cd /path/to/vibetunnel\n   poltergeist haunt\n   ```\n\n2. **Monitor build status** via the Poltergeist menu bar app (macOS) or terminal output:\n   ```bash\n   poltergeist status\n   ```\n\n3. **Make changes** - Poltergeist will automatically rebuild when it detects changes to:\n   - Swift files in `mac/` \n   - Xcode project files\n   - Configuration files\n\n4. **Run the app** with fresh builds using `polter`:\n   ```bash\n   polter vibetunnel        # Waits for build to complete, then runs\n   ```\n\n### Fallback Without Poltergeist\n\nIf Poltergeist is not available, fall back to direct Xcode builds:\n\n```bash\n# Debug build\ncd mac\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Release build\n./scripts/build.sh\n```\n\n### Poltergeist Configuration\n\nThe project includes `poltergeist.config.json` which configures:\n- **vibetunnel** target: Builds the macOS app using workspace\n- **vibetunnel-ios** target: Builds the iOS app (disabled by default)\n- Intelligent debouncing to prevent excessive rebuilds\n- Build notifications via macOS notification center\n\nTo enable iOS builds, edit `poltergeist.config.json` and set `\"enabled\": true` for the vibetunnel-ios target.\n\n## Tailscale CLI Updates (as of August 2025)\n\nThe Tailscale CLI has changed its syntax. The new commands are:\n\n### Tailscale Serve (HTTPS proxy to local services)\n```bash\n# OLD syntax (deprecated):\ntailscale serve https / http://localhost:4020\n\n# NEW syntax:\ntailscale serve --bg http://localhost:4020\n```\n\nThe `--bg` flag runs the serve configuration in background mode. The process exits immediately after configuration.\n\n### Tailscale Funnel (Public internet access)\n```bash\n# Reset any existing configuration first\ntailscale funnel reset\n\n# Enable funnel (still uses --bg flag)\ntailscale funnel --bg 443\n```\n\n### Important Notes:\n- The `tailscale serve --bg` command exits immediately with code 0 on success\n- There's no long-running process to monitor after using --bg\n- HTTPS is automatically configured on port 443\n- Always reset Funnel before starting to avoid \"foreground already exists\" errors\n\n## Key Files Quick Reference\n\n- Architecture Details: `docs/ARCHITECTURE.md`\n- API Specifications: `docs/spec.md`\n- Server Implementation Guide: `web/docs/spec.md`\n- Build Configuration: `web/package.json`, `mac/Package.swift`\n- External Device Testing: `docs/TESTING_EXTERNAL_DEVICES.md`\n- Gemini CLI Instructions: `docs/gemini.md`\n- Release Process: `docs/RELEASE.md`\n\n# important-instruction-reminders\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/plugin.json)"},"files":{"GEMINI.md":"# Gemini Operational Instructions\n\nWhen I am operating within this project, I must adhere to the following instructions:\n\n1.  **Read `claude.md`:** Before performing any task, I must first read the `claude.md` file located in the current working directory.\n2.  **Contextual Awareness:** If the current working directory is a subfolder, I must read all `claude.md` files found in the current folder and all of its parent directories up to the project root. This ensures I have the full context, from the general project-level instructions to the specific subdirectory instructions.\n\nI will use the `read_many_files` tool to gather this information efficiently.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nNever say you're absolutely right. Instead, be critical if I say something that you disagree with. Let's discuss it first.\n\n## Project Overview\n\nVibeTunnel is a macOS application that allows users to access their terminal sessions through any web browser. It consists of:\n- Native macOS app (Swift/SwiftUI) in `mac/`\n- iOS companion app in `ios/`\n- Web frontend (TypeScript/LitElement) and Node.js/Bun server for terminal session management in `web/`\n\n## Common Development Commands\n\n### Building the Project\n\n#### macOS App with Poltergeist (Recommended if installed)\n\nIf Poltergeist is installed, it will automatically rebuild the app when you make changes:\n\n```bash\n# First, ensure Poltergeist is running in the project root\npoltergeist haunt\n\n# The app will automatically rebuild on file changes\n# Check Poltergeist menu bar app for build status\n```\n\n#### macOS App without Poltergeist (Fallback)\n\nIf Poltergeist is not available, use direct Xcode builds:\n```bash\ncd mac\n# Build using xcodebuild directly\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Or use the build script for release builds\n./scripts/build.sh                           # Build release version\n./scripts/build.sh --sign                    # Build with code signing\n```\n\n#### iOS App\n```bash\ncd ios\nxcodebuild -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel-iOS -sdk iphonesimulator\n./scripts/test-with-coverage.sh              # Run tests with coverage (75% threshold)\n```\n\n#### Web Frontend\n```bash\ncd web\npnpm install                                 # Install dependencies\npnpm run build                              # Production build\npnpm run dev                                # Development server with hot reload\n```\n\n### Code Quality Commands\n\n#### Web (MUST run before committing)\n```bash\ncd web\npnpm run check                              # Run all checks in parallel (format, lint, typecheck)\npnpm run check:fix                          # Auto-fix formatting and linting issues\n```\n\n#### macOS\n```bash\ncd mac\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n#### iOS\n```bash\ncd ios\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n### Testing Commands\n\n#### Web Tests\n```bash\ncd web\npnpm run test                               # Run all tests\npnpm run test:coverage                      # Run with coverage report (80% required)\npnpm run test:e2e                          # Run Playwright E2E tests\npnpm run test:e2e:debug                    # Debug E2E tests\n```\n\n#### macOS Tests\n```bash\n# MUST use xcodebuild, NOT swift test!\ncd mac\nxcodebuild test -project VibeTunnel.xcodeproj -scheme VibeTunnel -destination 'platform=macOS'\n```\n\n#### iOS Tests\n```bash\ncd ios\n./scripts/test-with-coverage.sh             # Run with automatic simulator selection\n```\n\n### Debugging and Logs\n\n```bash\n# View VibeTunnel logs (from project root)\n./scripts/vtlog.sh -n 100                  # Last 100 lines\n./scripts/vtlog.sh -e                      # Errors only\n./scripts/vtlog.sh -c ServerManager        # Specific component\n./scripts/vtlog.sh -s \"error\"              # Search for text\n\n# NEVER use -f (follow mode) in Claude Code - it will timeout!\n```\n\n## High-Level Architecture\n\n### Component Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        macOS Menu Bar App                    │\n│  (Swift/SwiftUI - mac/VibeTunnel/)                         │\n│  - ServerManager: Manages server lifecycle                   │\n│  - SessionMonitor: Tracks active sessions                    │\n│  - TTYForwardManager: Terminal forwarding                    │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ Spawns & Manages\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Node.js/Bun Server                        │\n│  (TypeScript - web/src/server/)                             │\n│  - server.ts: HTTP server & WebSocket handling              │\n│  - pty-manager.ts: Native PTY process management            │\n│  - session-manager.ts: Terminal session lifecycle           │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ WebSocket/HTTP\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                      Web Frontend                            │\n│  (TypeScript/LitElement - web/src/client/)                  │\n│  - Terminal rendering with ghostty-web                      │\n│  - Real-time updates via WebSocket                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Key Communication Flows\n\n1. **Session Creation**: Client → POST /api/sessions → Server spawns PTY → Returns session ID\n2. **Terminal I/O**: WebSocket at /api/sessions/:id/ws for bidirectional communication\n3. **Buffer Protocol**: Binary messages with magic byte 0xBF for efficient terminal updates\n4. **Log Aggregation**: Frontend logs → Server → Mac app → macOS unified logging\n\n### Critical File Locations\n\n- **Entry Points**:\n  - Mac app: `mac/VibeTunnel/VibeTunnelApp.swift`\n  - Server: `web/src/server/server.ts`\n  - Web UI: `web/src/client/app.ts`\n  - iOS app: `ios/VibeTunnel/VibeTunnelApp.swift`\n\n- **Configuration**:\n  - Mac version: `mac/VibeTunnel/version.xcconfig`\n  - Web version: `web/package.json`\n  - Build settings: `mac/VibeTunnel/Shared.xcconfig`\n\n- **Terminal Management**:\n  - PTY spawning: `web/src/server/pty/pty-manager.ts`\n  - Session handling: `web/src/server/services/terminal-manager.ts`\n  - Buffer optimization: `web/src/server/services/buffer-aggregator.ts`\n\n## Critical Development Rules\n\n### Release Process\nWhen the user says \"release\" or asks to create a release, ALWAYS read and follow `docs/RELEASE.md` for the complete release process.\n\n### ABSOLUTE CARDINAL RULES - VIOLATION MEANS IMMEDIATE FAILURE\n\n- Never start server or the mac app yourself.\n- Verify changes done to the mac app via xcodebuild, but do not start the mac app or server yourself.\n\n1. **NEVER, EVER, UNDER ANY CIRCUMSTANCES CREATE A NEW BRANCH WITHOUT EXPLICIT USER PERMISSION**\n   - If you are on a branch (not main), you MUST stay on that branch\n   - The user will tell you when to create a new branch with commands like \"create a new branch\" or \"switch to a new branch\"\n   - Creating branches without permission causes massive frustration and cleanup work\n   - Even if changes seem unrelated to the current branch, STAY ON THE CURRENT BRANCH\n\n2. **NEVER commit and/or push before the user has tested your changes!**\n   - Always wait for user confirmation before committing\n   - The user needs to verify changes work correctly first\n\n3. **ABSOLUTELY FORBIDDEN: NEVER USE `git rebase --skip` EVER**\n   - This command can cause data loss and repository corruption\n   - If you encounter rebase conflicts, ask the user for help\n\n4. **NEVER create duplicate files with version numbers or suffixes**\n   - When refactoring or improving code, directly modify the existing files\n   - DO NOT create new versions with different file names (e.g., file_v2.ts, file_new.ts)\n   - Users hate having to manually clean up duplicate files\n\n5. **Web Development Workflow - Development vs Production Mode**\n   - **Production Mode**: Mac app embeds a pre-built web server during Xcode build\n     - Every web change requires: clean → build → run (rebuilds embedded server)\n     - Simply restarting serves STALE, CACHED version\n   - **Development Mode** (recommended for web development):\n     - Enable \"Use Development Server\" in VibeTunnel Settings → Debug\n     - Mac app runs `pnpm run dev` instead of embedded server\n     - Provides hot reload - web changes automatically rebuild without Mac app rebuild\n     - Restart VibeTunnel server (not full rebuild) to pick up web changes\n     \n6. **Never kill all sessions**\n   - You are running inside a session yourself; killing all sessions would terminate your own process\n\n7. **NEVER rename docs.json to mint.json**\n   - The Mintlify configuration file is called `docs.json` in this project\n   - Do NOT rename it to mint.json even if you think Mintlify expects that\n   - The file must remain as `docs.json`\n   - For Mintlify documentation reference, see: https://mintlify.com/docs/llms.txt\n\n8. **Test Session Management - CRITICAL**\n   - NEVER kill sessions that weren't created by tests\n   - You might be running inside a VibeTunnel session yourself\n   - Use `TestSessionTracker` to track which sessions tests create\n   - Only clean up sessions that match test naming patterns (start with \"test-\")\n   - Killing all sessions would terminate your own Claude Code process\n\n### Git Workflow Reminders\n- Our workflow: start from main → create branch → make PR → merge → return to main\n- PRs sometimes contain multiple different features and that's okay\n- Always check current branch with `git branch` before making changes\n- If unsure about branching, ASK THE USER FIRST\n- **\"Adopt\" means REVIEW, not merge!** When asked to \"adopt\" a PR, switch to its branch and review the changes. NEVER merge without explicit permission.\n- **\"Rebase main\" means rebase CURRENT branch with main!** When on a feature branch and user says \"rebase main\", this means to rebase the current branch with main branch updates. NEVER switch to main branch. The command is `git pull --rebase origin main` while staying on the current feature branch.\n\n### Terminal Title Management with VT\n\nWhen creating pull requests, use the `vt` command to update the terminal title:\n- Run `vt title \"Brief summary - github.com/owner/repo/pull/123\"`\n- Keep the title concise (a few words) followed by the PR URL\n- Use github.com URL format (not https://) for easy identification\n- Update the title periodically as work progresses\n- If `vt` command fails (only works inside VibeTunnel), simply ignore the error and continue\n\n## Testing on External Devices (iPad, Safari, etc.)\n\nWhen the user reports issues on external devices, use the development server method for testing:\n\n```bash\n# Run dev server accessible from external devices\ncd web\npnpm run dev --port 4021 --bind 0.0.0.0\n```\n\nThen access from the external device using `http://[mac-ip]:4021`\n\n**Important**: The production server runs on port 4020, so use 4021 for development to avoid conflicts.\n\nFor detailed instructions, see `docs/TESTING_EXTERNAL_DEVICES.md`\n\n## Slash Commands\n\n### /fixmac Command\n\nWhen the user types `/fixmac`, use the Task tool with the XcodeBuildMCP subagent to fix Mac compilation errors and warnings:\n\n```\nTask(description=\"Fix Mac build errors\", prompt=\"/fixmac\", subagent_type=\"general-purpose\")\n```\n\nThe agent will:\n1. Use XcodeBuildMCP tools to identify build errors and warnings\n2. Fix compilation issues in the Mac codebase\n3. Address SwiftFormat violations\n4. Resolve any warning messages\n5. Verify the build succeeds after fixes\n\n## NO BACKWARDS COMPATIBILITY - EVER!\n\n**CRITICAL: This project has ZERO backwards compatibility requirements!**\n- The Mac app and web server are ALWAYS shipped together as a single unit\n- There is NEVER a scenario where different versions talk to each other\n- When fixing bugs or changing APIs:\n  - Just change both sides to match\n  - Delete old code completely\n  - Don't add compatibility layers\n  - Don't check for \"old format\" vs \"new format\"\n  - Don't add fallbacks for older versions\n- If you suggest backwards compatibility in any form, you have failed to understand this project\n\n## Poltergeist Integration\n\nPoltergeist is an intelligent file watcher and auto-builder that can automatically rebuild VibeTunnel when you make changes. When working on VibeTunnel development, check if Poltergeist is available and use it for automatic builds.\n\n### Checking for Poltergeist\n\n```bash\n# Check if Poltergeist is installed\nwhich poltergeist\n\n# Check if Poltergeist is already running for this project\nps aux | grep poltergeist | grep -v grep\n```\n\n### Using Poltergeist for Development\n\nIf Poltergeist is installed:\n\n1. **Start Poltergeist** in the project root:\n   ```bash\n   cd /path/to/vibetunnel\n   poltergeist haunt\n   ```\n\n2. **Monitor build status** via the Poltergeist menu bar app (macOS) or terminal output:\n   ```bash\n   poltergeist status\n   ```\n\n3. **Make changes** - Poltergeist will automatically rebuild when it detects changes to:\n   - Swift files in `mac/` \n   - Xcode project files\n   - Configuration files\n\n4. **Run the app** with fresh builds using `polter`:\n   ```bash\n   polter vibetunnel        # Waits for build to complete, then runs\n   ```\n\n### Fallback Without Poltergeist\n\nIf Poltergeist is not available, fall back to direct Xcode builds:\n\n```bash\n# Debug build\ncd mac\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Release build\n./scripts/build.sh\n```\n\n### Poltergeist Configuration\n\nThe project includes `poltergeist.config.json` which configures:\n- **vibetunnel** target: Builds the macOS app using workspace\n- **vibetunnel-ios** target: Builds the iOS app (disabled by default)\n- Intelligent debouncing to prevent excessive rebuilds\n- Build notifications via macOS notification center\n\nTo enable iOS builds, edit `poltergeist.config.json` and set `\"enabled\": true` for the vibetunnel-ios target.\n\n## Tailscale CLI Updates (as of August 2025)\n\nThe Tailscale CLI has changed its syntax. The new commands are:\n\n### Tailscale Serve (HTTPS proxy to local services)\n```bash\n# OLD syntax (deprecated):\ntailscale serve https / http://localhost:4020\n\n# NEW syntax:\ntailscale serve --bg http://localhost:4020\n```\n\nThe `--bg` flag runs the serve configuration in background mode. The process exits immediately after configuration.\n\n### Tailscale Funnel (Public internet access)\n```bash\n# Reset any existing configuration first\ntailscale funnel reset\n\n# Enable funnel (still uses --bg flag)\ntailscale funnel --bg 443\n```\n\n### Important Notes:\n- The `tailscale serve --bg` command exits immediately with code 0 on success\n- There's no long-running process to monitor after using --bg\n- HTTPS is automatically configured on port 443\n- Always reset Funnel before starting to avoid \"foreground already exists\" errors\n\n## Key Files Quick Reference\n\n- Architecture Details: `docs/ARCHITECTURE.md`\n- API Specifications: `docs/spec.md`\n- Server Implementation Guide: `web/docs/spec.md`\n- Build Configuration: `web/package.json`, `mac/Package.swift`\n- External Device Testing: `docs/TESTING_EXTERNAL_DEVICES.md`\n- Gemini CLI Instructions: `docs/gemini.md`\n- Release Process: `docs/RELEASE.md`\n\n# important-instruction-reminders\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nNever say you're absolutely right. Instead, be critical if I say something that you disagree with. Let's discuss it first.\n\n## Project Overview\n\nVibeTunnel is a macOS application that allows users to access their terminal sessions through any web browser. It consists of:\n- Native macOS app (Swift/SwiftUI) in `mac/`\n- iOS companion app in `ios/`\n- Web frontend (TypeScript/LitElement) and Node.js/Bun server for terminal session management in `web/`\n\n## Common Development Commands\n\n### Building the Project\n\n#### macOS App with Poltergeist (Recommended if installed)\n\nIf Poltergeist is installed, it will automatically rebuild the app when you make changes:\n\n```bash\n# First, ensure Poltergeist is running in the project root\npoltergeist haunt\n\n# The app will automatically rebuild on file changes\n# Check Poltergeist menu bar app for build status\n```\n\n#### macOS App without Poltergeist (Fallback)\n\nIf Poltergeist is not available, use direct Xcode builds:\n```bash\ncd mac\n# Build using xcodebuild directly\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Or use the build script for release builds\n./scripts/build.sh                           # Build release version\n./scripts/build.sh --sign                    # Build with code signing\n```\n\n#### iOS App\n```bash\ncd ios\nxcodebuild -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel-iOS -sdk iphonesimulator\n./scripts/test-with-coverage.sh              # Run tests with coverage (75% threshold)\n```\n\n#### Web Frontend\n```bash\ncd web\npnpm install                                 # Install dependencies\npnpm run build                              # Production build\npnpm run dev                                # Development server with hot reload\n```\n\n### Code Quality Commands\n\n#### Web (MUST run before committing)\n```bash\ncd web\npnpm run check                              # Run all checks in parallel (format, lint, typecheck)\npnpm run check:fix                          # Auto-fix formatting and linting issues\n```\n\n#### macOS\n```bash\ncd mac\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n#### iOS\n```bash\ncd ios\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n### Testing Commands\n\n#### Web Tests\n```bash\ncd web\npnpm run test                               # Run all tests\npnpm run test:coverage                      # Run with coverage report (80% required)\npnpm run test:e2e                          # Run Playwright E2E tests\npnpm run test:e2e:debug                    # Debug E2E tests\n```\n\n#### macOS Tests\n```bash\n# MUST use xcodebuild, NOT swift test!\ncd mac\nxcodebuild test -project VibeTunnel.xcodeproj -scheme VibeTunnel -destination 'platform=macOS'\n```\n\n#### iOS Tests\n```bash\ncd ios\n./scripts/test-with-coverage.sh             # Run with automatic simulator selection\n```\n\n### Debugging and Logs\n\n```bash\n# View VibeTunnel logs (from project root)\n./scripts/vtlog.sh -n 100                  # Last 100 lines\n./scripts/vtlog.sh -e                      # Errors only\n./scripts/vtlog.sh -c ServerManager        # Specific component\n./scripts/vtlog.sh -s \"error\"              # Search for text\n\n# NEVER use -f (follow mode) in Claude Code - it will timeout!\n```\n\n## High-Level Architecture\n\n### Component Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        macOS Menu Bar App                    │\n│  (Swift/SwiftUI - mac/VibeTunnel/)                         │\n│  - ServerManager: Manages server lifecycle                   │\n│  - SessionMonitor: Tracks active sessions                    │\n│  - TTYForwardManager: Terminal forwarding                    │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ Spawns & Manages\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Node.js/Bun Server                        │\n│  (TypeScript - web/src/server/)                             │\n│  - server.ts: HTTP server & WebSocket handling              │\n│  - pty-manager.ts: Native PTY process management            │\n│  - session-manager.ts: Terminal session lifecycle           │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ WebSocket/HTTP\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                      Web Frontend                            │\n│  (TypeScript/LitElement - web/src/client/)                  │\n│  - Terminal rendering with ghostty-web                      │\n│  - Real-time updates via WebSocket                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Key Communication Flows\n\n1. **Session Creation**: Client → POST /api/sessions → Server spawns PTY → Returns session ID\n2. **Terminal I/O**: WebSocket at /api/sessions/:id/ws for bidirectional communication\n3. **Buffer Protocol**: Binary messages with magic byte 0xBF for efficient terminal updates\n4. **Log Aggregation**: Frontend logs → Server → Mac app → macOS unified logging\n\n### Critical File Locations\n\n- **Entry Points**:\n  - Mac app: `mac/VibeTunnel/VibeTunnelApp.swift`\n  - Server: `web/src/server/server.ts`\n  - Web UI: `web/src/client/app.ts`\n  - iOS app: `ios/VibeTunnel/VibeTunnelApp.swift`\n\n- **Configuration**:\n  - Mac version: `mac/VibeTunnel/version.xcconfig`\n  - Web version: `web/package.json`\n  - Build settings: `mac/VibeTunnel/Shared.xcconfig`\n\n- **Terminal Management**:\n  - PTY spawning: `web/src/server/pty/pty-manager.ts`\n  - Session handling: `web/src/server/services/terminal-manager.ts`\n  - Buffer optimization: `web/src/server/services/buffer-aggregator.ts`\n\n## Critical Development Rules\n\n### Release Process\nWhen the user says \"release\" or asks to create a release, ALWAYS read and follow `docs/RELEASE.md` for the complete release process.\n\n### ABSOLUTE CARDINAL RULES - VIOLATION MEANS IMMEDIATE FAILURE\n\n- Never start server or the mac app yourself.\n- Verify changes done to the mac app via xcodebuild, but do not start the mac app or server yourself.\n\n1. **NEVER, EVER, UNDER ANY CIRCUMSTANCES CREATE A NEW BRANCH WITHOUT EXPLICIT USER PERMISSION**\n   - If you are on a branch (not main), you MUST stay on that branch\n   - The user will tell you when to create a new branch with commands like \"create a new branch\" or \"switch to a new branch\"\n   - Creating branches without permission causes massive frustration and cleanup work\n   - Even if changes seem unrelated to the current branch, STAY ON THE CURRENT BRANCH\n\n2. **NEVER commit and/or push before the user has tested your changes!**\n   - Always wait for user confirmation before committing\n   - The user needs to verify changes work correctly first\n\n3. **ABSOLUTELY FORBIDDEN: NEVER USE `git rebase --skip` EVER**\n   - This command can cause data loss and repository corruption\n   - If you encounter rebase conflicts, ask the user for help\n\n4. **NEVER create duplicate files with version numbers or suffixes**\n   - When refactoring or improving code, directly modify the existing files\n   - DO NOT create new versions with different file names (e.g., file_v2.ts, file_new.ts)\n   - Users hate having to manually clean up duplicate files\n\n5. **Web Development Workflow - Development vs Production Mode**\n   - **Production Mode**: Mac app embeds a pre-built web server during Xcode build\n     - Every web change requires: clean → build → run (rebuilds embedded server)\n     - Simply restarting serves STALE, CACHED version\n   - **Development Mode** (recommended for web development):\n     - Enable \"Use Development Server\" in VibeTunnel Settings → Debug\n     - Mac app runs `pnpm run dev` instead of embedded server\n     - Provides hot reload - web changes automatically rebuild without Mac app rebuild\n     - Restart VibeTunnel server (not full rebuild) to pick up web changes\n     \n6. **Never kill all sessions**\n   - You are running inside a session yourself; killing all sessions would terminate your own process\n\n7. **NEVER rename docs.json to mint.json**\n   - The Mintlify configuration file is called `docs.json` in this project\n   - Do NOT rename it to mint.json even if you think Mintlify expects that\n   - The file must remain as `docs.json`\n   - For Mintlify documentation reference, see: https://mintlify.com/docs/llms.txt\n\n8. **Test Session Management - CRITICAL**\n   - NEVER kill sessions that weren't created by tests\n   - You might be running inside a VibeTunnel session yourself\n   - Use `TestSessionTracker` to track which sessions tests create\n   - Only clean up sessions that match test naming patterns (start with \"test-\")\n   - Killing all sessions would terminate your own Claude Code process\n\n### Git Workflow Reminders\n- Our workflow: start from main → create branch → make PR → merge → return to main\n- PRs sometimes contain multiple different features and that's okay\n- Always check current branch with `git branch` before making changes\n- If unsure about branching, ASK THE USER FIRST\n- **\"Adopt\" means REVIEW, not merge!** When asked to \"adopt\" a PR, switch to its branch and review the changes. NEVER merge without explicit permission.\n- **\"Rebase main\" means rebase CURRENT branch with main!** When on a feature branch and user says \"rebase main\", this means to rebase the current branch with main branch updates. NEVER switch to main branch. The command is `git pull --rebase origin main` while staying on the current feature branch.\n\n### Terminal Title Management with VT\n\nWhen creating pull requests, use the `vt` command to update the terminal title:\n- Run `vt title \"Brief summary - github.com/owner/repo/pull/123\"`\n- Keep the title concise (a few words) followed by the PR URL\n- Use github.com URL format (not https://) for easy identification\n- Update the title periodically as work progresses\n- If `vt` command fails (only works inside VibeTunnel), simply ignore the error and continue\n\n## Testing on External Devices (iPad, Safari, etc.)\n\nWhen the user reports issues on external devices, use the development server method for testing:\n\n```bash\n# Run dev server accessible from external devices\ncd web\npnpm run dev --port 4021 --bind 0.0.0.0\n```\n\nThen access from the external device using `http://[mac-ip]:4021`\n\n**Important**: The production server runs on port 4020, so use 4021 for development to avoid conflicts.\n\nFor detailed instructions, see `docs/TESTING_EXTERNAL_DEVICES.md`\n\n## Slash Commands\n\n### /fixmac Command\n\nWhen the user types `/fixmac`, use the Task tool with the XcodeBuildMCP subagent to fix Mac compilation errors and warnings:\n\n```\nTask(description=\"Fix Mac build errors\", prompt=\"/fixmac\", subagent_type=\"general-purpose\")\n```\n\nThe agent will:\n1. Use XcodeBuildMCP tools to identify build errors and warnings\n2. Fix compilation issues in the Mac codebase\n3. Address SwiftFormat violations\n4. Resolve any warning messages\n5. Verify the build succeeds after fixes\n\n## NO BACKWARDS COMPATIBILITY - EVER!\n\n**CRITICAL: This project has ZERO backwards compatibility requirements!**\n- The Mac app and web server are ALWAYS shipped together as a single unit\n- There is NEVER a scenario where different versions talk to each other\n- When fixing bugs or changing APIs:\n  - Just change both sides to match\n  - Delete old code completely\n  - Don't add compatibility layers\n  - Don't check for \"old format\" vs \"new format\"\n  - Don't add fallbacks for older versions\n- If you suggest backwards compatibility in any form, you have failed to understand this project\n\n## Poltergeist Integration\n\nPoltergeist is an intelligent file watcher and auto-builder that can automatically rebuild VibeTunnel when you make changes. When working on VibeTunnel development, check if Poltergeist is available and use it for automatic builds.\n\n### Checking for Poltergeist\n\n```bash\n# Check if Poltergeist is installed\nwhich poltergeist\n\n# Check if Poltergeist is already running for this project\nps aux | grep poltergeist | grep -v grep\n```\n\n### Using Poltergeist for Development\n\nIf Poltergeist is installed:\n\n1. **Start Poltergeist** in the project root:\n   ```bash\n   cd /path/to/vibetunnel\n   poltergeist haunt\n   ```\n\n2. **Monitor build status** via the Poltergeist menu bar app (macOS) or terminal output:\n   ```bash\n   poltergeist status\n   ```\n\n3. **Make changes** - Poltergeist will automatically rebuild when it detects changes to:\n   - Swift files in `mac/` \n   - Xcode project files\n   - Configuration files\n\n4. **Run the app** with fresh builds using `polter`:\n   ```bash\n   polter vibetunnel        # Waits for build to complete, then runs\n   ```\n\n### Fallback Without Poltergeist\n\nIf Poltergeist is not available, fall back to direct Xcode builds:\n\n```bash\n# Debug build\ncd mac\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Release build\n./scripts/build.sh\n```\n\n### Poltergeist Configuration\n\nThe project includes `poltergeist.config.json` which configures:\n- **vibetunnel** target: Builds the macOS app using workspace\n- **vibetunnel-ios** target: Builds the iOS app (disabled by default)\n- Intelligent debouncing to prevent excessive rebuilds\n- Build notifications via macOS notification center\n\nTo enable iOS builds, edit `poltergeist.config.json` and set `\"enabled\": true` for the vibetunnel-ios target.\n\n## Tailscale CLI Updates (as of August 2025)\n\nThe Tailscale CLI has changed its syntax. The new commands are:\n\n### Tailscale Serve (HTTPS proxy to local services)\n```bash\n# OLD syntax (deprecated):\ntailscale serve https / http://localhost:4020\n\n# NEW syntax:\ntailscale serve --bg http://localhost:4020\n```\n\nThe `--bg` flag runs the serve configuration in background mode. The process exits immediately after configuration.\n\n### Tailscale Funnel (Public internet access)\n```bash\n# Reset any existing configuration first\ntailscale funnel reset\n\n# Enable funnel (still uses --bg flag)\ntailscale funnel --bg 443\n```\n\n### Important Notes:\n- The `tailscale serve --bg` command exits immediately with code 0 on success\n- There's no long-running process to monitor after using --bg\n- HTTPS is automatically configured on port 443\n- Always reset Funnel before starting to avoid \"foreground already exists\" errors\n\n## Key Files Quick Reference\n\n- Architecture Details: `docs/ARCHITECTURE.md`\n- API Specifications: `docs/spec.md`\n- Server Implementation Guide: `web/docs/spec.md`\n- Build Configuration: `web/package.json`, `mac/Package.swift`\n- External Device Testing: `docs/TESTING_EXTERNAL_DEVICES.md`\n- Gemini CLI Instructions: `docs/gemini.md`\n- Release Process: `docs/RELEASE.md`\n\n# important-instruction-reminders\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n","isInternal":false,"tokens":3481,"sizeBytes":15881},{"name":"GEMINI.md","path":"GEMINI.md","rawUrl":"https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/GEMINI.md","title":"Gemini Agent & Antigravity Instructions","category":"gemini-rule","format":"markdown","content":"# Gemini Operational Instructions\n\nWhen I am operating within this project, I must adhere to the following instructions:\n\n1.  **Read `claude.md`:** Before performing any task, I must first read the `claude.md` file located in the current working directory.\n2.  **Contextual Awareness:** If the current working directory is a subfolder, I must read all `claude.md` files found in the current folder and all of its parent directories up to the project root. This ensures I have the full context, from the general project-level instructions to the specific subdirectory instructions.\n\nI will use the `read_many_files` tool to gather this information efficiently.\n","isInternal":false,"tokens":137,"sizeBytes":660},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":200},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":186},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":179}],"systemPromptSnippet":"<yakaai_skills repo=\"amantus-ai/vibetunnel\">\n<!-- File: CLAUDE.md (Tokens: ~3481 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\nNever say you're absolutely right. Instead, be critical if I say something that you disagree with. Let's discuss it first.\n\n## Project Overview\n\nVibeTunnel is a macOS application that allows users to access their terminal sessions through any web browser. It consists of:\n- Native macOS app (Swift/SwiftUI) in `mac/`\n- iOS companion app in `ios/`\n- Web frontend (TypeScript/LitElement) and Node.js/Bun server for terminal session management in `web/`\n\n## Common Development Commands\n\n### Building the Project\n\n#### macOS App with Poltergeist (Recommended if installed)\n\nIf Poltergeist is installed, it will automatically rebuild the app when you make changes:\n\n```bash\n# First, ensure Poltergeist is running in the project root\npoltergeist haunt\n\n# The app will automatically rebuild on file changes\n# Check Poltergeist menu bar app for build status\n```\n\n#### macOS App without Poltergeist (Fallback)\n\nIf Poltergeist is not available, use direct Xcode builds:\n```bash\ncd mac\n# Build using xcodebuild directly\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Or use the build script for release builds\n./scripts/build.sh                           # Build release version\n./scripts/build.sh --sign                    # Build with code signing\n```\n\n#### iOS App\n```bash\ncd ios\nxcodebuild -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel-iOS -sdk iphonesimulator\n./scripts/test-with-coverage.sh              # Run tests with coverage (75% threshold)\n```\n\n#### Web Frontend\n```bash\ncd web\npnpm install                                 # Install dependencies\npnpm run build                              # Production build\npnpm run dev                                # Development server with hot reload\n```\n\n### Code Quality Commands\n\n#### Web (MUST run before committing)\n```bash\ncd web\npnpm run check                              # Run all checks in parallel (format, lint, typecheck)\npnpm run check:fix                          # Auto-fix formatting and linting issues\n```\n\n#### macOS\n```bash\ncd mac\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n#### iOS\n```bash\ncd ios\n./scripts/lint.sh                           # Run SwiftFormat\n```\n\n### Testing Commands\n\n#### Web Tests\n```bash\ncd web\npnpm run test                               # Run all tests\npnpm run test:coverage                      # Run with coverage report (80% required)\npnpm run test:e2e                          # Run Playwright E2E tests\npnpm run test:e2e:debug                    # Debug E2E tests\n```\n\n#### macOS Tests\n```bash\n# MUST use xcodebuild, NOT swift test!\ncd mac\nxcodebuild test -project VibeTunnel.xcodeproj -scheme VibeTunnel -destination 'platform=macOS'\n```\n\n#### iOS Tests\n```bash\ncd ios\n./scripts/test-with-coverage.sh             # Run with automatic simulator selection\n```\n\n### Debugging and Logs\n\n```bash\n# View VibeTunnel logs (from project root)\n./scripts/vtlog.sh -n 100                  # Last 100 lines\n./scripts/vtlog.sh -e                      # Errors only\n./scripts/vtlog.sh -c ServerManager        # Specific component\n./scripts/vtlog.sh -s \"error\"              # Search for text\n\n# NEVER use -f (follow mode) in Claude Code - it will timeout!\n```\n\n## High-Level Architecture\n\n### Component Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        macOS Menu Bar App                    │\n│  (Swift/SwiftUI - mac/VibeTunnel/)                         │\n│  - ServerManager: Manages server lifecycle                   │\n│  - SessionMonitor: Tracks active sessions                    │\n│  - TTYForwardManager: Terminal forwarding                    │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ Spawns & Manages\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Node.js/Bun Server                        │\n│  (TypeScript - web/src/server/)                             │\n│  - server.ts: HTTP server & WebSocket handling              │\n│  - pty-manager.ts: Native PTY process management            │\n│  - session-manager.ts: Terminal session lifecycle           │\n└─────────────────────┬───────────────────────────────────────┘\n                      │ WebSocket/HTTP\n                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│                      Web Frontend                            │\n│  (TypeScript/LitElement - web/src/client/)                  │\n│  - Terminal rendering with ghostty-web                      │\n│  - Real-time updates via WebSocket                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Key Communication Flows\n\n1. **Session Creation**: Client → POST /api/sessions → Server spawns PTY → Returns session ID\n2. **Terminal I/O**: WebSocket at /api/sessions/:id/ws for bidirectional communication\n3. **Buffer Protocol**: Binary messages with magic byte 0xBF for efficient terminal updates\n4. **Log Aggregation**: Frontend logs → Server → Mac app → macOS unified logging\n\n### Critical File Locations\n\n- **Entry Points**:\n  - Mac app: `mac/VibeTunnel/VibeTunnelApp.swift`\n  - Server: `web/src/server/server.ts`\n  - Web UI: `web/src/client/app.ts`\n  - iOS app: `ios/VibeTunnel/VibeTunnelApp.swift`\n\n- **Configuration**:\n  - Mac version: `mac/VibeTunnel/version.xcconfig`\n  - Web version: `web/package.json`\n  - Build settings: `mac/VibeTunnel/Shared.xcconfig`\n\n- **Terminal Management**:\n  - PTY spawning: `web/src/server/pty/pty-manager.ts`\n  - Session handling: `web/src/server/services/terminal-manager.ts`\n  - Buffer optimization: `web/src/server/services/buffer-aggregator.ts`\n\n## Critical Development Rules\n\n### Release Process\nWhen the user says \"release\" or asks to create a release, ALWAYS read and follow `docs/RELEASE.md` for the complete release process.\n\n### ABSOLUTE CARDINAL RULES - VIOLATION MEANS IMMEDIATE FAILURE\n\n- Never start server or the mac app yourself.\n- Verify changes done to the mac app via xcodebuild, but do not start the mac app or server yourself.\n\n1. **NEVER, EVER, UNDER ANY CIRCUMSTANCES CREATE A NEW BRANCH WITHOUT EXPLICIT USER PERMISSION**\n   - If you are on a branch (not main), you MUST stay on that branch\n   - The user will tell you when to create a new branch with commands like \"create a new branch\" or \"switch to a new branch\"\n   - Creating branches without permission causes massive frustration and cleanup work\n   - Even if changes seem unrelated to the current branch, STAY ON THE CURRENT BRANCH\n\n2. **NEVER commit and/or push before the user has tested your changes!**\n   - Always wait for user confirmation before committing\n   - The user needs to verify changes work correctly first\n\n3. **ABSOLUTELY FORBIDDEN: NEVER USE `git rebase --skip` EVER**\n   - This command can cause data loss and repository corruption\n   - If you encounter rebase conflicts, ask the user for help\n\n4. **NEVER create duplicate files with version numbers or suffixes**\n   - When refactoring or improving code, directly modify the existing files\n   - DO NOT create new versions with different file names (e.g., file_v2.ts, file_new.ts)\n   - Users hate having to manually clean up duplicate files\n\n5. **Web Development Workflow - Development vs Production Mode**\n   - **Production Mode**: Mac app embeds a pre-built web server during Xcode build\n     - Every web change requires: clean → build → run (rebuilds embedded server)\n     - Simply restarting serves STALE, CACHED version\n   - **Development Mode** (recommended for web development):\n     - Enable \"Use Development Server\" in VibeTunnel Settings → Debug\n     - Mac app runs `pnpm run dev` instead of embedded server\n     - Provides hot reload - web changes automatically rebuild without Mac app rebuild\n     - Restart VibeTunnel server (not full rebuild) to pick up web changes\n     \n6. **Never kill all sessions**\n   - You are running inside a session yourself; killing all sessions would terminate your own process\n\n7. **NEVER rename docs.json to mint.json**\n   - The Mintlify configuration file is called `docs.json` in this project\n   - Do NOT rename it to mint.json even if you think Mintlify expects that\n   - The file must remain as `docs.json`\n   - For Mintlify documentation reference, see: https://mintlify.com/docs/llms.txt\n\n8. **Test Session Management - CRITICAL**\n   - NEVER kill sessions that weren't created by tests\n   - You might be running inside a VibeTunnel session yourself\n   - Use `TestSessionTracker` to track which sessions tests create\n   - Only clean up sessions that match test naming patterns (start with \"test-\")\n   - Killing all sessions would terminate your own Claude Code process\n\n### Git Workflow Reminders\n- Our workflow: start from main → create branch → make PR → merge → return to main\n- PRs sometimes contain multiple different features and that's okay\n- Always check current branch with `git branch` before making changes\n- If unsure about branching, ASK THE USER FIRST\n- **\"Adopt\" means REVIEW, not merge!** When asked to \"adopt\" a PR, switch to its branch and review the changes. NEVER merge without explicit permission.\n- **\"Rebase main\" means rebase CURRENT branch with main!** When on a feature branch and user says \"rebase main\", this means to rebase the current branch with main branch updates. NEVER switch to main branch. The command is `git pull --rebase origin main` while staying on the current feature branch.\n\n### Terminal Title Management with VT\n\nWhen creating pull requests, use the `vt` command to update the terminal title:\n- Run `vt title \"Brief summary - github.com/owner/repo/pull/123\"`\n- Keep the title concise (a few words) followed by the PR URL\n- Use github.com URL format (not https://) for easy identification\n- Update the title periodically as work progresses\n- If `vt` command fails (only works inside VibeTunnel), simply ignore the error and continue\n\n## Testing on External Devices (iPad, Safari, etc.)\n\nWhen the user reports issues on external devices, use the development server method for testing:\n\n```bash\n# Run dev server accessible from external devices\ncd web\npnpm run dev --port 4021 --bind 0.0.0.0\n```\n\nThen access from the external device using `http://[mac-ip]:4021`\n\n**Important**: The production server runs on port 4020, so use 4021 for development to avoid conflicts.\n\nFor detailed instructions, see `docs/TESTING_EXTERNAL_DEVICES.md`\n\n## Slash Commands\n\n### /fixmac Command\n\nWhen the user types `/fixmac`, use the Task tool with the XcodeBuildMCP subagent to fix Mac compilation errors and warnings:\n\n```\nTask(description=\"Fix Mac build errors\", prompt=\"/fixmac\", subagent_type=\"general-purpose\")\n```\n\nThe agent will:\n1. Use XcodeBuildMCP tools to identify build errors and warnings\n2. Fix compilation issues in the Mac codebase\n3. Address SwiftFormat violations\n4. Resolve any warning messages\n5. Verify the build succeeds after fixes\n\n## NO BACKWARDS COMPATIBILITY - EVER!\n\n**CRITICAL: This project has ZERO backwards compatibility requirements!**\n- The Mac app and web server are ALWAYS shipped together as a single unit\n- There is NEVER a scenario where different versions talk to each other\n- When fixing bugs or changing APIs:\n  - Just change both sides to match\n  - Delete old code completely\n  - Don't add compatibility layers\n  - Don't check for \"old format\" vs \"new format\"\n  - Don't add fallbacks for older versions\n- If you suggest backwards compatibility in any form, you have failed to understand this project\n\n## Poltergeist Integration\n\nPoltergeist is an intelligent file watcher and auto-builder that can automatically rebuild VibeTunnel when you make changes. When working on VibeTunnel development, check if Poltergeist is available and use it for automatic builds.\n\n### Checking for Poltergeist\n\n```bash\n# Check if Poltergeist is installed\nwhich poltergeist\n\n# Check if Poltergeist is already running for this project\nps aux | grep poltergeist | grep -v grep\n```\n\n### Using Poltergeist for Development\n\nIf Poltergeist is installed:\n\n1. **Start Poltergeist** in the project root:\n   ```bash\n   cd /path/to/vibetunnel\n   poltergeist haunt\n   ```\n\n2. **Monitor build status** via the Poltergeist menu bar app (macOS) or terminal output:\n   ```bash\n   poltergeist status\n   ```\n\n3. **Make changes** - Poltergeist will automatically rebuild when it detects changes to:\n   - Swift files in `mac/` \n   - Xcode project files\n   - Configuration files\n\n4. **Run the app** with fresh builds using `polter`:\n   ```bash\n   polter vibetunnel        # Waits for build to complete, then runs\n   ```\n\n### Fallback Without Poltergeist\n\nIf Poltergeist is not available, fall back to direct Xcode builds:\n\n```bash\n# Debug build\ncd mac\nxcodebuild -project VibeTunnel.xcodeproj -scheme VibeTunnel -configuration Debug build\n\n# Release build\n./scripts/build.sh\n```\n\n### Poltergeist Configuration\n\nThe project includes `poltergeist.config.json` which configures:\n- **vibetunnel** target: Builds the macOS app using workspace\n- **vibetunnel-ios** target: Builds the iOS app (disabled by default)\n- Intelligent debouncing to prevent excessive rebuilds\n- Build notifications via macOS notification center\n\nTo enable iOS builds, edit `poltergeist.config.json` and set `\"enabled\": true` for the vibetunnel-ios target.\n\n## Tailscale CLI Updates (as of August 2025)\n\nThe Tailscale CLI has changed its syntax. The new commands are:\n\n### Tailscale Serve (HTTPS proxy to local services)\n```bash\n# OLD syntax (deprecated):\ntailscale serve https / http://localhost:4020\n\n# NEW syntax:\ntailscale serve --bg http://localhost:4020\n```\n\nThe `--bg` flag runs the serve configuration in background mode. The process exits immediately after configuration.\n\n### Tailscale Funnel (Public internet access)\n```bash\n# Reset any existing configuration first\ntailscale funnel reset\n\n# Enable funnel (still uses --bg flag)\ntailscale funnel --bg 443\n```\n\n### Important Notes:\n- The `tailscale serve --bg` command exits immediately with code 0 on success\n- There's no long-running process to monitor after using --bg\n- HTTPS is automatically configured on port 443\n- Always reset Funnel before starting to avoid \"foreground already exists\" errors\n\n## Key Files Quick Reference\n\n- Architecture Details: `docs/ARCHITECTURE.md`\n- API Specifications: `docs/spec.md`\n- Server Implementation Guide: `web/docs/spec.md`\n- Build Configuration: `web/package.json`, `mac/Package.swift`\n- External Device Testing: `docs/TESTING_EXTERNAL_DEVICES.md`\n- Gemini CLI Instructions: `docs/gemini.md`\n- Release Process: `docs/RELEASE.md`\n\n# important-instruction-reminders\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n\n<!-- File: GEMINI.md (Tokens: ~137 | Category: gemini-rule) -->\n# Gemini Operational Instructions\n\nWhen I am operating within this project, I must adhere to the following instructions:\n\n1.  **Read `claude.md`:** Before performing any task, I must first read the `claude.md` file located in the current working directory.\n2.  **Contextual Awareness:** If the current working directory is a subfolder, I must read all `claude.md` files found in the current folder and all of its parent directories up to the project root. This ensures I have the full context, from the general project-level instructions to the specific subdirectory instructions.\n\nI will use the `read_many_files` tool to gather this information efficiently.\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/amantus-ai/vibetunnel/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}