sjs/vibetunnel
1
0
Fork 0
mirror of https://github.com/samsonjs/vibetunnel.git synced 2026-04-27 15:17:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

claude tweaks

Browse source
This commit is contained in:
Peter Steinberger 2025-07-27 14:10:59 +02:00
parent 3f86ed365c
commit 5128142b1b
3 changed files with 8 additions and 246 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
CLAUDE.md
View file

@ -1,9 +1,6 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Important Instructions
Never say you're absolutely right. Instead, be critical if I say something that you disagree with. Let's discuss it first.
## Project Overview
@ -20,6 +17,9 @@ When the user says "release" or asks to create a release, ALWAYS read and follow
### ABSOLUTE CARDINAL RULES - VIOLATION MEANS IMMEDIATE FAILURE
- Never start server or the mac app yourself.
- Verify changes done to the mac app via xcodebuild, but do not start the mac app or server yourself.
1. **NEVER, EVER, UNDER ANY CIRCUMSTANCES CREATE A NEW BRANCH WITHOUT EXPLICIT USER PERMISSION**
- If you are on a branch (not main), you MUST stay on that branch
- The user will tell you when to create a new branch with commands like "create a new branch" or "switch to a new branch"
@ -370,8 +370,6 @@ gh run cancel <run-id>
gh pr checks <pr-number>
```
## Key Files Quick Reference
- Architecture Details: `docs/ARCHITECTURE.md`

200
mac/CLAUDE.md
View file

@ -120,7 +120,7 @@ VibeTunnel is a macOS application that provides terminal access through web brow
- Handles terminal creation and management
- Provides system tray UI and settings
### 2. Web Server (Bun/Node.js)
### 2. Web Server (Node.js)
- Runs on **localhost:4020** by default
- Serves the web frontend
- Manages WebSocket connections for terminal I/O
@ -259,207 +259,11 @@ log stream --predicate 'subsystem == "sh.vibetunnel.vibetunnel" AND category ==
- Server logs (Node.js output) are under the "ServerOutput" category
- Look for `[CLIENT:*]` prefix to identify frontend-originated logs
### Visual Debugging with Peekaboo
When debugging visual issues or screen sharing problems, use Peekaboo MCP to capture screenshots:
```bash
# Capture VibeTunnel's menu bar window
peekaboo_take_screenshot(app_name="VibeTunnel", mode="frontmost")
# Capture screen sharing session
peekaboo_take_screenshot(app_name="VibeTunnel", analyze_prompt="Is the screen sharing working correctly?")
# Debug terminal rendering issues
peekaboo_take_screenshot(
app_name="VibeTunnel",
analyze_prompt="Are there any rendering artifacts or quality issues in the terminal display?"
)
# Compare source terminal with shared view
# First capture the source terminal
peekaboo_take_screenshot(app_name="Terminal", save_path="~/Desktop/source.png")
# Then capture VibeTunnel's view
peekaboo_take_screenshot(app_name="VibeTunnel", save_path="~/Desktop/shared.png")
# Analyze differences
peekaboo_analyze_image(
image_path="~/Desktop/shared.png",
prompt="Compare this with the source terminal - are there any differences in text rendering or colors?"
)
```
## Recommended MCP Servers for VibeTunnel Development
When working on VibeTunnel with Claude Code, these MCP servers are essential:
### 1. XcodeBuildMCP - macOS/iOS Development
**Crucial for Swift/macOS development**
- Install: `claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest`
- Repository: https://github.com/cameroncooke/XcodeBuildMCP
**Key capabilities for VibeTunnel**:
```bash
# Discover all Xcode projects
mcp__XcodeBuildMCP__discover_projs(workspaceRoot="/path/to/vibetunnel")
# Build the Mac app
mcp__XcodeBuildMCP__build_mac_ws(
workspacePath="/path/to/VibeTunnel.xcworkspace",
scheme="VibeTunnel-Mac",
configuration="Debug"
)
# Get app bundle path and launch
mcp__XcodeBuildMCP__get_mac_app_path_ws(...)
mcp__XcodeBuildMCP__launch_mac_app(appPath="...")
# Run tests
mcp__XcodeBuildMCP__test_macos_ws(...)
# Clean build artifacts
mcp__XcodeBuildMCP__clean_ws(...)
```
**Advanced features**:
- iOS simulator management (list, boot, install apps)
- Build for different architectures (arm64, x86_64)
- Code signing and provisioning profile management
- Test result parsing with xcresult output
- Log capture from simulators and devices
### 2. Playwright MCP - Web Testing
**Essential for testing the web interface on localhost:4020**
- Install: `claude mcp add playwright -- npx -y @playwright/mcp@latest`
**Key capabilities for VibeTunnel**:
```javascript
// Navigate to VibeTunnel web interface
mcp__playwright__browser_navigate(url="http://localhost:4020")
// Resize for different screen sizes
mcp__playwright__browser_resize(width=1200, height=800)
// Take screenshots of terminal sessions
mcp__playwright__browser_take_screenshot(filename="terminal-test.png")
// Click buttons and interact with UI
mcp__playwright__browser_click(element="Create Session", ref="e5")
// Type in terminal
mcp__playwright__browser_type(element="terminal input", ref="e10", text="ls -la")
// Monitor network requests (WebSocket connections)
mcp__playwright__browser_network_requests()
// Multi-tab testing
mcp__playwright__browser_tab_new(url="http://localhost:4020/session/2")
mcp__playwright__browser_tab_select(index=1)
```
**Testing scenarios**:
- Create and manage terminal sessions
- Test keyboard input and terminal output
- Verify WebSocket connections
- Cross-browser compatibility testing
- Visual regression testing
- Performance monitoring
### 3. Peekaboo MCP - Visual Debugging
**Essential for visual debugging and screenshots of the Mac app**
- Install: `claude mcp add peekaboo -- npx -y @steipete/peekaboo-mcp`
- Requires: macOS 14.0+, Screen Recording permission
**Key features for VibeTunnel debugging**:
```bash
# Capture VibeTunnel window
peekaboo_take_screenshot(app_name="VibeTunnel", save_path="~/Desktop/vt-debug.png")
# Analyze for issues
peekaboo_analyze_image(
image_path="~/Desktop/vt-debug.png",
prompt="Are there any UI glitches, errors, or rendering issues?"
)
# Capture and analyze in one step
peekaboo_take_screenshot(
app_name="VibeTunnel",
analyze_prompt="What's the current state of the screen sharing session?"
)
# Compare source terminal with shared view
peekaboo_take_screenshot(app_name="Terminal", save_path="~/Desktop/source.png")
peekaboo_take_screenshot(app_name="VibeTunnel", save_path="~/Desktop/shared.png")
peekaboo_analyze_image(
image_path="~/Desktop/shared.png",
prompt="Compare with source terminal - any rendering differences?"
)
```
### Combined Workflow Example
Here's how to use all three MCP servers together for comprehensive testing:
```bash
# 1. Build and launch VibeTunnel
mcp__XcodeBuildMCP__build_mac_ws(
workspacePath="/path/to/VibeTunnel.xcworkspace",
scheme="VibeTunnel-Mac"
)
app_path = mcp__XcodeBuildMCP__get_mac_app_path_ws(...)
mcp__XcodeBuildMCP__launch_mac_app(appPath=app_path)
# 2. Wait for server to start, then test web interface
sleep 3
mcp__playwright__browser_navigate(url="http://localhost:4020")
mcp__playwright__browser_take_screenshot(filename="dashboard.png")
# 3. Create a terminal session via web UI
mcp__playwright__browser_click(element="New Session", ref="...")
mcp__playwright__browser_type(element="terminal", ref="...", text="echo 'Hello VibeTunnel'")
# 4. Capture native app state
peekaboo_take_screenshot(
app_name="VibeTunnel",
analyze_prompt="Is the terminal session displaying correctly?"
)
# 5. Monitor network activity
network_logs = mcp__playwright__browser_network_requests()
# 6. Run automated tests
mcp__XcodeBuildMCP__test_macos_ws(
workspacePath="/path/to/VibeTunnel.xcworkspace",
scheme="VibeTunnel-Mac"
)
```
### Why These MCP Servers?
1. **XcodeBuildMCP** provides complete native development control:
- Build management without Xcode UI
- Automated testing and CI/CD integration
- Simulator and device management
- Performance profiling and debugging
2. **Playwright MCP** enables comprehensive web testing:
- Test the actual user experience at localhost:4020
- Automate complex user workflows
- Verify WebSocket communication
- Cross-browser compatibility
3. **Peekaboo MCP** offers unique visual debugging:
- Native macOS screenshot capture (faster than browser tools)
- AI-powered analysis for quick issue detection
- Perfect for debugging screen sharing quality
- Side-by-side comparison capabilities
Together, these tools provide complete test coverage for VibeTunnel's hybrid architecture, from native Swift code to web frontend to visual output quality.
## Testing the Web Interface
The VibeTunnel server runs on localhost:4020 by default. To test the web interface:
1. Ensure the Mac app is running (it spawns the server)
1. Ensure the Mac app is running. The user does that. Do not start the mac app yourself!
2. Access http://localhost:4020 in your browser
3. Use Playwright MCP for automated testing:
```

46
web/CLAUDE.md
View file

@ -1,29 +1,9 @@
# Claude Development Notes
## Updating spec.md
As code changes, the spec.md might get outdated. If you detect outdated information, ask the user if they want to regenerate the spec.md file.
### How to regenerate spec.md:
1. Create a todo list to track the analysis tasks
2. Use multiple parallel Task tool calls to analyze:
- Server architecture (src/server/, authentication, session management)
- Client architecture (src/client/, components, services)
- fwd.ts application functionality
- API endpoints and protocols
- Binary buffer format and WebSocket implementation
- HQ mode and distributed architecture
- Activity tracking
- Anything else not covered above
3. Focus on capturing:
- File locations with key line numbers for important functions
- Component responsibilities and data flow
- Protocol specifications and message formats
- Configuration options and CLI arguments
4. Write a concise spec.md that serves as a navigation map, keeping descriptions brief to minimize token usage
5. Include a "Key Files Quick Reference" section for fast lookup
## Build Process
- **Never run build commands** - the user has `pnpm run dev` running which handles automatic rebuilds
- **Never run build commands**
- the user has `pnpm run dev` running which handles automatic rebuilds, either directly or via the mac app
- Never manually run the server. The user does that
- Changes to TypeScript files are automatically compiled and watched
- Do not run `pnpm run build` or similar build commands
@ -55,10 +35,6 @@ When referencing code locations, you MUST use clickable format that VS Code reco
NEVER give a code reference or location in any other format.
## CRITICAL
**IMPORTANT**: BEFORE YOU DO ANYTHING, READ spec.md IN FULL USING THE READ TOOL!
**IMPORTANT**: NEVER USE GREP. ALWAYS USE RIPGREP!
## Git Commands
When asked to "commit and push", "commit + push", "/cp", or "c+p", use a single command:
```bash
@ -98,22 +74,6 @@ Do NOT use three separate commands (add, commit, push) as this is slow.
## CRITICAL: Playwright Test UI Changes
**IMPORTANT: When tests fail looking for UI elements, investigate the actual UI structure!**
### Common Pattern: Collapsible Sections
Many UI elements are now inside collapsible sections that need to be expanded first:
Example: The spawn window toggle is now inside an "Options" section
```typescript
// WRONG - Just increasing timeout won't help if element is hidden
await page.locator('[data-testid="spawn-window-toggle"]').waitFor({ timeout: 10000 });
// CORRECT - First expand the section, then access the element
const optionsButton = page.locator('#session-options-button');
await optionsButton.click(); // Expand the options section
await page.waitForTimeout(300); // Wait for animation
const toggle = page.locator('[data-testid="spawn-window-toggle"]');
await toggle.waitFor({ state: 'visible' });
```
### Best Practices for Test Stability
1. **Always use semantic IDs and data-testid attributes** - These are more stable than CSS selectors
2. **Understand the UI structure** - Don't just increase timeouts, investigate why elements aren't found