Package detail

vibetunnel

amantus-ai52.3kMIT1.0.0-beta.15.1

Terminal sharing server with web interface - supports macOS, Linux, and headless environments

terminal, multiplexer, websocket, asciinema

readme

VibeTunnel Banner

Turn any browser into your Mac terminal.
VibeTunnel proxies your terminals right into the browser, so you can vibe-code anywhere.

Download npm version Homebrew Node.js 20+ Discord Twitter

Linux Support License macOS 14.0+ Apple Silicon Support us on Polar Ask DeepWiki

DocumentationReleasesDiscordTwitter

Table of Contents

Why VibeTunnel?

Ever wanted to check on your AI agents while you're away? Need to monitor that long-running build from your phone? Want to share a terminal session with a colleague without complex SSH setups? VibeTunnel makes it happen with zero friction.

Installation Options

macOS App (Recommended for Mac users)

The native macOS app provides the best experience with menu bar integration and automatic updates.

npm Package (Linux & Headless Systems)

For Linux servers, Docker containers, or headless macOS systems, install via npm:

npm install -g vibetunnel

This gives you the full VibeTunnel server with web UI, just without the macOS menu bar app. See the npm Package section for detailed usage.

Quick Start

Requirements

macOS App: Requires an Apple Silicon Mac (M1+). Intel Macs are not supported for the native app.

npm Package: Works on any system with Node.js 20+, including Intel Macs and Linux. Windows is not yet supported (#252).

1. Download & Install

Option 1: Direct Download

Download VibeTunnel and drag it to your Applications folder.

Option 2: Homebrew

brew install --cask vibetunnel

2. Launch VibeTunnel

VibeTunnel lives in your menu bar. Click the icon to start the server.

3. Use the vt Command

The vt command is a smart wrapper that forwards your terminal sessions through VibeTunnel:

How it works:

  • vt is a bash script that internally calls vibetunnel fwd to forward terminal output
  • It provides additional features like shell alias resolution and session title management
  • Available from both the Mac app and npm package installations

Installation sources:

  • macOS App: Creates /usr/local/bin/vt symlink during installation
  • npm Package: Installs vt globally, with intelligent Mac app detection

Smart detection: When you run vt from the npm package, it:

  1. Checks if the Mac app is installed at /Applications/VibeTunnel.app
  2. If found, forwards to the Mac app's vt for the best experience
  3. If not found, uses the npm-installed vibetunnel fwd
  4. This ensures vt always uses the best available implementation
# Run any command in the browser
vt pnpm run dev
vt npm test
vt python script.py

# Monitor AI agents with automatic activity tracking
vt claude --dangerously-skip-permissions
vt --title-mode dynamic claude    # See real-time Claude status

# Use your shell aliases
vt gs              # Your 'git status' alias works!
vt claude-danger   # Custom aliases are resolved

# Open an interactive shell
vt --shell         # or vt -i

# Git follow mode
vt follow          # Follow current branch
vt follow main     # Switch to main and follow
vt unfollow       # Stop following

# For more examples and options, see "The vt Forwarding Command" section below

Git Repository Scanning on First Session

When opening a new session for the first time, VibeTunnel's working directory scanner will look for Git repositories. By default, this scans your home directory, which may trigger macOS permission prompts for accessing protected folders (like Desktop, Documents, Downloads, iCloud Drive, or external volumes).

To avoid these prompts:

  • Option 1: Navigate to your actual projects directory before opening a session
  • Option 2: Accept the one-time permission prompts (they won't appear again)

This only happens on the first session when the scanner discovers your Git repositories. For more details about macOS privacy-protected folders, see this explanation.

4. Open Your Dashboard

Visit http://localhost:4020 to see all your terminal sessions.

Features

  • 🌐 Browser-Based Access - Control your Mac terminal from any device with a web browser
  • 🚀 Zero Configuration - No SSH keys, no port forwarding, no complexity
  • 🤖 AI Agent Friendly - Perfect for monitoring Claude Code, ChatGPT, or any terminal-based AI tools
  • 📊 Dynamic Terminal Titles - Real-time activity tracking shows what's happening in each session
  • 🔄 Git Follow Mode - Terminal automatically follows your IDE's branch switching
  • ⌨️ Smart Keyboard Handling - Intelligent shortcut routing with toggleable capture modes. When capture is active, use Cmd+1...9/0 (Mac) or Ctrl+1...9/0 (Linux) to quickly switch between sessions
  • 🔒 Secure by Design - Multiple authentication modes, localhost-only mode, or secure tunneling via Tailscale/ngrok
  • 📱 Mobile Ready - Native iOS app and responsive web interface for phones and tablets
  • 🎬 Session Recording - All sessions recorded in asciinema format for later playback
  • ⚡ High Performance - Optimized Node.js server with minimal resource usage
  • 🍎 Apple Silicon Native - Optimized for Apple Silicon (M1+) Macs with ARM64-only binaries
  • 🐚 Shell Alias Support - Your custom aliases and shell functions work automatically

Note: The iOS app is still work in progress and not recommended for production use yet.

Architecture

VibeTunnel consists of three main components:

  1. macOS Menu Bar App - Native Swift application that manages the server lifecycle
  2. Node.js Server - High-performance TypeScript server handling terminal sessions
  3. Web Frontend - Modern web interface using Lit components and xterm.js

The server runs as a standalone Node.js executable with embedded modules, providing excellent performance and minimal resource usage.

Remote Access Options

Option 1: Tailscale (Recommended)

Tailscale creates a secure peer-to-peer VPN network between your devices. It's the most secure option as traffic stays within your private network without exposing VibeTunnel to the public internet.

How it works: Tailscale creates an encrypted WireGuard tunnel between your devices, allowing them to communicate as if they were on the same local network, regardless of their physical location.

Setup Guide:

  1. Install Tailscale on your Mac: Download from Mac App Store or Direct Download
  2. Install Tailscale on your remote device:
  3. Sign in to both devices with the same account
  4. Find your Mac's Tailscale hostname in the Tailscale menu bar app (e.g., my-mac.tailnet-name.ts.net)
  5. Access VibeTunnel at http://[your-tailscale-hostname]:4020

Benefits:

  • End-to-end encrypted traffic
  • No public internet exposure
  • Works behind NAT and firewalls
  • Zero configuration after initial setup

Option 2: ngrok

ngrok creates secure tunnels to your localhost, making VibeTunnel accessible via a public URL. Perfect for quick sharing or temporary access.

How it works: ngrok establishes a secure tunnel from a public endpoint to your local VibeTunnel server, handling SSL/TLS encryption and providing a unique URL for access.

Setup Guide:

  1. Create a free ngrok account: Sign up for ngrok
  2. Copy your auth token from the ngrok dashboard
  3. Add the token in VibeTunnel settings (Settings → Remote Access → ngrok)
  4. Enable ngrok tunneling in VibeTunnel
  5. Share the generated https://[random].ngrok-free.app URL

Benefits:

  • Public HTTPS URL with SSL certificate
  • No firewall configuration needed
  • Built-in request inspection and replay
  • Custom domains available (paid plans)

Note: Free ngrok URLs change each time you restart the tunnel. You can claim one free static domain per user, or upgrade to a paid plan for multiple domains.

Option 3: Local Network

  1. Configure authentication (see Authentication section)
  2. Switch to "Network" mode
  3. Access via http://[your-mac-ip]:4020

Option 4: Cloudflare Quick Tunnel

  1. Install cloudflared
  2. Run cloudflared tunnel --url http://localhost:4020
  3. Access via the generated *.trycloudflare.com URL

Git Follow Mode

Git Follow Mode keeps your main repository checkout synchronized with the branch you're working on in a Git worktree. This allows agents to work in worktrees while your IDE, server, and other tools stay open on the main repository - they'll automatically update when the worktree switches branches.

What is Follow Mode?

Follow mode creates a seamless workflow for agent-assisted development:

  • Agents work in worktrees → Main repository automatically follows their branch switches
  • Keep Xcode/IDE open → It updates automatically without reopening projects
  • Server stays running → No need to restart servers in different folders
  • Zero manual intervention → Main repo stays in sync with active development

Quick Start

# From a worktree - enable follow mode for this worktree
vt follow

# From main repo - follow current branch's worktree (if it exists)
vt follow

# From main repo - follow a specific branch's worktree
vt follow feature/new-api

# From main repo - follow a worktree by path
vt follow ~/project-feature

# Disable follow mode
vt unfollow

How It Works

  1. Git Hooks: VibeTunnel installs lightweight Git hooks (post-commit, post-checkout) in worktrees that detect branch changes
  2. Main Repo Sync: When you switch branches in a worktree, the main repository automatically checks out to the same branch
  3. Smart Handling: If the main repo has uncommitted changes, follow mode pauses to prevent data loss
  4. Development Continuity: Your IDE, servers, and tools running on the main repo seamlessly follow your active work
  5. Clean Uninstall: When you run vt unfollow, Git hooks are automatically removed and any original hooks are restored

Common Workflows

Agent Development with Worktrees

# Create a worktree for agent development
git worktree add ../project-agent feature/new-feature

# Enable follow mode on the main repo
cd ../project && vt follow

# Agent works in the worktree while you stay in main repo
# When agent switches branches in worktree, your main repo follows!
# Your Xcode/IDE and servers stay running without interruption

Technical Details

Follow mode stores the worktree path in your main repository's Git config:

# Check which worktree is being followed
git config vibetunnel.followWorktree

# Follow mode is active when this returns a path
# The config is managed by vt commands - manual editing not recommended

For more advanced Git worktree workflows, see our detailed worktree documentation.

Terminal Title Management

VibeTunnel provides intelligent terminal title management to help you track what's happening in each session:

Title Modes

  • Dynamic Mode (default for web UI): Shows working directory, command, and real-time activity

    • Generic activity: ~/projects — npm — •
    • Claude status: ~/projects — claude — ✻ Crafting (45s, ↑2.1k)
  • Static Mode: Shows working directory and command

    • Example: ~/projects/app — npm run dev
  • Filter Mode: Blocks all title changes from applications

    • Useful when you have your own terminal management system
  • None Mode: No title management - applications control their own titles

Activity Detection

Dynamic mode includes real-time activity detection:

  • Shows when there's terminal output within 5 seconds
  • Claude commands show specific status (Crafting, Transitioning, etc.)
  • Extensible system for future app-specific detectors

Authentication

VibeTunnel provides multiple authentication modes to secure your terminal sessions:

Authentication Modes

1. System Authentication (Default)

Uses your operating system's native authentication:

  • macOS: Authenticates against local user accounts
  • Linux: Uses PAM (Pluggable Authentication Modules)
  • Login with your system username and password

2. Environment Variable Authentication

Simple authentication for deployments:

export VIBETUNNEL_USERNAME=admin
export VIBETUNNEL_PASSWORD=your-secure-password
npm run start

3. SSH Key Authentication

Use Ed25519 SSH keys from ~/.ssh/authorized_keys:

# Enable SSH key authentication
npm run start -- --enable-ssh-keys

# Make SSH keys mandatory (disable password auth)
npm run start -- --enable-ssh-keys --disallow-user-password

4. No Authentication

For trusted environments only:

npm run start -- --no-auth

5. Local Bypass (Development Only)

Allow localhost connections to bypass authentication:

# Basic local bypass (DEVELOPMENT ONLY - NOT FOR PRODUCTION)
npm run start -- --allow-local-bypass

# With token for additional security (minimum for production)
npm run start -- --allow-local-bypass --local-auth-token mytoken

Security Note: Local bypass uses req.socket.remoteAddress which cannot be spoofed remotely due to TCP's three-way handshake. The implementation also rejects requests with proxy headers (X-Forwarded-For, etc.) to prevent header injection attacks. However:

  • Development only: Basic bypass without token should never be used in production
  • Local processes: Any process on the same machine can access the API
  • Always use tokens: In production, always require --local-auth-token
  • Consider alternatives: For production, use proper authentication instead of local bypass

macOS App Authentication

The macOS menu bar app supports these authentication modes:

  • No Authentication: For trusted environments only
  • System Authentication: Uses your macOS user account credentials
  • SSH Key Authentication: Uses Ed25519 SSH keys from ~/.ssh/authorized_keys
  • Configure via Settings → Security when in "Network" mode

Security Best Practices

  1. Always use authentication when binding to network interfaces (--bind 0.0.0.0)
  2. Use HTTPS in production with a reverse proxy (nginx, Caddy)
  3. Rotate credentials regularly
  4. Consider SSH keys for stronger security
  5. Never use local bypass without tokens in production environments
  6. Monitor access logs for suspicious authentication patterns
  7. Default to secure - explicitly enable less secure options only when needed

SSH Key Authentication Troubleshooting

If SSH key generation fails with crypto errors, see the detailed troubleshooting guide for solutions.

npm Package

The VibeTunnel npm package provides the full server functionality for Linux, Docker, CI/CD environments, and headless macOS systems.

Installation

# Install globally via npm
npm install -g vibetunnel

# Or with yarn
yarn global add vibetunnel

# Or with pnpm
pnpm add -g vibetunnel

Requirements: Node.js 20.0.0 or higher

Running the VibeTunnel Server

Basic Usage

# Start with default settings (localhost:4020)
vibetunnel

# Bind to all network interfaces
vibetunnel --bind 0.0.0.0

# Use a custom port
vibetunnel --port 8080

# With authentication
VIBETUNNEL_USERNAME=admin VIBETUNNEL_PASSWORD=secure vibetunnel --bind 0.0.0.0

# Enable debug logging
VIBETUNNEL_DEBUG=1 vibetunnel

# Run without authentication (trusted networks only!)
vibetunnel --no-auth

Using the vt Command

The vt command wrapper makes it easy to forward terminal sessions:

# Monitor AI agents with automatic activity tracking
vt claude
vt claude --dangerously-skip-permissions
vt --title-mode dynamic claude    # See real-time Claude status

# Run any command and see it in the browser
vt npm test
vt python script.py
vt cargo build --release

# Open an interactive shell
vt --shell
vt -i  # short form

# Control terminal titles
vt --title-mode static npm run dev    # Shows path and command
vt --title-mode dynamic python app.py  # Shows path, command, and activity
vt --title-mode filter vim            # Blocks vim from changing title

# Control output verbosity
vt -q npm test         # Quiet mode - no console output
vt -v npm run dev      # Verbose mode - show more information
vt -vv cargo build     # Extra verbose - all except debug
vt -vvv python app.py  # Debug mode - show everything

# Shell aliases work automatically!
vt claude-danger  # Your custom alias for claude --dangerously-skip-permissions

# Update session title (inside a VibeTunnel session)
vt title "My Project - Testing"

The vt Forwarding Command

The vt command is VibeTunnel's terminal forwarding wrapper that allows you to run any command while making its output visible in the browser. Under the hood, vt is a convenient shortcut for vibetunnel fwd - it's a bash script that calls the full command with proper path resolution and additional features like shell alias support. The vt wrapper acts as a transparent proxy between your terminal and the command, forwarding all input and output through VibeTunnel's infrastructure.

Command Syntax

vt [options] <command> [args...]

Options

Terminal Title Control:

  • --title-mode <mode> - Control how terminal titles are managed:
    • none - No title management, apps control their own titles (default)
    • filter - Block all title changes from applications
    • static - Show working directory and command in title
    • dynamic - Show directory, command, and live activity status (auto-enabled for Claude)

Verbosity Control:

  • -q, --quiet - Quiet mode, no console output (logs to file only)
  • -v, --verbose - Verbose mode, show errors, warnings, and info messages
  • -vv - Extra verbose, show all messages except debug
  • -vvv - Debug mode, show all messages including debug

Other Options:

  • --shell, -i - Launch your current shell interactively
  • --no-shell-wrap, -S - Execute command directly without shell interpretation
  • --log-file <path> - Override default log file location (defaults to ~/.vibetunnel/log.txt)
  • --help, -h - Show help message with all options

Verbosity Levels

VibeTunnel uses a hierarchical logging system where each level includes all messages from more severe levels:

Level Flag Environment Variable Shows
SILENT -q VIBETUNNEL_LOG_LEVEL=silent No console output (file logging only)
ERROR (default) VIBETUNNEL_LOG_LEVEL=error Errors only
WARN - VIBETUNNEL_LOG_LEVEL=warn Errors and warnings
INFO -v VIBETUNNEL_LOG_LEVEL=info Errors, warnings, and informational messages
VERBOSE -vv VIBETUNNEL_LOG_LEVEL=verbose All messages except debug
DEBUG -vvv VIBETUNNEL_LOG_LEVEL=debug Everything including debug traces

Note: All logs are always written to ~/.vibetunnel/log.txt regardless of verbosity settings. The verbosity only controls terminal output.

Examples

# Basic command forwarding
vt ls -la                    # List files with VibeTunnel monitoring
vt npm run dev              # Run development server
vt python script.py         # Execute Python script

# With verbosity control
vt -q npm test              # Run tests silently
vt -v npm install           # See detailed installation progress
vt -vvv python debug.py     # Full debug output
vt --log-file debug.log npm run dev  # Write logs to custom file

# Terminal title management
vt --title-mode static npm run dev    # Fixed title showing command
vt --title-mode dynamic claude         # Live activity updates
vt --title-mode filter vim            # Prevent vim from changing title

# Shell handling
vt --shell                  # Open interactive shell
vt -S /usr/bin/python      # Run python directly without shell

How It Works

  1. Command Resolution: The vt wrapper first checks if your command is an alias, shell function, or binary
  2. Session Creation: It creates a new VibeTunnel session with a unique ID
  3. PTY Allocation: A pseudo-terminal is allocated to preserve terminal features (colors, cursor control, etc.)
  4. I/O Forwarding: All input/output is forwarded between your terminal and the browser in real-time
  5. Process Management: The wrapper monitors the process and handles signals, exit codes, and cleanup

Environment Variables

  • VIBETUNNEL_LOG_LEVEL - Set default verbosity level (silent, error, warn, info, verbose, debug)
  • VIBETUNNEL_TITLE_MODE - Set default title mode (none, filter, static, dynamic)
  • VIBETUNNEL_DEBUG - Legacy debug flag, equivalent to VIBETUNNEL_LOG_LEVEL=debug
  • VIBETUNNEL_CLAUDE_DYNAMIC_TITLE - Force dynamic title mode for Claude commands

Special Features

Automatic Claude Detection: When running Claude AI, vt automatically enables dynamic title mode to show real-time activity status (thinking, writing, idle).

Shell Alias Support: Your shell aliases and functions work transparently through vt:

alias gs='git status'
vt gs  # Works as expected

Session Title Updates: Inside a VibeTunnel session, use vt title to update the session name:

vt title "Building Production Release"

Mac App Interoperability

The npm package is designed to work seamlessly alongside the Mac app:

Smart Command Routing

  • The vt command automatically detects if the Mac app is installed
  • If found at /Applications/VibeTunnel.app, it defers to the Mac app
  • If not found, it uses the npm-installed server
  • This ensures you always get the best available implementation

Installation Behavior

  • If /usr/local/bin/vt already exists (from another tool), npm won't overwrite it
  • You'll see a helpful warning with alternatives: vibetunnel or npx vt
  • The installation always succeeds, even if the vt symlink can't be created

When to Use Each Version

  • Mac app only: Best for macOS users who want menu bar integration
  • npm only: Perfect for Linux, Docker, CI/CD, or headless servers
  • Both installed: Mac app takes precedence, npm serves as fallback
  • Development: npm package useful for testing without affecting Mac app

Package Contents

The npm package includes:

  • Full VibeTunnel server with web UI
  • CLI tools (vibetunnel and vt commands)
  • Native PTY support via node-pty
  • Pre-built binaries for common platforms
  • Complete feature parity with macOS app (minus menu bar)

Building the npm Package

For maintainers who need to build the npm package:

Unified Build (Multi-Platform by Default)

# Build with prebuilt binaries for all platforms
# Requires Docker for Linux cross-compilation
npm run build:npm

This creates prebuilt binaries for:

  • macOS (x64, arm64) - Node.js 20, 22, 23, 24
  • Linux (x64, arm64) - Node.js 20, 22, 23, 24

Build Options

# Current platform only (faster for development)
node scripts/build-npm.js --current-only

# Specific platform/architecture
node scripts/build-npm.js --platform darwin --arch arm64

# Skip Docker builds
node scripts/build-npm.js --no-docker

Publishing

# Test the package locally
npm pack

# Publish to npm
npm publish

Building from Source

Prerequisites

  • macOS 14.0+ (Sonoma) on Apple Silicon (M1+)
  • Xcode 16.0+
  • Node.js 20+ (minimum supported version)

Build Steps

# Clone the repository
git clone https://github.com/amantus-ai/vibetunnel.git
cd vibetunnel

# Set up code signing (required for macOS/iOS development)
# Create Local.xcconfig files with your Apple Developer Team ID
# Note: These files must be in the same directory as Shared.xcconfig
cat > mac/VibeTunnel/Local.xcconfig << EOF
// Local Development Configuration
// DO NOT commit this file to version control
DEVELOPMENT_TEAM = YOUR_TEAM_ID
CODE_SIGN_STYLE = Automatic
EOF

cat > ios/VibeTunnel/Local.xcconfig << EOF
// Local Development Configuration  
// DO NOT commit this file to version control
DEVELOPMENT_TEAM = YOUR_TEAM_ID
CODE_SIGN_STYLE = Automatic
EOF

# Build the web server
cd web
pnpm install
pnpm run build

# Optional: Build with custom Node.js for smaller binary (46% size reduction)
# export VIBETUNNEL_USE_CUSTOM_NODE=YES
# node build-custom-node.js  # Build optimized Node.js (one-time, ~20 min)
# pnpm run build              # Will use custom Node.js automatically

# Build the macOS app
cd ../mac
./scripts/build.sh --configuration Release

Custom Node.js Builds

VibeTunnel supports building with a custom Node.js for a 46% smaller executable (61MB vs 107MB):

# Build custom Node.js (one-time, ~20 minutes)
node build-custom-node.js

# Use environment variable for all builds
export VIBETUNNEL_USE_CUSTOM_NODE=YES

# Or use in Xcode Build Settings
# Add User-Defined Setting: VIBETUNNEL_USE_CUSTOM_NODE = YES

See Custom Node Build Flags for detailed optimization information.

Development

For development setup and contribution guidelines, see CONTRIBUTING.md.

Key Files

  • macOS App: mac/VibeTunnel/VibeTunnelApp.swift
  • Server: web/src/server/ (TypeScript/Node.js)
  • Web UI: web/src/client/ (Lit/TypeScript)
  • iOS App: ios/VibeTunnel/

Testing & Code Coverage

VibeTunnel has comprehensive test suites with code coverage enabled for all projects:

# Run all tests with coverage
./scripts/test-all-coverage.sh

# macOS tests with coverage (Swift Testing)
cd mac && swift test --enable-code-coverage

# iOS tests with coverage (using xcodebuild)
cd ios && ./scripts/test-with-coverage.sh

# Web tests with coverage (Vitest)
cd web && ./scripts/coverage-report.sh

Coverage Requirements:

  • macOS/iOS: 75% minimum (enforced in CI)
  • Web: 80% minimum for lines, functions, branches, and statements

Development Server & Hot Reload

VibeTunnel includes a development server with automatic rebuilding for faster iteration:

Development Mode

cd web
pnpm run dev

What this provides:

  • Automatic Rebuilds: esbuild watches for file changes and rebuilds bundles instantly
  • Fast Feedback: Changes are compiled within seconds of saving
  • Manual Refresh Required: Browser needs manual refresh to see changes (no hot module replacement)

How it works:

  • esbuild watch mode detects file changes in src/
  • Automatically rebuilds JavaScript bundles and CSS
  • Express server serves updated files immediately
  • Visit http://localhost:4020 and refresh to see changes

Testing on External Devices (iPad, iPhone, etc.)

When developing the web interface, you often need to test changes on external devices to debug browser-specific issues. Here's how to do it:

Quick Setup
  1. Run the dev server with network access:

    cd web
    pnpm run dev --port 4021 --bind 0.0.0.0
    

    This binds to all network interfaces, making it accessible from other devices.

  2. Find your Mac's IP address:

    • System Preferences → Network → Wi-Fi → Details
    • Or run: ipconfig getifaddr en0
  3. Access from your external device:

    http://[your-mac-ip]:4021
    
Important Notes
  • Port conflict: The Mac app runs on port 4020, so use a different port (e.g., 4021) for development
  • Same network: Ensure both devices are on the same Wi-Fi network
  • Firewall: macOS may prompt to allow incoming connections - click "Allow"
  • Auto-rebuild: Changes to the web code are automatically rebuilt, but you need to manually refresh the browser
Pasting on Mobile Devices

When using VibeTunnel on mobile browsers (Safari, Chrome), pasting works differently than on desktop:

To paste on mobile:

  1. Press the paste button on the keyboard toolbar
  2. A white input box will appear
  3. Long-press inside the white box to bring up the paste menu
  4. Select "Paste" from the menu
  5. The text will be pasted into your terminal session

Note: Due to browser security restrictions on non-HTTPS connections, the paste API is limited on mobile devices. The white input box is a workaround that allows clipboard access through the browser's native paste functionality.

Future: Hot Module Replacement

For true hot module replacement without manual refresh, see our Vite migration plan which would provide:

  • Instant updates without page refresh
  • Preserved application state during development
  • Sub-second feedback loops
  • Modern development tooling

Mac App Development Server Mode

The VibeTunnel Mac app includes a special development server mode that integrates with the web development workflow:

Setup:

  1. Open VibeTunnel Settings → Debug tab (enable Debug Mode first in General settings)
  2. Enable "Use Development Server"
  3. Set the path to your web/ directory
  4. Restart the VibeTunnel server

How it works:

  • Instead of using the bundled production server, the Mac app runs pnpm run dev in your web directory
  • Provides hot reload and automatic rebuilding during development
  • Maintains all Mac app functionality (session management, logging, etc.)
  • Shows "Dev Server" in the menu bar and status indicators

Benefits:

  • No need to manually rebuild after code changes
  • Automatic esbuild watch mode for instant compilation
  • Full integration with Mac app features
  • Same terminal session management as production

Alternative: Standalone Development

If you prefer working outside the Mac app:

  1. Build the web project: cd web && pnpm run build
  2. In VibeTunnel settings, set Dashboard Access to "Network"
  3. Access from external device: http://[your-mac-ip]:4020

Note: This requires rebuilding after each change, so the dev server mode above is preferred for rapid iteration.

Debug Logging

Enable debug logging for troubleshooting:

# Enable debug mode
export VIBETUNNEL_DEBUG=1

# Or use inline
VIBETUNNEL_DEBUG=1 vt your-command

Debug logs are written to ~/.vibetunnel/log.txt.

Using Development Builds with vt

When developing VibeTunnel, you can use the VIBETUNNEL_PREFER_DERIVED_DATA environment variable to make the vt command prefer development builds from Xcode's DerivedData folder:

# Enable DerivedData preference
export VIBETUNNEL_PREFER_DERIVED_DATA=1

# vt will now search for and use the latest VibeTunnel build from DerivedData
vt your-command

When this environment variable is set, vt will:

  1. First search for VibeTunnel builds in ~/Library/Developer/Xcode/DerivedData
  2. Use the most recently modified build found there
  3. Fall back to /Applications/VibeTunnel.app if no DerivedData build exists
  4. Log the exact binary location, version, and build timestamp being used

This is particularly useful for:

  • Testing changes without installing to /Applications
  • Working with multiple VibeTunnel builds simultaneously
  • Quickly switching between development and production versions
  • Debugging which version of VibeTunnel is being used

The version information is also:

  • Stored in session.json for each session
  • Displayed in vt status output
  • Shown in the initial log output when VIBETUNNEL_PREFER_DERIVED_DATA is set

Verbosity Control

Control the amount of output from VibeTunnel commands:

# Command-line flags
vt -q npm test                # Quiet mode - no console output
vt npm test                   # Default - errors only
vt -v npm run dev            # Verbose - errors, warnings, and info
vt -vv cargo build           # Extra verbose - all except debug
vt -vvv python script.py     # Debug mode - everything

# Environment variable
export VIBETUNNEL_LOG_LEVEL=error    # Default
export VIBETUNNEL_LOG_LEVEL=warn     # Show errors and warnings
export VIBETUNNEL_LOG_LEVEL=info     # Show errors, warnings, and info
export VIBETUNNEL_LOG_LEVEL=verbose  # All except debug
export VIBETUNNEL_LOG_LEVEL=debug    # Everything

# Or use inline
VIBETUNNEL_LOG_LEVEL=silent vt npm test

Note: All logs are always written to ~/.vibetunnel/log.txt regardless of verbosity level. The verbosity settings only control what's displayed in the terminal.

Poltergeist Integration

Poltergeist is an intelligent file watcher and auto-builder that can automatically rebuild VibeTunnel as you develop. This is particularly useful for native app development where manual rebuilds can interrupt your flow.

Setting Up Poltergeist

  1. Install Poltergeist (if not already installed):

    npm install -g poltergeist
    
  2. Start Poltergeist in the VibeTunnel directory:

    cd /path/to/vibetunnel
    poltergeist
    
  3. Make changes - Poltergeist will automatically rebuild when it detects changes to:

    • Swift files in mac/ or ios/
    • Xcode project files
    • Configuration files

Poltergeist Features

  • Automatic Rebuilds: Detects file changes and rebuilds instantly
  • Smart Debouncing: Prevents excessive rebuilds during rapid edits
  • Build Notifications: macOS notifications for build success/failure
  • Menu Bar Integration: Monitor build status from the macOS menu bar
  • Parallel Builds: Can build macOS and iOS targets simultaneously

Configuration

VibeTunnel includes a poltergeist.config.json that configures:

  • vibetunnel target: Builds the macOS app in Debug configuration
  • vibetunnel-ios target: Builds the iOS app (disabled by default)

To enable iOS builds, edit poltergeist.config.json and set "enabled": true for the vibetunnel-ios target.

Documentation

macOS Permissions

macOS is finicky when it comes to permissions. The system will only remember the first path from where an app requests permissions. If subsequently the app starts somewhere else, it will silently fail. Fix: Delete the entry and restart settings, restart app and next time the permission is requested, there should be an entry in Settings again.

Important: You need to set your Developer ID in Local.xcconfig. If apps are signed Ad-Hoc, each new signing will count as a new app for macOS and the permissions have to be (deleted and) requested again.

Debug vs Release Bundle IDs: The Debug configuration uses a different bundle identifier (sh.vibetunnel.vibetunnel.debug) than Release (sh.vibetunnel.vibetunnel). This allows you to have both versions installed simultaneously, but macOS treats them as separate apps for permissions. You'll need to grant permissions separately for each version.

If that fails, use the terminal to reset:

# This removes Accessibility permission for a specific bundle ID:
sudo tccutil reset Accessibility sh.vibetunnel.vibetunnel
sudo tccutil reset Accessibility sh.vibetunnel.vibetunnel.debug  # For debug builds

sudo tccutil reset ScreenCapture sh.vibetunnel.vibetunnel
sudo tccutil reset ScreenCapture sh.vibetunnel.vibetunnel.debug  # For debug builds

# This removes all Automation permissions system-wide (cannot target specific apps):
sudo tccutil reset AppleEvents

Logging and Privacy

VibeTunnel uses Apple's unified logging system with the subsystem sh.vibetunnel.vibetunnel. By default, macOS redacts sensitive runtime data in logs, showing <private> instead of actual values. This is a privacy feature to prevent accidental exposure of sensitive information.

Bundle Identifiers

VibeTunnel uses the following bundle identifiers:

Production:

  • sh.vibetunnel.vibetunnel - Main macOS app and logging subsystem
  • sh.vibetunnel.vibetunnel.debug - Debug builds of the macOS app

Testing:

  • sh.vibetunnel.vibetunnel.tests - macOS test suite
  • sh.vibetunnel.ios.tests - iOS test suite

iOS:

  • sh.vibetunnel.ios - iOS keychain service and URL scheme

Viewing Unredacted Logs

To see full log details for debugging, you have several options:

  1. Install the Configuration Profile (Recommended - easiest method):

    # Install the logging configuration profile
    open apple/logging/VibeTunnel-Logging.mobileconfig
    
    # This enables debug logging for all VibeTunnel components
    # To remove later: System Settings → Privacy & Security → Profiles
    
  2. Use the vtlog script (convenient log viewer):

    # View recent logs (requires configuration profile or sudo)
    ./scripts/vtlog.sh
    
    # Follow logs in real-time
    ./scripts/vtlog.sh -f
    
    # Show only errors
    ./scripts/vtlog.sh -e
    
    # Filter by category
    ./scripts/vtlog.sh -c ServerManager
    
  3. Configure passwordless sudo (alternative for vtlog with -p flag):

    # Add to sudoers (replace 'yourusername' with your actual username)
    sudo visudo
    # Add this line:
    yourusername ALL=(ALL) NOPASSWD: /usr/bin/log
    
    # Then use vtlog with private flag
    ./scripts/vtlog.sh -p
    
  4. Enable private data logging using a plist file (alternative):

    # Create the plist to enable private data for VibeTunnel
    sudo mkdir -p /Library/Preferences/Logging/Subsystems
    sudo tee /Library/Preferences/Logging/Subsystems/sh.vibetunnel.vibetunnel.plist > /dev/null << 'EOF'
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>Enable-Private-Data</key>
        <true/>
    </dict>
    </plist>
    EOF
    

Why Logs Show <private>

Apple redacts dynamic values in logs by default to protect user privacy. This prevents accidental logging of passwords, tokens, or personal information. Our configuration profile or the methods above enable full visibility for development and debugging.

For more detailed information about logging privacy and additional methods, see apple/docs/logging-private-fix.md.

Contributing

We welcome contributions! VibeTunnel is a community-driven project and we'd love to have you join us.

Join Our Community

Connect with the VibeTunnel team and other contributors on our Discord server. It's the best place to:

  • Discuss new features and ideas
  • Get help with development setup
  • Coordinate on larger changes
  • Share your VibeTunnel use cases

How to Contribute

  1. Join Discord: Start by joining our Discord server to say hello!
  2. Check Issues: Look for issues labeled good first issue or help wanted
  3. Development Setup: Follow our Contributing Guide for detailed setup instructions
  4. Submit PRs: Fork the repo, create a branch, and submit your changes

For technical details on building and developing VibeTunnel, see our Contributing Guide.

Support VibeTunnel

Love VibeTunnel? Help us keep the terminal vibes flowing! Your support helps us buy pizza and drinks while we keep hacking on your favorite AI agent orchestration platform.

All donations go directly to the development team. Choose your own amount - one-time or monthly! Visit our Polar page to support us.

Credits

Created with ❤️ by:

License

VibeTunnel is open source software licensed under the MIT License. See LICENSE for details.


Ready to vibe? Download VibeTunnel and start tunneling!

changelog

Changelog

[Unreleased]

🐛 Bug Fixes

  • Fix session creation "data couldn't be read" error on Mac app (#500)

[1.0.0-beta.15] - 2025-08-02

✨ Major Features

Push Notifications (#475)

  • Native push notifications for terminal events - get notified when commands complete, sessions start/end, or errors occur
  • Customizable notification types: Session exits, command completion (>3s), command errors, terminal bell, Claude AI turn notifications
  • Smart Claude detection: Automatically identifies Claude CLI sessions and tracks when Claude finishes responding
  • Complete overhaul of the notification system with reliable push notifications for session events
  • Test notification feature now works seamlessly between web frontend and Mac app
  • Improved notification preferences with granular control over notification types
  • Better error handling and recovery for notification delivery failures
  • Enhanced integration between web services and native Mac notification service

Git Worktree Management & Follow Mode (#452)

  • Full worktree support: Create, manage, and delete Git worktrees directly from VibeTunnel
  • VibeTunnel intelligently follows Git worktrees instead of just branches, perfect for developers using worktrees for parallel development
  • When you switch branches in your editor/IDE, VibeTunnel automatically switches to the corresponding worktree terminal session
  • The vt follow command works contextually - run it from either your main repository or a worktree to set up appropriate tracking
  • Visual indicators: Fork icon (⑂) shows worktree sessions, branch names displayed throughout UI
  • Follow mode displays worktree paths with ~ for your home directory, making them easier to read
  • HTTP Git API: New endpoints for Git operations (/api/git/status, /api/git/branches, /api/worktrees)
  • Branch selection: Choose branches before creating sessions with real-time repository status

Comprehensive CJK (Chinese, Japanese, Korean) Input Support (#480)

  • Full support for CJK input methods with proper IME (Input Method Editor) integration
  • Fixed input duplication issues that affected Asian language users
  • Improved Z-index management to ensure IME candidates display correctly above terminal content
  • Enhanced keyboard event handling for complex character composition
  • Better compatibility with native macOS and iOS input methods

Terminal Multiplexer Integration (tmux, Zellij & Screen) (#460)

  • Full integration with tmux, Zellij, and GNU Screen terminal multiplexers for persistent sessions
  • Create, list, and attach to tmux/Zellij/Screen sessions directly from VibeTunnel interface
  • Sessions persist across VibeTunnel restarts - never lose your work
  • Perfect for remote development: attach to the same session from multiple devices
  • Supports tmux panes and windows for advanced terminal workflows
  • Seamless switching between standard VibeTunnel sessions and multiplexer sessions

Quick Session Switching with Number Keys

  • When keyboard capture is active, use Cmd+1...9 (Mac) or Ctrl+1...9 (Linux) to instantly switch between sessions
  • Cmd/Ctrl+0 switches to the 10th session
  • Works only when keyboard capture is enabled in session view, allowing quick navigation without mouse
  • Session numbers match the numbers shown in the session list

Enhanced Git Integration

  • See branch names, commit status, and sync state in autocomplete suggestions
  • Real-time display of uncommitted changes (added/modified/deleted files)
  • Branch selector dropdown for switching branches before creating sessions
  • Repository grouping in session list with branch/worktree selectors
  • Consistent branch name formatting with square brackets: [main]

Interface Polish

  • Responsive design: Better mobile/iPad layouts with adaptive button switching
  • Collapsible options: Session options now in expandable sections for cleaner UI
  • Increased menu bar button heights for better clickability
  • Improved spacing and padding throughout the interface
  • Smoother animations and transitions

🐛 Bug Fixes

Project Organization & Stability

  • Enhanced VT command reliability with self-healing capabilities - VT sessions now automatically recover from connection issues
  • Fixed menu bar icon not appearing on app launch

Advanced Features

  • Enhanced Tailscale integration with automatic authentication for seamless secure access (#472)
  • Cleaned up VT command output by removing verbose binary path prefixes and socket disconnect noise

Developer Experience

  • Improved notification system reliability - fixed test notification button integration between Mac app and server (#483)
  • Enhanced notification auto-reconnection behavior when pages are reloaded
  • Added comprehensive logging documentation to README for better troubleshooting
  • Removed obsolete bundle identifier references and updated logging configuration

🔧 Technical Improvements

Improved Terminal Output Handling

  • Enhanced asciinema stream pruning: Removes noisy ANSI sequences for cleaner recordings
  • Better mobile terminal detection to optimize output rendering
  • Fixed terminal resize event handling to prevent output corruption
  • Improved logging for debugging terminal lifecycle issues

Performance & Architecture

  • Completed Tailwind CSS v4 migration with performance optimizations
  • Enhanced Playwright test performance for faster CI runs
  • Updated all dependencies to latest stable versions
  • Improved type safety throughout the codebase, especially for Tailscale authentication
  • Modular refactoring: Split session-view.ts into 7 specialized managers
  • Component breakdown: Refactored session-create-form into smaller components
  • Unified components: Created reusable GitBranchWorktreeSelector
  • Better separation: Clear boundaries between UI and business logic
  • Session rename functionality centralized: Eliminated duplicate code across components
  • Socket-based vt command communication: Replaced HTTP with Unix domain sockets for reliability

Communication & Reliability

  • Unified notification system now uses Server-Sent Events (SSE) for all clients instead of mixed approaches
  • Fixed git status monitoring to prevent EMFILE errors through shallow directory watching
  • Standardized git status terminology - consistently uses 'New' for untracked files across all interfaces
  • Enhanced session cleanup on startup with proper JSON field handling

Developer Experience

  • Improved TypeScript type safety throughout
  • Better error handling and logging
  • Consistent code formatting across macOS and web codebases
  • Removed outdated crash investigation documentation
  • Comprehensive JSDoc documentation added to service classes
  • Removed backwards compatibility for older vt command versions

UI/UX Enhancements

  • Modernized macOS autocomplete dropdown with native SwiftUI materials and transparency
  • Fixed Quick Start Commands UI with proper native macOS table styling
  • Added help tooltips throughout settings UI explaining each notification type
  • Fixed mouse hover selection issues in autocomplete dropdown
  • Improved button click targets for better usability

Socket API Improvements

  • Refactored socket client with type-safe message handling
  • Removed HTTP fallback in favor of pure socket communication for better reliability
  • Added proper TypeScript types for all socket protocol messages
  • Cleaner public API without brittle type casting

Developer Tools

  • Added VIBETUNNEL_PREFER_DERIVED_DATA environment variable for faster Xcode builds
  • Version tracking in socket protocol for better debugging
  • Consolidated duplicate Git status implementations for maintainability
  • Enhanced error logging for session termination debugging

Self-Healing VT Command

  • The vt command now automatically recovers from connection issues and socket failures
  • Improved reliability with automatic reconnection when the server restarts
  • Better error handling for Unix socket communication

iOS Mobile Experience

  • Completely redesigned keyboard handling for iOS devices (#484)
  • Fixed keyboard dismissal issues that left the interface in an inconsistent state (#484)
  • Improved modal interactions with better keyboard management
  • Enhanced direct keyboard input manager for smoother text entry
  • Better handling of iOS-specific keyboard behaviors and quirks
  • Fixed blinking cursor issue in binary terminal mode (#489)

👥 Contributors

Thank you to all the contributors who helped make this release possible!

First-time contributors to VibeTunnel:

  • @jblwilliams - Removed unused ScreenCaptureKit import from ServerManager (#486)
  • @lox - Added Tailscale Serve integration with automatic authentication (#472)
  • @diegopetrucci - Contributed push notifications onboarding screen (via #474)

Additional contributors:

  • @hjanuschka - Added tmux integration (#460), fixed iOS keyboard dismissal issue (#484), and fixed blinking cursor in binary terminal mode (#489)
  • @fal3 - Fixed Test Notification Button to VibeTunnel Mac App (#483)
  • @hewigovens - Fixed mobile keyboard layout and text sizing issues (#441) and contributed CJK (Chinese, Japanese, Korean) IME input support (#447, refined in #480)

[1.0.0-beta.14] - 2025-07-21

✨ Major Features

Customizable Quick Start Commands (#436)

  • Quick Start commands are now fully customizable - previously hardcoded buttons can be edited
  • Add your own commands with custom names and emoji (e.g., "✨ claude" or "▶️ dev server")
  • Drag & drop reordering with smooth animations in macOS settings
  • Inline editing without popup dialogs
  • Reset to defaults button when you want the original set back
  • File-based persistence in ~/.vibetunnel/config.json shared between web and Mac apps

New Session Path Autocomplete (#435)

  • Intelligent path autocomplete when creating sessions with unified UI
  • Home directory expansion (~/ shortcuts work properly)
  • Visual file browser with folder icons for easy navigation
  • Git repository discovery shows current branch in file browser
  • Repository status displayed in welcome screen
  • Escape key support and auto-select first suggestion

Session Status Management

  • New dropdown menu in session headers for running/exited sessions
  • Terminate running sessions without closing the tab
  • Clear exited sessions individually with one click
  • Visual status indicators - pulsing dot for running, static for exited
  • Keyboard navigation support (Arrow keys, Enter, Escape)

Image Upload Menu (#432)

  • New image upload feature in session headers with multiple input methods:
    • Paste images from clipboard
    • Select from photo library (mobile)
    • Take photo with camera (mobile)
    • Browse for files
  • Automatically converts images to base64 and inserts at cursor position
  • Mobile-optimized UI with full-screen menu

Linux Systemd Support (#426)

  • Run VibeTunnel as a persistent service with vibetunnel systemd install
  • User-level service - no root required
  • Automatic startup on boot
  • Smart Node.js detection works with nvm, fnm, or global npm
  • Comprehensive systemd commands for status, logs, start/stop

🎨 UI Improvements

  • Mobile Terminal Experience (#441)

    • Fixed keyboard layout issues on mobile devices
    • Improved quick keys bar with better sizing and spacing
    • Responsive text sizes that scale properly on smaller screens
    • Tab key now works correctly on mobile keyboards
  • Dark Mode & Theme Improvements

    • Improved theme toggle with clearer icon and tooltips (#438, fixes #368)
    • Fixed new session dialog styling for dark mode (#433)
    • Better contrast and visibility across all themes
  • General UI Polish

    • Clickable ngrok URLs in Settings with copy button (#422)
    • Cleaner session headers with better-positioned controls
    • Fixed magic wand icon alignment for AI sessions
    • Edit icons now positioned directly after text instead of far right
    • Improved OPTIONS label alignment in session create form

🐛 Bug Fixes

  • Fixed session timers continuing to run after sessions exited (#428)
  • Fixed sessions with undefined activity status showing as idle instead of active
  • Fixed new session dialog styling for dark mode (#433)
  • Fixed Mintlify documentation generation (#434)
  • Fixed ConfigManager threading crash when moving quick start items in macOS
  • Fixed mobile keyboard layout and text sizing issues (#441)
  • Improved Chinese input method support (#431, duplicate of #421)
  • Fixed OpenCode support for better integration with external apps

🏗️ Under the Hood

Code Quality & Architecture (#444)

  • Extracted all magic strings to centralized constants files
  • Created dedicated constant files for:
    • API endpoints, bundle identifiers, environment keys
    • Error messages, file paths, keychain constants
    • Network constants, notification names, UI strings
    • URL constants and user defaults keys
  • Removed RepositoryPathSyncService and related WebSocket sync code
  • Improved type safety and maintainability across the codebase

Configuration System Overhaul (#436)

  • New file-based configuration system with ~/.vibetunnel/config.json
  • ConfigManager for synchronized settings between Mac and web
  • REST API at /api/config replacing WebSocket sync
  • Zod schema validation for all configuration data
  • Automatic file watching for real-time config updates
  • Repository base path now stored in config instead of CLI args

Testing & Development

  • Added comprehensive test coverage for new components
  • Improved test maintainability by adding element IDs to web components
  • Added AutocompleteService tests and drag & drop tests
  • Enhanced CI workflows with better error diagnostics

Documentation & Cleanup

  • Major codebase cleanup - removed Tauri project and 17k lines of unused code (#419)
  • Enhanced release process with better troubleshooting documentation
  • Updated README with proper badges and table of contents
  • Removed redundant header text and improved visual hierarchy

👥 Contributors

First-time contributors to VibeTunnel:

  • @gopikori - Made ngrok URLs clickable with copy button in Settings (#422)
  • @claudemini - Improved theme toggle UI with better icon and tooltips (#438)

Additional contributors:

  • @hewigovens - Fixed mobile keyboard issues and co-authored systemd support (#426, #441)

[1.0.0-beta.13] - 2025-07-19

Terminal Performance Mode (Experimental)

  • New binary WebSocket mode for terminal sessions dramatically improves performance for high-throughput operations (#412)
  • Toggle between standard SSE mode and high-performance binary mode in terminal settings
  • Binary mode significantly reduces latency and CPU usage when running commands with heavy output
  • Seamless switching between modes without losing your session

Enhanced Terminal Control

  • Uninstall option for the vt command line tool now available in settings (#407)
  • Simple trash icon button to cleanly remove the CLI tool when needed
  • Proper cleanup of both standard and Homebrew installation paths

Screen Sharing Removed

  • Removed screen sharing feature to focus on core terminal functionality (#415)
  • Eliminated ~17,000 lines of WebRTC and screen capture code
  • No longer requests screen recording permissions
  • Screen Sharing is out of scope for the 1.0 release

🐛 Bug Fixes

  • Fixed server crashes when using special characters (like *) in terminal status messages (#398)
  • Resolved "Kill All Sessions" button failing silently in compact/sidebar view (#418)
  • Fixed network bind address reverting to localhost after server restarts (#404)
  • Ghostty terminal now properly spawns and executes commands if there are no windows (#408)

📚 Documentation

  • Added complete HQ mode documentation covering distributed deployments
  • Organized all documentation into logical categories with Mintlify

👥 Contributors

First-time contributors to VibeTunnel:

  • @hewigovens - Added systemd service management for Linux deployments, refactored installer for user-level services with improved security (#419)

[1.0.0-beta.12] - 2025-07-17

Welcome Screen Performance

  • Background folder scanning eliminates UI freeze when opening the welcome screen (#394)
  • Improved startup performance with optimized web directory structure
  • Much smoother experience when working with large project directories

SSH Agent Reliability

  • Fixed SSH key generation errors on non-localhost HTTP connections (#392)
  • SSH agent now works correctly when accessing VibeTunnel via ngrok or from another device
  • Improved security and reliability for remote access scenarios

npm Package Stability

  • Fixed critical installation issues on Linux systems (#393)
  • authenticate-pam now properly handled as optional dependency
  • Enhanced cross-platform compatibility for Ubuntu and other distributions
  • Comprehensive vt command tests ensure reliability across environments

Developer Experience

  • Fixed missing public directory in Mac app bundle (#392)
  • Resolved TypeScript type annotations throughout codebase
  • Improved lint compliance and code quality
  • Streamlined CI/CD workflow for more reliable builds

🐛 Bug Fixes

  • Fixed vt command syntax errors on Linux systems (#393)
  • Fixed welcome screen lag during folder scanning (#394)
  • Resolved missing icons and resources in Mac app
  • Fixed lint and type errors across the codebase
  • Cleaned up duplicate and stray files from web directory

👥 Contributors

First-time contributors to VibeTunnel:

  • @amazanov - Fixed PAM module and npm_config_prefix issues on Ubuntu, improving Linux compatibility (#380)

[1.0.0-beta.11] - 2025-07-17

Better Settings Organization

  • Reorganized settings into logical tabs for easier navigation (#359)
  • Repository base path now syncs automatically between Mac app and web UI (#358)
  • Simplified welcome screen repository display (#372)

UI Context Awareness

  • Spawn window toggle shows only when relevant (#357)

NPM Package Now Available

  • vibetunnel (server) is now available as an npm package for easy installation on macOS and Linux (#360, #377)
  • Install with npm install -g vibetunnel - no build tools required!
  • Includes prebuilt binaries for Node.js 20, 22, 23, and 24
  • Supports macOS (Intel and Apple Silicon) and Linux (x64 and arm64) (#344)

Enhanced Git Diff Tool Support

  • Added JuxtaCode to the list of supported Git diff tools with automatic detection

Improved vt Command

  • Added verbosity control with -q (quiet), -v (verbose), -vv (extra verbose) flags (#356)
  • New vt title command to update session names from within a VibeTunnel session (via @tarasenko)

🐛 Bug Fixes

  • Fixed npm package installation issues (#360, #377)
  • Fixed control message processing loop (#372)
  • Fixed file browser constant refresh issue (#354)
  • Replaced bell icon with settings icon for better clarity (#366)
  • Resolved Tailwind CSS performance warning

👥 Contributors

First-time contributors to VibeTunnel:

  • @janremes - Implemented Git repository discovery with folder selection and automatic repo detection (#274)
  • @lukeswitz - Fixed duplicate session creation with intelligent detection logic (#345)

[1.0.0-beta.10] - 2025-07-15

Repository Discovery

  • Automatic Git repository detection when creating new sessions (#301) (via @mrshu)
  • Recently modified repositories displayed in new session dialog
  • Quick project access with one-click repository selection

Keyboard Shortcut Handling

  • Redesigned keyboard capture system with intelligent priority handling (#298) (via @tarasenko)
  • Browser shortcuts work naturally: Cmd+Shift+A (tab search), Cmd+1-9 (tab switching), Alt+Arrow keys
  • Visual keyboard capture indicator with detailed tooltips
  • Double-Escape toggle for switching between browser and terminal keyboard modes

Theme System

  • Dracula theme is now the default for new users (#349)
  • Professional light mode with improved contrast (#314)
  • Easy theme switching between light and dark modes
  • Enhanced terminal color schemes (#332)

    Development Server Mode

  • New "Development Server" mode in Debug Settings enables hot reload (#316)
  • Significantly faster iteration when developing the web interface
  • Hot reload works with full VibeTunnel functionality

🐛 Bug Fixes

  • Fixed Safari clipboard paste on iOS and macOS (#336)
  • Fixed duplicate session creation with intelligent detection (#345) (via @lukeswitz)
  • Added keyboard navigation in session grid (arrow keys, Enter, etc.) (#322)
  • Fixed race conditions in network access mode (#347)
  • Improved SSH key manager modal layout (#325) (via @hewigovens)
  • Updated all dependencies to latest stable versions
  • Enhanced TypeScript configuration with better type safety

👥 Contributors

First-time contributors to VibeTunnel:

  • @davidgomesdev - Transformed SessionListView to clean MVVM architecture for better maintainability (#217)
  • @jeffhurray - Consolidated z-index management to prevent UI layer conflicts (#291)
  • @hewigovens - Fixed SSH key manager modal layout and improved test compatibility (#325)
  • @tarasenko - Added browser keyboard shortcut support with intelligent priority handling (#298)

[1.0.0-beta.9] - 2025-07-11

Terminal Crash Fix

  • Replaced Microsoft's node-pty with custom fork to resolve random terminal crashes (#304)
  • Improved thread-safe operations and resource management
  • Addresses stability issues affecting VS Code and other Electron applications

Server Crash Detection

  • Added crash detection and recovery system for server failures (#308)
  • Provides immediate feedback with specific error codes
  • Improved troubleshooting and error reporting

Mobile Experience

  • Fixed continuous resize loop on mobile devices (#305)
  • Improved mobile terminal width management
  • Added support for smaller grid sizes on compact devices
  • Added Alt+Delete/Left/Right keyboard shortcuts for mobile users (#290)
  • Fixed mobile header overflow when using dropdown menus (#295)

    Cloudflare Integration

  • Improved tunnel setup with stream-based monitoring (#306)
  • Enhanced error handling and more reliable setup process

Git Repository Discovery

  • Enhanced folder selection when creating new sessions (#274) (via @janremes)
  • Added intelligent Git repository discovery in selected folders
  • Fixed multiple bugs in repository discovery (#282)

🐛 Bug Fixes

  • Fixed terminal titles jumping due to activity indicators (#309)
  • Consolidated z-index management to prevent UI layer conflicts (#291) (via @jeffhurray)
  • Enhanced event handling for better cross-platform compatibility
  • Improved file browser functionality with better click handling

👥 Contributors

First-time contributors to VibeTunnel:

  • @claywarren - Fixed infinite scroll loop that could freeze the browser (#206)
  • @luisnell - Added Apple Silicon Homebrew path check for VT tool installation

[1.0.0-beta.8] - 2025-07-08

🐛 Bug Fixes

  • Fixed release builds to correctly bundle all Homebrew library dependencies (#269)
  • Fixed app launch on systems without developer tools installed
  • Fixed file browser going dark due to event bubbling issues with modal handling
  • Updated build scripts to handle dynamic library dependencies properly

[1.0.0-beta.7] - 2025-07-08

AI Session Context Injection

  • Inject project context into Claude.ai sessions with a single click (#210, #218)
  • Automatically detects Claude browser windows
  • Includes git repository details, current branch, and recent commits
  • Configurable prompts to match workflow

Terminal Performance

  • Fixed critical flow control issue causing xterm.js buffer overflow (#223)
  • Fixed infinite scroll loop that could freeze the browser
  • Fixed race conditions in terminal output handling
  • Improved memory management for long-running sessions
  • Better handling of high-volume terminal output

UI Performance

  • Removed UI animations causing 1-2 second delays
  • Disabled View Transitions API for instant session navigation
  • Fixed modal backdrop pointer-events issues (#195)
  • Smoother menu bar UI without jumping

Touch Device & Mobile

  • Unified keyboard layout for all mobile devices
  • Universal touch device detection
  • Inline-edit pencil always visible on touch devices
  • New compact keyboard layout optimized for tablets
  • Fixed touch interaction issues with modals

Fish Shell Integration

  • Full support for Fish shell command expansion and completions (#228, #242)
  • Proper handling of Fish-specific syntax
  • Fixed shell configuration files not being loaded

Developer Experience

  • Preserve Swift package resolution for faster builds
  • Better Node.js detection handling fnm/homebrew conflicts (#246, #253)
  • Hash-based vt script version detection
  • Delete old sessions when VibeTunnel version changes (#254)

🐛 Bug Fixes

  • Fixed session state synchronization between web and native clients
  • Resolved memory leaks in long-running sessions
  • Fixed connection timeout issues on slower networks
  • Better cleanup of terminal processes and resources
  • Fixed various UI glitches and visual artifacts
  • Resolved sidebar animation issues
  • Fixed file browser problems
  • Unified control protocol for terminal sessions (#239)
  • Improved Unix socket handling with better error recovery

👥 Contributors

First-time contributors to VibeTunnel:

  • @deveshseth - Fixed responsive layout issues preventing proper desktop mode transition (#201)
  • @raghavsethi - Added fish shell expansion support with proper syntax handling (#228, #242)
  • @raghavsethi - Fixed Xcode Node.js detection issues with fnm/homebrew conflicts (#246, #253)
  • @sandeepjak2007 - Added paste button to quick keyboard for improved iOS usability (#227)
  • @Dimillian - Fixed WebSocket and terminal resize loop on iOS devices (#224)

[1.0.0-beta.6] - 2025-07-03

Git Repository Monitoring

  • Real-time Git status in session rows with branch name and change counts (#200)
  • Color-coded status: orange for branches, yellow for uncommitted changes
  • Click folder icons to open repositories in Finder
  • Context menu option to open repositories on GitHub
  • 5-second cache prevents excessive git commands
  • Automatically finds git repositories in parent directories

Enhanced Command-Line Tool

  • vt title can set terminal title - even Claude can use it! (#153)
  • vt help displays binary path, version, build date, and platform info
  • Automatic detection of Homebrew installations on ARM Macs

Menu Bar Enhancements

  • Powerful menu bar with visual activity indicators (#176)
  • See all terminal sessions and Claude Code status (#160)
  • Mac stays awake when running terminal sessions

Web Interface Improvements

  • Complete UI overhaul with improved color scheme and animations (#179)
  • Collapsible sidebar to maximize terminal viewing space (#175)
  • Fixed race conditions causing sessions to appear as "missing"
  • Improved responsive design with better touch targets

🐛 Bug Fixes

  • Fixed terminal output corruption from race conditions
  • Fixed terminal titles jumping or getting stuck
  • Fixed double logger initialization deleting log files
  • Improved PTY manager cleanup and timer management
  • Enhanced error handling throughout server stack

Simplified Tailscale Setup

  • Switched to Tailscale's local API for easier configuration (#184)
  • Removed manual token management requirements
  • Streamlined connection UI

👥 Contributors

First-time contributors to VibeTunnel:

  • @noppe - Enabled scrolling in ConnectionView for narrow windows, improving UI accessibility
  • @tarasenko - Added title mode support and enhanced CLI installation verification (#153)

[1.0.0-beta.5] - 2025-06-29

UI Improvements

  • Web interface now shows full version including beta suffix
  • Cleaner build output by filtering non-actionable Xcode warnings
  • Fixed scrolling issues on mobile web browsers

Infrastructure

  • Web version automatically reads from package.json at build time
  • Build process validates version consistency between macOS and web
  • Tests only run when relevant files change (iOS/Mac/Web)
  • Comprehensive Playwright tests for web frontend reliability (#120)

🐛 Bug Fixes

  • Fixed authentication-related error messages when running with --no-auth
  • Fixed frontend log streaming in no-auth mode
  • Resolved flaky tests and improved test infrastructure (#205)
  • Enhanced release process documentation with version sync requirements
  • Better test fixtures, helpers, and debugging capabilities (#73)
  • Cleaner logs when running in development mode

👥 Contributors

First-time contributors to VibeTunnel:

  • @manuelmaly - Added gemini quick start button and slash commands for enhanced workflow (#128, #138)
  • @billyb2 - Fixed repeated screen recording permission dialogs for better user experience

[1.0.0-beta.4] - 2025-06-25

  • We replaced HTTP Basic auth with System Login or SSH Keys for better security (#43).
  • Sessions now show exited terminals by default - no more hunting for terminated sessions
  • Reorganized sidebar with cleaner, more compact header and better button placement
  • Added user menu in sidebar for quick access to settings and logout
  • Enhanced responsive design with better adaptation to different screen sizes
  • Improved touch targets and spacing for mobile users
  • Leverages View Transitions API for smoother animations with CSS fallbacks
  • More intuitive default settings for better out-of-box experience

👥 Contributors

First-time contributors to VibeTunnel:

  • @hjanuschka - Implemented authentication system with SSH key management for better security (#43)
  • @hjanuschka - Added screen sharing functionality with WebRTC (later removed in beta.13) (#209)
  • @chrisreyn - Fixed double shell-wrapping issues for aliases in vt script (#132)

[1.0.0-beta.3] - 2025-06-23

There's too much to list! This is the version you've been waiting for.

  • Redesigned, responsive, animated frontend.
  • Improved terminal width spanning and layout optimization
  • File-Picker to see files on-the-go.
  • Creating new Terminals is now much more reliable.
  • Added terminal font size adjustment in the settings dropdown
  • Fresh new icon for Progressive Web App installations
  • Refined bounce animations for a more subtle, professional feel
  • Added retro CRT-style phosphor decay visual effect for closed terminals
  • Fixed buffer aggregator message handling for smoother terminal updates
  • Better support for shell aliases and improved debug logging
  • Enhanced Unix socket server implementation for faster local communication
  • Special handling for Warp terminal with custom enter key behavior
  • New dock menu with quick actions when right-clicking the app icon
  • More resilient vt command-line tool with better error handling
  • Ensured vibetunnel server properly terminates when Mac app is killed

👥 Contributors

First-time contributors to VibeTunnel:

  • @tarasenko - Added Bonjour/mDNS service discovery for iOS app connectivity (#226)
  • @PiotrBosak - Updated README documentation for clarity
  • @zhouzhuojie - Added Cloudflare Quick Tunnel as a new access option

[1.0.0-beta.2] - 2025-06-19

🎨 Improvements

  • Redesigned slick new web frontend
  • Faster terminal rendering in the web frontend
  • New Sessions spawn new Terminal windows. (This needs Applescript and Accessibility permissions)
  • Enhanced font handling with system font priority
  • Better async operations in PTY service for improved performance
  • Improved window activation when showing the welcome and settings windows
  • Preparations for Linux support

🐛 Bug Fixes

  • Fixed window front order when dock icon is hidden
  • Fixed PTY service enhancements with proper async operations
  • Fixed race condition in session creation that caused frontend to open previous session

👥 Contributors

First-time contributors to VibeTunnel:

  • @moffmann - Updated CONTRIBUTING.md documentation

[1.0.0-beta.1] - 2025-06-17

🎉 First Public Beta Release

This is the first public beta release of VibeTunnel, ready for testing by early adopters.

✨ What's Included

  • Complete terminal session proxying to web browsers
  • Support for multiple concurrent sessions
  • Real-time terminal rendering with full TTY support
  • Secure password-protected dashboard
  • Tailscale and ngrok integration for remote access
  • Automatic updates via Sparkle framework
  • Native macOS menu bar application

🐛 Bug Fixes Since Internal Testing

  • Fixed visible circle spacer in menu (now uses Color.clear)
  • Removed development files from app bundle
  • Enhanced build process with automatic cleanup
  • Fixed Sparkle API compatibility for v2.7.0

📝 Notes

  • This is a beta release - please report any issues on GitHub
  • Auto-update functionality is fully enabled
  • All core features are stable and ready for daily use

✨ What's New Since Internal Testing

  • Improved stability and performance
  • Enhanced error handling for edge cases
  • Refined UI/UX based on internal feedback
  • Better session cleanup and resource management
  • Optimized for macOS Sonoma and Sequoia

🐛 Known Issues

  • Occasional connection drops with certain terminal applications
  • Performance optimization needed for very long sessions
  • Some terminal escape sequences may not render perfectly

📝 Notes

  • This is a beta release - please report any issues on GitHub
  • Auto-update functionality is fully enabled
  • All core features are stable and ready for daily use

[1.0.0] - 2025-06-16

🎉 Initial Release

VibeTunnel is a native macOS application that proxies terminal sessions to web browsers, allowing you to monitor and control terminals from any device.

✨ Core Features

Terminal Management

  • Terminal Session Proxying - Run any command with vt prefix to make it accessible via web browser
  • Multiple Concurrent Sessions - Support for multiple terminal sessions running simultaneously
  • Session Recording - All sessions automatically recorded in asciinema format for later playback
  • Full TTY Support - Proper handling of terminal control sequences, colors, and special characters
  • Interactive Commands - Support for interactive applications like vim, htop, and more
  • Shell Integration - Direct shell access with vt --shell or vt -i

Web Interface

  • Browser-Based Dashboard - Access all terminal sessions at http://localhost:4020
  • Real-time Terminal Rendering - Live terminal output using asciinema player
  • WebSocket Streaming - Low-latency real-time updates for terminal I/O
  • Mobile Responsive - Fully functional on phones, tablets, and desktop browsers
  • Session Management UI - Create, view, kill, and manage sessions from the web interface

Security & Access Control

  • Password Protection - Optional password authentication for dashboard access
  • Keychain Integration - Secure password storage using macOS Keychain
  • Access Modes - Choose between localhost-only, network, or secure tunneling
  • Basic Authentication - HTTP Basic Auth support for network access

Remote Access Options

  • Tailscale Integration - Access VibeTunnel through your Tailscale network
  • ngrok Support - Built-in ngrok tunneling for public access with authentication
  • Network Mode - Local network access with IP-based connections

macOS Integration

  • Menu Bar Application - Lives in the system menu bar with optional dock mode
  • Launch at Login - Automatic startup with macOS
  • Auto Updates - Sparkle framework integration for seamless updates
  • Native Swift/SwiftUI - Built with modern macOS technologies
  • Universal Binary - Native support for both Intel and Apple Silicon Macs

CLI Tool (vt)

  • Command Wrapper - Prefix any command with vt to tunnel it
  • Claude Integration - Special support for AI assistants with vt --claude and vt --claude-yolo
  • Direct Execution - Bypass shell with vt -S for direct command execution
  • Automatic Installation - CLI tool automatically installed to /usr/local/bin

Server Implementation

  • Dual Server Architecture - Choose between Rust (default) or Swift server backends
  • High Performance - Rust server for efficient TTY forwarding and process management
  • RESTful APIs - Clean API design for session management
  • Health Monitoring - Built-in health check endpoints

Developer Features

  • Server Console - Debug view showing server logs and diagnostics
  • Configurable Ports - Change server port from default 4020
  • Session Cleanup - Automatic cleanup of stale sessions on startup
  • Comprehensive Logging - Detailed logs for debugging

🛠️ Technical Details

  • Minimum macOS Version: 14.0 (Sonoma)
  • Architecture: Universal Binary (Intel + Apple Silicon)
  • Languages: Swift 6.0, Rust, TypeScript
  • UI Framework: SwiftUI
  • Web Technologies: TypeScript, Tailwind CSS, WebSockets
  • Build System: Xcode, Swift Package Manager, Cargo, npm

📦 Installation

  • Download DMG from GitHub releases
  • Drag VibeTunnel to Applications folder
  • Launch from Applications or Spotlight
  • CLI tool (vt) automatically installed on first launch

🚀 Quick Start

# Monitor AI agents
vt claude

# Run development servers  
vt npm run dev

# Watch long-running processes
vt python train_model.py

# Open interactive shell
vt --shell

👥 Contributors

Created by:

First-time contributors to VibeTunnel:

  • @hjanuschka - Implemented comprehensive authentication system with SSH key management and PAM support (#43)
  • @hjanuschka - Added keyboard shortcut highlighter, fixed Japanese input duplication on iOS, and sleep prevention option (#114, #102, #146)

📄 License

VibeTunnel is open source software licensed under the MIT License.


Version History

Pre-release Development

The project went through extensive development before the 1.0.0 release, including:

  • Initial TTY forwarding implementation using Rust
  • macOS app foundation with SwiftUI
  • Integration of asciinema format for session recording
  • Web frontend development with real-time terminal rendering
  • Hummingbird HTTP server implementation
  • ngrok integration for secure tunneling
  • Sparkle framework integration for auto-updates
  • Comprehensive testing and bug fixes
  • UI/UX refinements and mobile optimizations