SocketGrid

A terminal UI for Windows socket discovery and process management. SocketGrid lists active TCP and UDP sockets, groups them by category, and lets you terminate processes from a single keyboard-driven interface.

Windows only. V1 targets 64-bit Windows with standard or elevated permissions.

Build and Run

Requires Go 1.24+.

make build    # build the executable
make test     # run the test suite

Or build directly:

go build ./cmd/socketgrid

Run the resulting executable:

./socketgrid

For full PID resolution and the ability to terminate protected processes, run from an elevated (Administrator) terminal.

CLI Flags

socketgrid [flags]

Flags:
  --ascii         Use ASCII-safe rendering for legacy terminals
  --refresh dur   Refresh interval (default 2s, min 500ms, max 60s)
  --density-cap n Socket count benchmark for density percentage (default 100, min 1, max 10000)

Examples:

socketgrid                          # default mode, 2s refresh
socketgrid --ascii                  # ASCII-safe for legacy terminals
socketgrid --refresh 5s             # refresh every 5 seconds
socketgrid --density-cap 200        # density relative to 200 sockets
socketgrid --ascii --refresh 3s     # combine flags

Invalid flags print an error and exit. The application always runs with safe defaults if no flags are given.

Keyboard Controls

| Key | Action | |:----|:-------| | Tab / Shift+Tab | Switch the focused group pane | | up / k | Move selection up within the focused pane | | down / j | Move selection down within the focused pane | | r | Force a snapshot refresh | | x / Delete | Open kill-confirmation modal for the selected process | | y | Confirm kill (inside modal) | | n / Esc | Cancel kill (inside modal) | | q / Ctrl+C | Quit |

Kill Confirmation Safety

Selecting a process entry and pressing x (or Delete) opens a confirmation modal showing the PID and executable name. The process is not terminated until you press y. Press n or Esc to cancel.

While a kill is in progress, further keypresses are ignored to prevent double-invocation. After the kill completes, SocketGrid refreshes its snapshot automatically and reports whether the termination succeeded or failed.

Running without elevation restricts the ability to terminate system processes. SocketGrid displays the error reason if a kill fails.

Display

SocketGrid organizes sockets into four groups, each showing one process entry per owning PID rather than one row per socket:

• Development stack — runtimes, databases, build tools (node.exe, python.exe, postgres)
• User apps and browsers — browsers, chat clients, consumer apps
• Windows services — system infrastructure (svchost.exe, lsass.exe)
• User & background apps — remaining sockets whose owning process is unrecognized or whose executable could not be resolved

Each process entry shows the executable name (or a port-based service hint for nameless entries), PID, total active socket count, and a status breakdown (listening/established/UDP). Entries are sorted by descending socket count within each group.

Transient TCP states (TIME_WAIT, CLOSE_WAIT, SYN_SENT, etc.) are filtered out of the panes and reported as a count in the footer. The density meter in the header reflects active sockets only.

Each group occupies an equal-height pane on screen. Use Tab / Shift+Tab to move focus between panes; up/down scroll and select within the focused pane. When a pane has more entries than fit, ↑ N more / ↓ N more indicators show how many entries are hidden above and below.

In Unicode mode (default), borders use box-drawing characters and status indicators use geometric glyphs. The --ascii flag switches to plain ASCII borders and text-based indicators for terminals that lack Unicode support.

Windows Permissions

SocketGrid works at both standard and elevated privilege levels:

• Standard user — Can view and navigate all sockets. Can terminate processes owned by the current user. Cannot terminate system or admin processes.
• Elevated (Administrator) — Can view and terminate any process, including protected system processes.

The header badge shows the current elevation status.

Verification

See docs/manual-verification.md for the pre-release verification checklist.

License

MIT