Perch

Overview

Modern local development is chaos by default. A typical session has a frontend running on one port, an API on another, a database, a Redis instance, maybe a Docker container you forgot you started, and half a dozen terminal tabs — each showing a different slice of what's actually happening on the machine. There's no single place to see which process owns which port, why a service silently died, or where things are bottlenecking.

Perch was built to fix exactly that. It runs a persistent background daemon that continuously scans the local machine and aggregates everything — running processes, open ports, HTTP traffic, resource usage, crash events — into one premium developer dashboard. The closest analogy is what tools like Vercel or Railway give you for deployed infrastructure, except Perch brings that same visibility to localhost.

System Architecture

Perch is built as a split-architecture system, cleanly separating the UI layer from the system-level introspection layer:

• Perch Daemon (Node.js) — a headless background process listening on port 7777, responsible for process monitoring, port scanning, an http-proxy server for traffic interception, an env file watcher, and config validation. This is the part that actually talks to the OS.
• Perch Desktop App (Electron) — the tray-resident client that serves the dashboard UI (nav rail, process list, dependency graph, HTTP inspector, config editor, resource badges) and communicates with the daemon over IPC/WebSocket.

Keeping these separate means the daemon can keep running and collecting data in the background even when the dashboard window itself is closed — the UI is just a lens onto whatever state the daemon is already tracking.

Core Features

• HTTP Request Inspector — dynamic proxying to intercept and debug localhost traffic in real time, with per-request method, route, status code, header tables, and latency, toggleable on/off per port from the UI
• Process Dependency Graph — auto-discovered service topology rendered as an interactive node-link graph, with live status indicators (healthy / warning / offline) and visual traffic direction between services
• System Tray Mode — native Electron tray integration; closing the dashboard window minimizes to tray instead of killing the daemon, with a quick-access menu for status, start/stop, and quit
• Process Crash Alerts — real-time toast notifications the instant a monitored service crashes, with exit codes, signals, and debug logs surfaced immediately instead of buried in a terminal scrollback
• Port Reservation & Violation Detection — declare expected port-to-service mappings in config; if another process hijacks a reserved port, Perch flags the violation instantly and offers a one-click swap to resolve it
• Interactive Config Editor — edit perch.config.json directly from the dashboard with live JSON schema validation, so malformed config never silently breaks the daemon
• CPU & Memory Sparklines — resource-dense process tables with inline micro-sparklines tracking CPU and memory trends over time per process
• Uptime Tracking — millisecond-granular uptime badges per process, so you know exactly how long something has actually been alive
• Forceful Kill & Restart — kills processes that ignore SIGTERM on Windows using taskkill /F /T with full child-process-tree termination, then restarts using the original spawn command and re-attaches logs from the new instance — with polling to verify the process is actually dead before reporting success

CLI

Perch ships a globally-linked perch CLI so the daemon can be driven entirely outside the dashboard — useful for scripting or headless use:

perch start              # start the daemon
perch stop                # stop the daemon
perch status               # daemon status, uptime, active process count
perch ports                 # list listening ports with process/PID/memory
perch kill 3000              # kill by port or PID
perch restart 3000            # restart using original command
perch logs 3000 --lines 100    # tail recent logs for a process
perch health                    # health check across all services

Running perch with no arguments shows live daemon status inline alongside the full command reference.

Windows Support

Perch is built with Windows as a first-class target, not an afterthought — all shell processes spawn invisibly (windowsHide: true), so the daemon runs cleanly in the background without triggering intrusive cmd window flashes, and tray integration handles window visibility and process cleanup natively.

Configuration

Workspaces are defined via a perch.config.json file — daemon port, poll interval, reserved ports, and grouped services each with their own start command, working directory, expected port, and auto-restart behavior — giving Perch enough context to know what should be running and flag anything that deviates from it.

Tech Stack

Electron · React + Zustand · Node.js + Express + WebSocket · http-proxy · ps-list / pidusage / ps-tree / node-netstat / chokidar · chalk / cli-table3