​
CLAUDE.md - iOS App

This file provides guidance to Claude Code when working with the iOS companion app for VibeTunnel.

​
Project Overview

The iOS app is a companion application to VibeTunnel that allows viewing and managing terminal sessions from iOS devices.

​
Development Setup

  1. Open the project in Xcode:
open ios/VibeTunnel-iOS.xcodeproj
  1. Select your development team in project settings
  2. Build and run on simulator or device

​
Architecture

  • SwiftUI for the user interface
  • WebSocket client for real-time terminal data
  • Shared protocol definitions with macOS app

​
Key Files

  • VibeTunnelApp.swift - Main app entry point
  • ContentView.swift - Primary UI
  • TerminalView.swift - Terminal display component
  • WebSocketClient.swift - Server communication

​
Building

# Build for simulator
xcodebuild -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel -sdk iphonesimulator

# Build for device
xcodebuild -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel -sdk iphoneos

​
Testing

# Run tests
xcodebuild test -project VibeTunnel-iOS.xcodeproj -scheme VibeTunnel -destination 'platform=iOS Simulator,name=iPhone 15'

​
Viewing Logs

Use the provided script to view iOS app logs with unredacted private data: 
# View all logs
./ios/scripts/vtlog.sh

# Filter by category
./ios/scripts/vtlog.sh -c NetworkManager

# Follow logs in real-time
./ios/scripts/vtlog.sh -f

# Search for specific terms
./ios/scripts/vtlog.sh -s "connection"
If prompted for password when viewing logs, see apple/docs/logging-private-fix.md for setup instructions.

​
Common Issues

​
Simulator Connection Issues

  • Ensure the Mac app server is running
  • Check that simulator can reach localhost:4020
  • Verify no firewall blocking connections

​
Device Testing

  • Device must be on same network as Mac
  • Use Mac’s IP address instead of localhost
  • Check network permissions in iOS settings