mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-04-12 12:25:53 +00:00
4a5052f425
- 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>
83 lines
No EOL
2.6 KiB
Markdown
83 lines
No EOL
2.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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` |