v1.7.0 - UX Improvements & International Fix

What's New

UX Improvements

• App Search & Filter - Live search on My Apps tab (Ctrl+F), filters by name, command, or working directory
• Running Apps Summary - Header badge shows live count ("3 running" / "all stopped")
• Sort Options - Sort apps by name A-Z/Z-A, running status, or port number
• Group Colours - Assign a colour to each group; accent appears on the group header
• Quick Add Wizard - 8 one-click templates: npm dev, Vite, Next.js, Angular, Flask, FastAPI, Docker Compose, Static (Ctrl+Q)
• New Keyboard Shortcuts - Ctrl+F (search), Ctrl+Q (Quick Add), Ctrl+G (new group)
• Rich Tray Menu - Running apps listed individually with per-app Stop buttons; tooltip shows live count

Bug Fix

• Non-English Windows - Port scanning now works on all Windows locales (German, French, Spanish, etc.) - closes #4
  • Previously used findstr LISTENING which fails on non-English Windows (e.g. German shows "ABHÖREN")
  • Now detects listening sockets by foreign address ending in :0, which is locale-independent

Download

Platform	File
Windows Installer	PortPilot-1.7.0-x64.exe
Windows Portable	PortPilot-1.7.0-portable.exe

Linux builds coming soon - build from source in the meantime:

git clone https://github.com/m4cd4r4/PortPilot.git
cd PortPilot && npm install && npm start

Upgrading

Run the new installer over your existing installation - your config at %APPDATA%\portpilot\portpilot-config.json is preserved.

Full Changelog: v1.6.2...v1.7.0

v1.6.2

Full Changelog: v1.6.1...v1.6.2

v1.6.1

Full Changelog: v1.6.0...v1.6.1

v1.6.0 - Compact UI & MCP Auto-Refresh

PortPilot v1.6.0 - Compact UI & MCP Auto-Refresh

🎨 Compact & Sharp UI Redesign

30-40% More Density - See more apps and ports without scrolling

• Sharp 2px corners (modern, clean aesthetic)
• Tighter spacing throughout
• Compact port cards with Process+PID on one line
• Smaller fonts for better information density

🔄 MCP Auto-Refresh

External Changes Detected Automatically

• File watcher monitors config for changes (100ms debounce)
• Toast notifications when apps list updates
• No restart required when MCP adds apps
• Seamless integration with AI assistants

📐 Smart Window Auto-Resize

Dynamic Height Based on Content

• Window grows/shrinks based on number of apps
• 400px minimum, 1200px maximum
• No wasted space, no excessive scrolling
• Works seamlessly with MCP auto-refresh

🧪 Enhanced Testing

100% Test Coverage - All 11 E2E tests passing

• Integrated test HTTP servers (ports 3000, 3001, 8080)
• Test mode support (singleton lock bypass)
• Improved reliability with better wait strategies
• Fixed visibility issues with scrollIntoViewIfNeeded

🐛 Bug Fixes

• Critical: Fixed ConfigStore null reference crash on startup
• Tests: All 11 E2E tests now passing reliably
• Load Strategy: Improved app initialization wait logic

📦 Installation

Windows

• Installer: PortPilot-1.6.0-x64.exe (72 MB)
• Portable: PortPilot-1.6.0-portable.exe (72 MB)

Linux

• AppImage: PortPilot-1.6.0-x86_64.AppImage (98 MB)
• Debian/Ubuntu: PortPilot-1.6.0-amd64.deb (69 MB)

🔗 Links

• Landing Page
• Full Changelog
• MCP Integration Guide

---

Full Changelog: v1.5.0...v1.6.0

v1.5.0 - Linux Platform Support 🐧

🎉 v1.5.0 - Linux Platform Support

PortPilot now officially supports Windows AND Linux!

🐧 Linux Platform Support (NEW!)

• AppImage Package - Universal Linux binary that runs on any distro (98 MB)
• .deb Package - Native Debian/Ubuntu installer (69 MB)
• Cross-Platform Test Suite - Automated tests for Windows and Linux
• WSL Support - Build and test in Windows Subsystem for Linux
• Platform Auto-Detection - Automatically adapts to your OS

🖥️ System Tray & Window Behavior

• Stop All Apps from Tray - Right-click tray icon to stop all PortPilot-managed apps
• Configurable Close Button - Choose minimize to tray or exit completely
• Smart Process Cleanup - Optionally stop apps when quitting (only PortPilot-managed)
• External Process Safety - Never touches processes outside PortPilot

🔒 Single-Instance Lock

• One Instance Only - Prevents multiple copies from running
• Smart Window Focusing - Second launch focuses existing window
• Clean State - Single tray icon, no confusion

📦 Downloads

Windows

• PortPilot-1.5.0-x64.exe (72 MB) - NSIS Installer with desktop shortcut
• PortPilot-1.5.0-portable.exe (72 MB) - No installation required

Linux 🆕

• PortPilot-1.5.0-x86_64.AppImage (98 MB) - Universal Linux package
  • Works on Ubuntu, Fedora, Debian, Arch, and more
  • chmod +x PortPilot-1.5.0-x86_64.AppImage && ./PortPilot-1.5.0-x86_64.AppImage
• PortPilot-1.5.0-amd64.deb (69 MB) - Debian/Ubuntu package
  • sudo dpkg -i PortPilot-1.5.0-amd64.deb

🔧 Installation

Windows:

1. Download PortPilot-1.5.0-x64.exe
2. Run the installer
3. PortPilot will appear in your Start Menu and create a desktop shortcut

Linux:

# AppImage (any distro)
chmod +x PortPilot-1.5.0-x86_64.AppImage
./PortPilot-1.5.0-x86_64.AppImage

# Debian/Ubuntu
sudo dpkg -i PortPilot-1.5.0-amd64.deb

📊 What's Included

✅ Port scanning and management
✅ One-click process termination
✅ App registry with start commands
✅ Auto-discovery of dev projects
✅ Port conflict warnings
✅ System tray integration
✅ 6 beautiful themes
✅ Cross-platform support (Windows + Linux)

🐛 Bug Fixes & Improvements

• Enhanced platform detection for WSL environments
• Improved process cleanup on application quit
• Better window state management
• Cross-platform test suite for reliability

📝 Full Changelog

See CHANGELOG.md for complete details.

---

Tested on:

• ✅ Windows 10/11
• ✅ Ubuntu 20.04/22.04/24.04
• ✅ Debian 11/12
• ✅ WSL 2

Compatibility:

• No breaking changes
• Fully backwards compatible with v1.4.x configs

v1.4.0 - Browse & Auto-detect, Port Conflict Warnings, Enhanced Detection

🎉 What's New in v1.4.0

🔍 Browse & Auto-detect Project

• One-Click Project Setup — Click "Browse & Auto-detect" in Add App modal to automatically configure any project
• Recursive Scanning — Finds projects up to 2 levels deep in subdirectories
• Package Manager Detection — Auto-detects pnpm, yarn, or npm and uses the correct command
• Smart Port Detection — Only uses explicit port config (no more "everything gets port 3000")
• Works with Monorepos — Finds the actual project inside parent folders (e.g., manual-build/ inside root)

⚠️ Port Conflict Warnings

• Unknown Process Detection — Warns when unknown processes block your app's preferred port
• 🌐 Preview Button — Click globe to see what's running on the blocked port
• Kill Blocker Button — Terminate blocking processes with one click
• Toast Notifications — Visual warnings when port conflicts are detected
• Improved Matching — Two-phase algorithm with keyword extraction prevents false positives

🔍 Project Auto-Discovery

• Automatic Project Detection — Scan your project directories to automatically discover Node.js, Docker, Python, and static site projects
• Smart Metadata Extraction — Automatically detects project names, start commands, and ports
• User-Configurable Paths — Add your own scan directories (e.g., C:\Projects, C:\Dev)
• Confidence Scoring — Shows match confidence (95%, 85%, etc.) for each discovered project
• Bulk Import — Add all discovered projects at once or pick individual ones

⭐ Favorites System

• Star Your Apps — Click the star (⭐/☆) button to mark frequently-used apps as favorites
• Organized Sections — Apps automatically organized into Favorites and Other Projects
• Collapsible Sections — Click section headers to expand/collapse
• Persistent State — Section collapse state saved across app restarts

🗑 Delete All

• Bulk Delete — Remove all apps in one click with "Delete All" button
• Safety First — Strong confirmation modal warns before deletion
• Export Reminder — Prompts to export config before deleting

✨ Improvements

Port Matching Algorithm

• Two-phase matching with stricter validation
• Keyword extraction from app names (e.g., "AzurePrep" → ["azure", "prep"])
• No more false positives - apps only match if there's strong evidence
• Tracks unknown conflicts separately from confident matches

Port Detection

• Removed hard-coded framework defaults (no more "everything gets port 3000")
• Checks package.json scripts for --port or PORT= flags
• Checks vite.config.js/ts for explicit port configuration
• Checks .env/.env.local for PORT environment variable
• Returns null if no explicit port found

Find Free Port

• Now checks both system availability AND registered app ports
• Loops through candidates to find truly unique ports
• Prevents duplicate port assignments when multiple apps need ports

📥 Downloads

• PortPilot-1.4.0-x64.exe — NSIS Installer (recommended)
• PortPilot-1.4.0-portable.exe — Portable Version (no installation required)

📚 Full Changelog

See CHANGELOG.md for complete details.

---

Built for developers who juggle multiple localhost apps

PortPilot v1.3.0 - Features, UI/UX Improvements, and Testing

PortPilot v1.3.0

Major feature release with new capabilities, comprehensive UI/UX improvements, and 100% test coverage.

🎉 New Features

DevTools Setting

• Toggle DevTools opening on startup (dev mode only)
• Checkbox in Settings tab for easy configuration

Process Cleanup

• Automatic cleanup after failed app starts
• No more ghost "already running" errors
• Reliable process lifecycle management

Port Conflict Detection

• Pre-flight checks before starting apps
• Resolution dialog for port conflicts
• Smart port availability checking

Smart Startup Delay

• Visual countdown when apps are starting
• Real-time port polling
• Better feedback during app launch

App Management

• Refresh button for manual status updates
• Add/delete app configurations via UI
• Improved app lifecycle controls

🎨 UI/UX Improvements

Port Cards

• 20% larger port numbers (1.5rem) - easier to scan at a glance
• Increased padding (12px→16px) - better breathing room
• 2x more readable labels - text-secondary with 75% opacity
• Ellipsis truncation for long command paths - cleaner display

My Apps Tab

• STOPPED badges now clearly visible - improved contrast
• App metadata more readable - better opacity and color
• App count badge more prominent - white text, larger size

Typography

• Better font weight hierarchy throughout
• Consistent opacity levels (75-85%)
• Improved visual scanning and readability

🧪 Testing

• 100% test coverage (20/20 tests passing)
• Comprehensive E2E test suite with Playwright
• Screenshot automation for UI validation
• Test server infrastructure for reliable testing

📦 Download

Recommended: NSIS Installer (creates desktop shortcut, start menu entry)

• PortPilot-1.3.0-x64.exe (72 MB)

Portable: No installation required

• PortPilot-1.3.0-portable.exe (72 MB)

📝 Full Changelog

See CHANGELOG.md for complete version history.

🔄 Upgrade Notes

No breaking changes. Existing v1.2.0 configurations will be automatically migrated.

---

What's Changed Since v1.2.0:

• 7 new features added
• 7 UI/UX improvements implemented
• 13 new files created (tests, docs, screenshots)
• 8 core files enhanced
• 20 E2E tests (100% passing)

Contributors:

• @m4cd4r4 (Macdara)
• Claude Sonnet 4.5 (AI pair programming)

PortPilot v1.2.0 - Critical Fixes

Critical Fixes in v1.2.0

This release fixes major issues with port matching and external process management.

🐛 Bug Fixes

Port Matching Accuracy

• Fixed false positives where apps were incorrectly matched to ports
• Example: Neural-Sync no longer shows as "running" when other apps use port 3000
• PreferredPort matching now requires evidence (app name in command OR node/python/java process)
• Changed confidence level from "medium" to "low" for preferredPort fallback matches

Kill External Processes

• Fixed "App not found or not running" error when stopping apps
• Stop button now works for apps started outside PortPilot
• Smart fallback: tries normal stop first, then kills by port if needed
• Shows confirmation before killing external processes

✨ New Features

Refresh Button

• Added refresh button to My Apps tab toolbar
• Shows live count: "8 apps • 3 running"
• Manually re-scan which apps are actually running
• Visual feedback during refresh operation

🔧 Technical Details

Files Changed:

• src/main/ipcHandlers.js - Stricter port matching logic
• src/renderer/renderer.js - Kill-by-port fallback
• src/renderer/index.html - Refresh button UI

---

Downloads

Windows Installer: PortPilot-1.2.0-x64.exe (72 MB)

• Recommended for most users
• Creates desktop shortcut
• Adds to Start Menu

Portable Version: PortPilot-1.2.0-portable.exe (72 MB)

• No installation required
• Run from USB drive
• Perfect for testing

Installation

1. Download either installer above
2. Run the executable
3. For NSIS installer: Follow the installation wizard
4. For portable: Just run the .exe file

Requirements

• Windows 10 or later
• 100MB disk space

---

What's Changed Since v1.1.0

• Improved port matching prevents false positives
• External processes can now be stopped via PortPilot
• Added refresh functionality to My Apps tab

Full Changelog: v1.1.0...v1.2.0

PortPilot v1.1.0

What's New in v1.1.0

📚 Documentation

• NEW: Comprehensive user guide with screenshots
• NEW: HTML version of user guide for offline viewing
• Added guide screenshots for all major features

✨ Features & Improvements

• Port Matching: Added preferredPort fallback when CWD matching fails
• UI Enhancement: Apps list now uses responsive grid layout
• Production Ready: DevTools only opens in development mode
• Project Organization: Moved utility scripts to scripts/ folder

🧪 Testing

• Test Suite: All 11 tests passing (100% success rate)
• Fixed: Port kill functionality test now reliable
• Validated: Port scanning, filtering, killing all confirmed working

🐛 Bug Fixes

• Fixed test suite dialog handling
• Removed duplicate DevTools call on tray click
• Improved port detection accuracy

---

Downloads

Windows Installer: PortPilot-1.1.0-x64.exe (72 MB)

• Recommended for most users
• Creates desktop shortcut
• Adds to Start Menu

Portable Version: PortPilot-1.1.0-portable.exe (72 MB)

• No installation required
• Run from USB drive
• Perfect for testing

Installation

1. Download either installer above
2. Run the executable
3. For NSIS installer: Follow the installation wizard
4. For portable: Just run the .exe file

Requirements

• Windows 10 or later
• 100MB disk space

---

Full Changelog: v1.0.0...v1.1.0

PortPilot v1.0.0 - Initial Release

PortPilot v1.0.0 🚀

Localhost Port Manager — A desktop app for developers to manage local development ports and applications.

Download

• Windows Installer (NSIS): PortPilot-1.0.0-x64.exe (72 MB)
• Portable Version: PortPilot-1.0.0-portable.exe (72 MB) - No installation required

Features

✅ Port Scanner — Discover all active TCP ports with process details (name, PID, command line)
✅ One-Click Kill — Free up stuck ports instantly
✅ App Registry — Register your dev projects with start commands and preferred ports
✅ Process Management — Start/stop apps directly from PortPilot
✅ Auto-Detection — Automatically detects running apps by matching ports to registered projects
✅ Docker Integration — Click to start Docker Desktop, with status detection
✅ IPv4/IPv6 Awareness — Shows which protocol your app is bound to
✅ System Tray — Minimize to tray, quick access menu
✅ Multi-Theme Support — 6 themes including TokyoNight, Brutalist, Nord, Dracula
✅ Knowledge Base — Built-in help with tips, shortcuts, and common ports reference

Recent Fixes

• Port Kill Fix — Now correctly uses `cmd.exe` shell on Windows (fixed Git Bash compatibility issue)
• ELECTRON_RUN_AS_NODE — Automatically cleared via `launch.js` wrapper for VS Code/Claude Code users
• Cross-Platform — Works in CMD, PowerShell, Git Bash, and VS Code terminal

Tech Stack

• Electron 27 — Cross-platform desktop framework
• Node.js — Process management and port scanning
• Playwright — End-to-end testing (10/11 tests passing)
• Vanilla JS — No framework bloat
• CSS Variables — Theme system

Installation

Download either executable above and run. The portable version requires no installation.

See the README for full documentation.