sjs/vibetunnel
1
0
Fork 0
mirror of https://github.com/samsonjs/vibetunnel.git synced 2026-03-28 09:55:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
vibetunnel/CLAUDE.md
Mario Zechner 4a5052f425 refactor: improve PTY manager cleanup and fwd.ts architecture 
- Remove global exit handlers from PTY manager, add clean shutdown() method
- Use file watching approach for control pipes on all platforms (no FIFO)
- Simplify fwd.ts - control pipe and stdin forwarding handled by PTY manager
- Add forwardToStdout and onExit options to createSession
- Add proper TypeScript types to PtySession interface (no more "as any")
- Clean up logging throughout, keep only essential messages
- Add colorful output with chalk for session start/end messages
- Fix hanging process issue by properly unreferencing file watchers
- Update spec.md to reflect architectural changes

This makes the shutdown process predictable and fixes the hanging echo command issue.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-06-22 14:16:06 +02:00

2.6 KiB
Raw Blame History

CLAUDE.md

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

Project Overview

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

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

Critical Development Rules

  • Never commit and/or push before the user has tested your changes!
  • ABSOLUTELY SUPER IMPORTANT & CRITICAL: NEVER USE git rebase --skip EVER

Web Development Commands

IMPORTANT: The user has npm run dev running - DO NOT manually build the web project!

In the web/ directory:

# Development (user already has this running)
npm run dev

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

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

macOS Development Commands

In the mac/ directory:

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

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

Architecture Overview

Terminal Sharing Protocol

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

Key Entry Points

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

Testing

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

Key Files Quick Reference

  • API Documentation: docs/API.md
  • Architecture Details: docs/ARCHITECTURE.md
  • Server Implementation Guide: web/spec.md
  • Build Configuration: web/package.json, mac/Package.swift