surfmon 0.3.6

Monitor Windsurf and Windsurf Next resource usage and diagnose problems

Surfmon

Surface Monitor for Windsurf IDE — a performance monitoring and diagnostics tool for Windsurf (Stable and Next).

Table of Contents

• Installation
• Quick Start
• Why Use Surfmon?
• Commands
  • check — Quick Performance Snapshot
  • watch — Live Monitoring Dashboard
  • analyze — Historical Trend Analysis
  • compare — Before/After Diff
  • cleanup — Remove Orphaned Processes
  • prune — Deduplicate Watch Reports
• What It Monitors
• Auto-Detection
• Exit Codes
• Common Issues
• Development
  • Package Structure
  • Running Tests
  • Dependencies
  • Requirements
  • Creating Screenshots

Installation

pip install surfmon

Or with uv:

uv tool install surfmon

Or run directly without installing:

uvx surfmon check    # Using uvx
pipx run surfmon check    # Using pipx

For development:

git clone https://github.com/detailobsessed/surfmon.git
cd surfmon
uv sync

Quick Start

# One-shot health check
surfmon check

# Verbose output with all process details
surfmon check -v

# Save reports (auto-named with timestamp, enables verbose output)
surfmon check -s

# Target a specific Windsurf installation
surfmon check -t next

Why Use Surfmon?

• 🔍 Debug Performance Issues — Identify memory leaks, CPU spikes, and resource bottlenecks
• 📊 Monitor Over Time — Track resource usage trends with watch sessions and historical analysis
• 🧹 Clean Up Resources — Remove orphaned processes and duplicate reports
• 🔧 Troubleshoot Crashes — Detect extension host crashes, language server issues, and PTY leaks
• 📈 Visualize Trends — Generate matplotlib plots showing resource usage over time

Commands

check — Quick Performance Snapshot

The main command. Shows system resources, Windsurf memory/CPU, active workspaces, top processes, and language servers in consistent fixed-width tables.

surfmon check                        # Basic check
surfmon check -v                     # Verbose (all processes)
surfmon check -s                     # Auto-save JSON + Markdown reports (enables verbose)
surfmon check --json report.json     # Save JSON to specific path
surfmon check --md report.md         # Save Markdown to specific path
surfmon check --json r.json --md r.md  # Save both formats with custom names

watch — Live Monitoring Dashboard

Continuously monitors Windsurf with a live-updating terminal dashboard. Saves periodic JSON snapshots for historical analysis.

surfmon watch                          # Default: 5s interval, save every 5min to ../reports/watch
surfmon watch -i 10 -s 600             # Check every 10s, save every 10min
surfmon watch -i 10 -n 720             # 720 checks = 2 hours
surfmon watch -o ~/windsurf-reports    # Custom output directory

analyze — Historical Trend Analysis

Analyzes JSON reports from watch sessions (or any directory containing JSON reports) to detect memory leaks, process growth, and performance degradation. Optionally generates a 9-panel matplotlib visualization.

surfmon analyze reports/watch/20260204-134518/
surfmon analyze reports/watch/20260204-134518/ --plot
surfmon analyze reports/watch/20260204-134518/ --plot --output analysis.png

Terminal Output:

Generated Matplotlib Visualization:

compare — Before/After Diff

surfmon check --json before.json
# ... make changes ...
surfmon check --json after.json
surfmon compare before.json after.json

cleanup — Remove Orphaned Processes

Detects and kills orphaned chrome_crashpad_handler processes left behind after Windsurf exits. Windsurf must be closed for this command to work.

surfmon cleanup             # Interactive (asks for confirmation)
surfmon cleanup --force     # No confirmation

prune — Deduplicate Watch Reports

Removes duplicate/identical JSON reports that accumulate during watch sessions when nothing changes.

surfmon prune reports/watch/20260204-134518/ --dry-run
surfmon prune reports/watch/20260204-134518/

What It Monitors

System — Total/available memory, memory %, swap, CPU cores

Windsurf Processes — Process count, total memory & CPU, top 10 by memory, thread counts

Language Servers — Detects and tracks basedpyright, JDT.LS, Codeium language servers, YAML/JSON servers

MCP Servers — Lists enabled MCP servers from Codeium config

Workspaces — Active workspace paths and load times

PTY Usage — Windsurf PTY allocation vs system limits

Issues — Orphaned crash handlers, extension host crashes, update service timeouts (NextDNS), telemetry failures, logs directory in extensions folder

Auto-Detection

Surfmon auto-detects whether Windsurf Stable or Windsurf Next is running and targets the active installation. Override with -t stable or -t next, or set SURFMON_TARGET in your environment.

Exit Codes

• 0 — No issues detected
• 1 — Issues detected (see output)
• 130 — Interrupted (Ctrl+C)

Common Issues

Issue	Cause	Fix
Orphaned crash handlers	Crash reporters not cleaned up on exit	surfmon cleanup --force
logs directory error	Marimo extension creates logs in wrong place	Move ~/.windsurf/extensions/logs
Update service timeouts	NextDNS blocking *.codeium.com	Whitelist in NextDNS
High memory usage	Too many language servers or extensions	Disable unused extensions

Development

Package Structure

src/surfmon/
    __init__.py        # Version
    cli.py             # Typer CLI — check, watch, compare, cleanup, prune, analyze
    config.py          # Target detection, paths, environment config
    monitor.py         # Core data collection — processes, language servers, MCP, PTYs
    output.py          # Rich terminal display and Markdown export
    compare.py         # Report comparison with colored diffs
tests/
    conftest.py        # Shared fixtures
    test_bugfixes.py   # Regression tests
    test_cli.py        # CLI command tests
    test_compare.py    # Report comparison tests
    test_config.py     # Configuration and target detection tests
    test_monitor.py    # Core monitoring logic tests
    test_output.py     # Display and formatting tests

Running Tests

poe test              # Run tests
poe test-cov          # Run with coverage
poe lint              # Ruff check
poe typecheck         # ty check

Dependencies

• psutil — Cross-platform process and system monitoring
• typer — CLI framework
• rich — Terminal output with tables and colors
• python-decouple — Environment configuration
• matplotlib — Visualization for analyze plots

Requirements

• Python 3.14+
• macOS (tested), Linux (untested), Windows (untested) though it should work
• Windsurf IDE installed

Creating Screenshots

Screenshots in this README were created using:

• Static images (termshot) - Captures terminal output as PNG
• Animated GIF (vhs) - Records terminal sessions as GIF

To recreate the watch GIF:

brew install vhs gifsicle

# Create tape file
cat > watch-demo.tape << 'EOF'
Output docs/screenshots/watch.gif
Set FontSize 13
Set Width 900
Set Height 400
Set Theme "Catppuccin Mocha"
Set BorderRadius 10
Set WindowBar Colorful
Set WindowBarSize 30
Type "uvx surfmon watch --interval 2 --max 15"
Enter
Sleep 32s
EOF

# Generate and optimize
vhs watch-demo.tape
gifsicle -O3 --colors 256 docs/screenshots/watch.gif -o docs/screenshots/watch.gif