aur: install README.md to /usr/share/doc/snitch

- Switch to nixos-25.11 for modern apple-sdk packages
- Use apple-sdk_15 which includes SecTrustCopyCertificateChain (macOS 12+)
- Required for Go 1.25 crypto/x509 compatibility on darwin

.github/workflows/ci.yaml

@@ -32,7 +32,28 @@ jobs:
           go-version: "1.25.0"
 
       - name: lint
-        uses: golangci/golangci-lint-action@v6
+        uses: golangci/golangci-lint-action@v8
         with:
-          version: latest
+          version: v2.5.0
+
+  nix-build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-14]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: DeterminateSystems/nix-installer-action@v17
+
+      - uses: nix-community/cache-nix-action@v6
+        with:
+          primary-key: nix-${{ runner.os }}-${{ hashFiles('flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-
+
+      - name: nix flake check
+        run: nix flake check
+
+      - name: nix build
+        run: nix build
 

.github/workflows/release.yaml

@@ -9,7 +9,7 @@ permissions:
   contents: write
 
 jobs:
-  goreleaser:
+  release-linux:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -20,11 +20,31 @@ jobs:
         with:
           go-version: "1.25.0"
 
-      - name: run goreleaser
+      - name: release linux
         uses: goreleaser/goreleaser-action@v6
         with:
           version: "~> v2"
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AUR_KEY: ${{ secrets.AUR_KEY }}
 
+  release-darwin:
+    needs: release-linux
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.25.0"
+
+      - name: release darwin
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          version: "~> v2"
+          args: release --clean --config .goreleaser-darwin.yaml --skip=validate
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -27,6 +27,9 @@ Thumbs.db
 # go
 vendor/
 
+# nix
+result
+
 # misc
 *.log
 *.tmp

.goreleaser-darwin.yaml

@@ -0,0 +1,39 @@
+version: 2
+
+project_name: snitch
+
+builds:
+  - id: darwin
+    env:
+      - CGO_ENABLED=1
+    goos:
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+    ldflags:
+      - -s -w
+      - -X snitch/cmd.Version={{.Version}}
+      - -X snitch/cmd.Commit={{.ShortCommit}}
+      - -X snitch/cmd.Date={{.Date}}
+
+archives:
+  - formats:
+      - tar.gz
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- .Version }}_
+      {{- .Os }}_
+      {{- .Arch }}
+    files:
+      - LICENSE
+      - README.md
+
+release:
+  github:
+    owner: karol-broda
+    name: snitch
+  draft: false
+  prerelease: auto
+  mode: append
+

.goreleaser.yaml

@@ -7,7 +7,8 @@ before:
     - go mod tidy
 
 builds:
-  - env:
+  - id: linux
+    env:
       - CGO_ENABLED=0
     goos:
       - linux
@@ -32,6 +33,9 @@ archives:
       {{- .Os }}_
       {{- .Arch }}
       {{- if .Arm }}v{{ .Arm }}{{ end }}
+    files:
+      - LICENSE
+      - README.md
 
 checksum:
   name_template: "checksums.txt"
@@ -60,10 +64,31 @@ nfpms:
       - rpm
       - apk
 
+aurs:
+  - name: snitch-bin
+    homepage: https://github.com/karol-broda/snitch
+    description: a friendlier ss/netstat for humans
+    maintainers:
+      - "Karol Broda <me@karolbroda.com>"
+    license: MIT
+    private_key: "{{ .Env.AUR_KEY }}"
+    git_url: "ssh://aur@aur.archlinux.org/snitch-bin.git"
+    depends:
+      - glibc
+    provides:
+      - snitch
+    conflicts:
+      - snitch
+    package: |-
+      install -Dm755 "./snitch" "${pkgdir}/usr/bin/snitch"
+      install -Dm644 "./LICENSE" "${pkgdir}/usr/share/licenses/snitch/LICENSE"
+      install -Dm644 "./README.md" "${pkgdir}/usr/share/doc/snitch/README.md"
+    commit_msg_template: "Update to {{ .Tag }}"
+    skip_upload: auto
+
 release:
   github:
     owner: karol-broda
     name: snitch
   draft: false
   prerelease: auto
-

Makefile

@@ -0,0 +1,23 @@
+.PHONY: build test lint demo demo-build demo-run clean
+
+build:
+	go build -o snitch .
+
+test:
+	go test ./...
+
+lint:
+	golangci-lint run
+
+demo: demo-build demo-run
+
+demo-build:
+	docker build -f demo/Dockerfile -t snitch-demo .
+
+demo-run:
+	docker run --rm -v $(PWD)/demo:/output snitch-demo
+
+clean:
+	rm -f snitch
+	rm -f demo/demo.gif
+

README.md

@@ -2,12 +2,129 @@
 
 a friendlier `ss` / `netstat` for humans. inspect network connections with a clean tui or styled tables.
 
+![snitch demo](demo/demo.gif)
+
 ## install
 
+### homebrew
+
+```bash
+brew install snitch
+```
+
+> thanks to [@bevanjkay](https://github.com/bevanjkay) for adding snitch to homebrew-core
+
+### go
+
 ```bash
 go install github.com/karol-broda/snitch@latest
 ```
 
+### nixpkgs
+
+```bash
+nix-env -iA nixpkgs.snitch
+```
+
+> thanks to [@DieracDelta](https://github.com/DieracDelta) for adding snitch to nixpkgs
+
+### nixos / nix (flake)
+
+```bash
+# try it
+nix run github:karol-broda/snitch
+
+# install to profile
+nix profile install github:karol-broda/snitch
+
+# or add to flake inputs
+{
+  inputs.snitch.url = "github:karol-broda/snitch";
+}
+# then use: inputs.snitch.packages.${system}.default
+```
+
+### home-manager (flake)
+
+add snitch to your flake inputs and import the home-manager module:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    home-manager.url = "github:nix-community/home-manager";
+    snitch.url = "github:karol-broda/snitch";
+  };
+
+  outputs = { nixpkgs, home-manager, snitch, ... }: {
+    homeConfigurations."user" = home-manager.lib.homeManagerConfiguration {
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      modules = [
+        snitch.homeManagerModules.default
+        {
+          programs.snitch = {
+            enable = true;
+            # optional: use the flake's package instead of nixpkgs
+            # package = snitch.packages.x86_64-linux.default;
+            settings = {
+              defaults = {
+                theme = "catppuccin-mocha";
+                interval = "2s";
+                resolve = true;
+              };
+            };
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+available themes: `ansi`, `catppuccin-mocha`, `catppuccin-macchiato`, `catppuccin-frappe`, `catppuccin-latte`, `gruvbox-dark`, `gruvbox-light`, `dracula`, `nord`, `tokyo-night`, `tokyo-night-storm`, `tokyo-night-light`, `solarized-dark`, `solarized-light`, `one-dark`, `mono`
+
+### arch linux (aur)
+
+```bash
+# with yay
+yay -S snitch-bin
+
+# with paru
+paru -S snitch-bin
+```
+
+### shell script
+
+```bash
+curl -sSL https://raw.githubusercontent.com/karol-broda/snitch/master/install.sh | sh
+```
+
+installs to `~/.local/bin` if available, otherwise `/usr/local/bin`. override with:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/karol-broda/snitch/master/install.sh | INSTALL_DIR=~/bin sh
+```
+
+> **macos:** the install script automatically removes the quarantine attribute (`com.apple.quarantine`) from the binary to allow it to run without gatekeeper warnings. to disable this, set `KEEP_QUARANTINE=1`.
+
+### binary
+
+download from [releases](https://github.com/karol-broda/snitch/releases):
+
+- **linux:** `snitch_<version>_linux_<arch>.tar.gz` or `.deb`/`.rpm`/`.apk`
+- **macos:** `snitch_<version>_darwin_<arch>.tar.gz`
+
+```bash
+tar xzf snitch_*.tar.gz
+sudo mv snitch /usr/local/bin/
+```
+
+> **macos:** if blocked with "cannot be opened because the developer cannot be verified", run:
+>
+> ```bash
+> xattr -d com.apple.quarantine /usr/local/bin/snitch
+> ```
+
 ## quick start
 
 ```bash
@@ -41,6 +158,9 @@ g/G           top/bottom
 t/u           toggle tcp/udp
 l/e/o         toggle listen/established/other
 s/S           cycle sort / reverse
+w             watch/monitor process (highlight)
+W             clear all watched
+K             kill process (with confirmation)
 /             search
 enter         connection details
 ?             help
@@ -81,6 +201,16 @@ snitch watch -i 1s | jq '.count'
 snitch watch -l -i 500ms
 ```
 
+### `snitch upgrade`
+
+check for updates and upgrade in-place.
+
+```bash
+snitch upgrade              # check for updates
+snitch upgrade --yes        # upgrade automatically
+snitch upgrade -v 0.1.7     # install specific version
+```
+
 ## filters
 
 shortcut flags work on all commands:
@@ -92,9 +222,20 @@ shortcut flags work on all commands:
 -e, --established   established connections
 -4, --ipv4          ipv4 only
 -6, --ipv6          ipv6 only
--n, --numeric       no dns resolution
 ```
 
+## resolution
+
+dns and service name resolution options:
+
+```
+--resolve-addrs     resolve ip addresses to hostnames (default: true)
+--resolve-ports     resolve port numbers to service names
+--no-cache          disable dns caching (force fresh lookups)
+```
+
+dns lookups are performed in parallel and cached for performance. use `--no-cache` to bypass the cache for debugging or when addresses change frequently.
+
 for more specific filtering, use `key=value` syntax with `ls`:
 
 ```bash
@@ -133,11 +274,38 @@ optional config file at `~/.config/snitch/snitch.toml`:
 
 ```toml
 [defaults]
-numeric = false
-theme = "auto"
+numeric = false      # disable name resolution
+dns_cache = true     # cache dns lookups (set to false to disable)
+theme = "auto"       # color theme: auto, dark, light, mono
+
+[tui]
+remember_state = false   # remember view options between sessions
+```
+
+### remembering view options
+
+when `remember_state = true`, the tui will save and restore:
+
+- filter toggles (tcp/udp, listen/established/other)
+- sort field and direction
+- address and port resolution settings
+
+state is saved to `$XDG_STATE_HOME/snitch/tui.json` (defaults to `~/.local/state/snitch/tui.json`).
+
+cli flags always take priority over saved state.
+
+### environment variables
+
+```bash
+SNITCH_THEME=dark          # set default theme
+SNITCH_RESOLVE=0           # disable dns resolution
+SNITCH_DNS_CACHE=0         # disable dns caching
+SNITCH_NO_COLOR=1          # disable color output
+SNITCH_CONFIG=/path/to     # custom config file path
 ```
 
 ## requirements
 
-- linux (reads from `/proc/net/*`)
-- root or `CAP_NET_ADMIN` for full process info
+- linux or macos
+- linux: reads from `/proc/net/*`, root or `CAP_NET_ADMIN` for full process info
+- macos: uses system APIs, may require sudo for full process info

cmd/cli_test.go

@@ -6,7 +6,8 @@ import (
 	"strings"
 	"testing"
 
-	"snitch/internal/testutil"
+	"github.com/karol-broda/snitch/internal/errutil"
+	"github.com/karol-broda/snitch/internal/testutil"
 )
 
 // TestCLIContract tests the CLI interface contracts as specified in the README
@@ -71,7 +72,7 @@ func TestCLIContract(t *testing.T) {
 			name:           "version",
 			args:           []string{"version"},
 			expectExitCode: 0,
-			expectStdout:   []string{"snitch", "commit:", "built:"},
+			expectStdout:   []string{"snitch", "commit", "built"},
 			expectStderr:   nil,
 			description:    "version command should show version information",
 		},
@@ -361,10 +362,11 @@ func resetGlobalFlags() {
 	showTimestamp = false
 	sortBy = ""
 	fields = ""
-	ipv4 = false
-	ipv6 = false
+	filterIPv4 = false
+	filterIPv6 = false
 	colorMode = "auto"
-	numeric = false
+	resolveAddrs = true
+	resolvePorts = false
 }
 
 // TestEnvironmentVariables tests that environment variables are properly handled
@@ -406,16 +408,16 @@ func TestEnvironmentVariables(t *testing.T) {
 		oldEnvVars := make(map[string]string)
 		for key, value := range tt.envVars {
 			oldEnvVars[key] = os.Getenv(key)
-			os.Setenv(key, value)
+			errutil.Setenv(key, value)
 		}
 
 		// Clean up environment variables
 		defer func() {
 			for key, oldValue := range oldEnvVars {
 				if oldValue == "" {
-					os.Unsetenv(key)
+					errutil.Unsetenv(key)
 				} else {
-					os.Setenv(key, oldValue)
+					errutil.Setenv(key, oldValue)
 				}
 			}
 		}()

cmd/golden_test.go

@@ -9,8 +9,8 @@ import (
 	"strings"
 	"testing"
 
-	"snitch/internal/collector"
-	"snitch/internal/testutil"
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/testutil"
 )
 
 var updateGolden = flag.Bool("update-golden", false, "Update golden files")

cmd/json.go

@@ -15,4 +15,5 @@ var jsonCmd = &cobra.Command{
 
 func init() {
 	rootCmd.AddCommand(jsonCmd)
+	addFilterFlags(jsonCmd)
 }

cmd/ls.go

@@ -8,34 +8,30 @@ import (
 	"log"
 	"os"
 	"os/exec"
-	"snitch/internal/collector"
-	"snitch/internal/color"
-	"snitch/internal/config"
-	"snitch/internal/resolver"
 	"strconv"
 	"strings"
 	"text/tabwriter"
 
 	"github.com/charmbracelet/lipgloss"
 	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/color"
+	"github.com/karol-broda/snitch/internal/config"
+	"github.com/karol-broda/snitch/internal/errutil"
+	"github.com/karol-broda/snitch/internal/resolver"
 	"github.com/tidwall/pretty"
 	"golang.org/x/term"
 )
 
+// ls-specific flags
 var (
 	outputFormat  string
 	noHeaders     bool
 	showTimestamp bool
 	sortBy        string
 	fields        string
-	ipv4          bool
-	ipv6          bool
 	colorMode     string
-	numeric       bool
-	lsTCP         bool
-	lsUDP         bool
-	lsListen      bool
-	lsEstab       bool
 	plainOutput   bool
 )
 
@@ -56,39 +52,16 @@ Available filters:
 }
 
 func runListCommand(outputFormat string, args []string) {
-	color.Init(colorMode)
-
-	filters, err := parseFilters(args)
-	if err != nil {
-		log.Fatalf("Error parsing filters: %v", err)
-	}
-	filters.IPv4 = ipv4
-	filters.IPv6 = ipv6
-
-	// apply shortcut flags
-	if lsTCP && !lsUDP {
-		filters.Proto = "tcp"
-	} else if lsUDP && !lsTCP {
-		filters.Proto = "udp"
-	}
-	if lsListen && !lsEstab {
-		filters.State = "LISTEN"
-	} else if lsEstab && !lsListen {
-		filters.State = "ESTABLISHED"
-	}
-
-	connections, err := collector.GetConnections()
+	rt, err := NewRuntime(args, colorMode)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	filteredConnections := collector.FilterConnections(connections, filters)
-
+	// apply sorting
 	if sortBy != "" {
-		collector.SortConnections(filteredConnections, collector.ParseSortOptions(sortBy))
+		rt.SortConnections(collector.ParseSortOptions(sortBy))
 	} else {
-		// default sort by local port
-		collector.SortConnections(filteredConnections, collector.SortOptions{
+		rt.SortConnections(collector.SortOptions{
 			Field:     collector.SortByLport,
 			Direction: collector.SortAsc,
 		})
@@ -99,93 +72,26 @@ func runListCommand(outputFormat string, args []string) {
 		selectedFields = strings.Split(fields, ",")
 	}
 
-	switch outputFormat {
+	renderList(rt.Connections, outputFormat, selectedFields)
+}
+
+func renderList(connections []collector.Connection, format string, selectedFields []string) {
+	switch format {
 	case "json":
-		printJSON(filteredConnections)
+		printJSON(connections)
 	case "csv":
-		printCSV(filteredConnections, !noHeaders, showTimestamp, selectedFields)
+		printCSV(connections, !noHeaders, showTimestamp, selectedFields)
 	case "table", "wide":
 		if plainOutput {
-			printPlainTable(filteredConnections, !noHeaders, showTimestamp, selectedFields)
+			printPlainTable(connections, !noHeaders, showTimestamp, selectedFields)
 		} else {
-			printStyledTable(filteredConnections, !noHeaders, selectedFields)
+			printStyledTable(connections, !noHeaders, selectedFields)
 		}
 	default:
-		log.Fatalf("Invalid output format: %s. Valid formats are: table, wide, json, csv", outputFormat)
+		log.Fatalf("Invalid output format: %s. Valid formats are: table, wide, json, csv", format)
 	}
 }
 
-func parseFilters(args []string) (collector.FilterOptions, error) {
-	filters := collector.FilterOptions{}
-	for _, arg := range args {
-		parts := strings.SplitN(arg, "=", 2)
-		if len(parts) != 2 {
-			return filters, fmt.Errorf("invalid filter format: %s", arg)
-		}
-		key, value := parts[0], parts[1]
-		switch strings.ToLower(key) {
-		case "proto":
-			filters.Proto = value
-		case "state":
-			filters.State = value
-		case "pid":
-			pid, err := strconv.Atoi(value)
-			if err != nil {
-				return filters, fmt.Errorf("invalid pid value: %s", value)
-			}
-			filters.Pid = pid
-		case "proc":
-			filters.Proc = value
-		case "lport":
-			port, err := strconv.Atoi(value)
-			if err != nil {
-				return filters, fmt.Errorf("invalid lport value: %s", value)
-			}
-			filters.Lport = port
-		case "rport":
-			port, err := strconv.Atoi(value)
-			if err != nil {
-				return filters, fmt.Errorf("invalid rport value: %s", value)
-			}
-			filters.Rport = port
-		case "user":
-			uid, err := strconv.Atoi(value)
-			if err == nil {
-				filters.UID = uid
-			} else {
-				filters.User = value
-			}
-		case "laddr":
-			filters.Laddr = value
-		case "raddr":
-			filters.Raddr = value
-		case "contains":
-			filters.Contains = value
-		case "if", "interface":
-			filters.Interface = value
-		case "mark":
-			filters.Mark = value
-		case "namespace":
-			filters.Namespace = value
-		case "inode":
-			inode, err := strconv.ParseInt(value, 10, 64)
-			if err != nil {
-				return filters, fmt.Errorf("invalid inode value: %s", value)
-			}
-			filters.Inode = inode
-		case "since":
-			since, sinceRel, err := collector.ParseTimeFilter(value)
-			if err != nil {
-				return filters, fmt.Errorf("invalid since value: %s", value)
-			}
-			filters.Since = since
-			filters.SinceRel = sinceRel
-		default:
-			return filters, fmt.Errorf("unknown filter key: %s", key)
-		}
-	}
-	return filters, nil
-}
 
 func getFieldMap(c collector.Connection) map[string]string {
 	laddr := c.Laddr
@@ -193,14 +99,18 @@ func getFieldMap(c collector.Connection) map[string]string {
 	lport := strconv.Itoa(c.Lport)
 	rport := strconv.Itoa(c.Rport)
 	
-	// Apply name resolution if not in numeric mode
-	if !numeric {
+	// apply address resolution
+	if resolveAddrs {
 		if resolvedLaddr := resolver.ResolveAddr(c.Laddr); resolvedLaddr != c.Laddr {
 			laddr = resolvedLaddr
 		}
 		if resolvedRaddr := resolver.ResolveAddr(c.Raddr); resolvedRaddr != c.Raddr && c.Raddr != "*" && c.Raddr != "" {
 			raddr = resolvedRaddr
 		}
+	}
+
+	// apply port resolution
+	if resolvePorts {
 		if resolvedLport := resolver.ResolvePort(c.Lport, c.Proto); resolvedLport != strconv.Itoa(c.Lport) {
 			lport = resolvedLport
 		}
@@ -277,7 +187,7 @@ func printCSV(conns []collector.Connection, headers bool, timestamp bool, select
 
 func printPlainTable(conns []collector.Connection, headers bool, timestamp bool, selectedFields []string) {
 	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0)
-	defer w.Flush()
+	defer errutil.Flush(w)
 
 	if len(selectedFields) == 0 {
 		selectedFields = []string{"pid", "process", "user", "proto", "state", "laddr", "lport", "raddr", "rport"}
@@ -291,7 +201,7 @@ func printPlainTable(conns []collector.Connection, headers bool, timestamp bool,
 		for _, field := range selectedFields {
 			headerRow = append(headerRow, strings.ToUpper(field))
 		}
-		fmt.Fprintln(w, strings.Join(headerRow, "\t"))
+		errutil.Ignore(fmt.Fprintln(w, strings.Join(headerRow, "\t")))
 	}
 
 	for _, conn := range conns {
@@ -300,7 +210,7 @@ func printPlainTable(conns []collector.Connection, headers bool, timestamp bool,
 		for _, field := range selectedFields {
 			row = append(row, fieldMap[field])
 		}
-		fmt.Fprintln(w, strings.Join(row, "\t"))
+		errutil.Ignore(fmt.Fprintln(w, strings.Join(row, "\t")))
 	}
 }
 
@@ -483,20 +393,16 @@ func init() {
 
 	cfg := config.Get()
 
+	// ls-specific flags
 	lsCmd.Flags().StringVarP(&outputFormat, "output", "o", cfg.Defaults.OutputFormat, "Output format (table, wide, json, csv)")
 	lsCmd.Flags().BoolVar(&noHeaders, "no-headers", cfg.Defaults.NoHeaders, "Omit headers for table/csv output")
 	lsCmd.Flags().BoolVar(&showTimestamp, "ts", false, "Include timestamp in output")
 	lsCmd.Flags().StringVarP(&sortBy, "sort", "s", cfg.Defaults.SortBy, "Sort by column (e.g., pid:desc)")
 	lsCmd.Flags().StringVarP(&fields, "fields", "f", strings.Join(cfg.Defaults.Fields, ","), "Comma-separated list of fields to show")
-	lsCmd.Flags().BoolVarP(&ipv4, "ipv4", "4", cfg.Defaults.IPv4, "Only show IPv4 connections")
-	lsCmd.Flags().BoolVarP(&ipv6, "ipv6", "6", cfg.Defaults.IPv6, "Only show IPv6 connections")
 	lsCmd.Flags().StringVar(&colorMode, "color", cfg.Defaults.Color, "Color mode (auto, always, never)")
-	lsCmd.Flags().BoolVarP(&numeric, "numeric", "n", cfg.Defaults.Numeric, "Don't resolve hostnames")
-
-	// shortcut filters
-	lsCmd.Flags().BoolVarP(&lsTCP, "tcp", "t", false, "Show only TCP connections")
-	lsCmd.Flags().BoolVarP(&lsUDP, "udp", "u", false, "Show only UDP connections")
-	lsCmd.Flags().BoolVarP(&lsListen, "listen", "l", false, "Show only listening sockets")
-	lsCmd.Flags().BoolVarP(&lsEstab, "established", "e", false, "Show only established connections")
 	lsCmd.Flags().BoolVarP(&plainOutput, "plain", "p", false, "Plain output (parsable, no styling)")
+
+	// shared flags
+	addFilterFlags(lsCmd)
+	addResolutionFlags(lsCmd)
 }

cmd/ls_test.go

@@ -4,8 +4,8 @@ import (
 	"strings"
 	"testing"
 
-	"snitch/internal/collector"
-	"snitch/internal/testutil"
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/testutil"
 )
 
 func TestLsCommand_EmptyResults(t *testing.T) {
@@ -251,7 +251,7 @@ func TestParseFilters(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			filters, err := parseFilters(tt.args)
+			filters, err := ParseFilterArgs(tt.args)
 
 			if tt.expectError {
 				if err == nil {

cmd/root.go

@@ -3,11 +3,12 @@ package cmd
 import (
 	"fmt"
 	"os"
-	"snitch/internal/config"
 
+	"github.com/karol-broda/snitch/internal/config"
 	"github.com/spf13/cobra"
 )
 
+
 var (
 	cfgFile string
 )
@@ -40,12 +41,12 @@ func init() {
 	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.config/snitch/snitch.toml)")
 	rootCmd.PersistentFlags().Bool("debug", false, "enable debug logs to stderr")
 
-	// add top's filter flags to root so `snitch -l` works
+	// add top's flags to root so `snitch -l` works (defaults to top command)
 	cfg := config.Get()
-	rootCmd.Flags().StringVar(&topTheme, "theme", cfg.Defaults.Theme, "Theme for TUI (dark, light, mono, auto)")
+	rootCmd.Flags().StringVar(&topTheme, "theme", cfg.Defaults.Theme, "Theme for TUI (see 'snitch themes')")
 	rootCmd.Flags().DurationVarP(&topInterval, "interval", "i", 0, "Refresh interval (default 1s)")
-	rootCmd.Flags().BoolVarP(&topTCP, "tcp", "t", false, "Show only TCP connections")
-	rootCmd.Flags().BoolVarP(&topUDP, "udp", "u", false, "Show only UDP connections")
-	rootCmd.Flags().BoolVarP(&topListen, "listen", "l", false, "Show only listening sockets")
-	rootCmd.Flags().BoolVarP(&topEstab, "established", "e", false, "Show only established connections")
+
+	// shared flags for root command
+	addFilterFlags(rootCmd)
+	addResolutionFlags(rootCmd)
 }

cmd/runtime.go

@@ -0,0 +1,244 @@
+package cmd
+
+import (
+	"fmt"
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/color"
+	"github.com/karol-broda/snitch/internal/config"
+	"github.com/karol-broda/snitch/internal/resolver"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// Runtime holds the shared state for all commands.
+// it handles common filter logic, fetching, filtering, and resolution.
+type Runtime struct {
+	// filter options built from flags and args
+	Filters collector.FilterOptions
+
+	// filtered connections ready for rendering
+	Connections []collector.Connection
+
+	// common settings
+	ColorMode    string
+	ResolveAddrs bool
+	ResolvePorts bool
+	NoCache      bool
+}
+
+// shared filter flags - used by all commands
+var (
+	filterTCP    bool
+	filterUDP    bool
+	filterListen bool
+	filterEstab  bool
+	filterIPv4   bool
+	filterIPv6   bool
+)
+
+// shared resolution flags - used by all commands
+var (
+	resolveAddrs bool
+	resolvePorts bool
+	noCache      bool
+)
+
+// BuildFilters constructs FilterOptions from command args and shortcut flags.
+func BuildFilters(args []string) (collector.FilterOptions, error) {
+	filters, err := ParseFilterArgs(args)
+	if err != nil {
+		return filters, err
+	}
+
+	// apply ipv4/ipv6 flags
+	filters.IPv4 = filterIPv4
+	filters.IPv6 = filterIPv6
+
+	// apply protocol shortcut flags
+	if filterTCP && !filterUDP {
+		filters.Proto = "tcp"
+	} else if filterUDP && !filterTCP {
+		filters.Proto = "udp"
+	}
+
+	// apply state shortcut flags
+	if filterListen && !filterEstab {
+		filters.State = "LISTEN"
+	} else if filterEstab && !filterListen {
+		filters.State = "ESTABLISHED"
+	}
+
+	return filters, nil
+}
+
+// FetchConnections gets connections from the collector and applies filters.
+func FetchConnections(filters collector.FilterOptions) ([]collector.Connection, error) {
+	connections, err := collector.GetConnections()
+	if err != nil {
+		return nil, err
+	}
+
+	return collector.FilterConnections(connections, filters), nil
+}
+
+// NewRuntime creates a runtime with fetched and filtered connections.
+func NewRuntime(args []string, colorMode string) (*Runtime, error) {
+	color.Init(colorMode)
+
+	cfg := config.Get()
+	
+	// configure resolver with cache setting (flag overrides config)
+	effectiveNoCache := noCache || !cfg.Defaults.DNSCache
+	resolver.SetNoCache(effectiveNoCache)
+
+	filters, err := BuildFilters(args)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse filters: %w", err)
+	}
+
+	connections, err := FetchConnections(filters)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch connections: %w", err)
+	}
+
+	rt := &Runtime{
+		Filters:      filters,
+		Connections:  connections,
+		ColorMode:    colorMode,
+		ResolveAddrs: resolveAddrs,
+		ResolvePorts: resolvePorts,
+		NoCache:      effectiveNoCache,
+	}
+
+	// pre-warm dns cache by resolving all addresses in parallel
+	if resolveAddrs {
+		rt.PreWarmDNS()
+	}
+
+	return rt, nil
+}
+
+// PreWarmDNS resolves all connection addresses in parallel to warm the cache.
+func (r *Runtime) PreWarmDNS() {
+	addrs := make([]string, 0, len(r.Connections)*2)
+	for _, c := range r.Connections {
+		addrs = append(addrs, c.Laddr, c.Raddr)
+	}
+	resolver.ResolveAddrsParallel(addrs)
+}
+
+// SortConnections sorts the runtime's connections in place.
+func (r *Runtime) SortConnections(opts collector.SortOptions) {
+	collector.SortConnections(r.Connections, opts)
+}
+
+// ParseFilterArgs parses key=value filter arguments.
+// exported for testing.
+func ParseFilterArgs(args []string) (collector.FilterOptions, error) {
+	filters := collector.FilterOptions{}
+	for _, arg := range args {
+		parts := strings.SplitN(arg, "=", 2)
+		if len(parts) != 2 {
+			return filters, fmt.Errorf("invalid filter format: %s (expected key=value)", arg)
+		}
+		key, value := parts[0], parts[1]
+		if err := applyFilter(&filters, key, value); err != nil {
+			return filters, err
+		}
+	}
+	return filters, nil
+}
+
+// applyFilter applies a single key=value filter to FilterOptions.
+func applyFilter(filters *collector.FilterOptions, key, value string) error {
+	switch strings.ToLower(key) {
+	case "proto":
+		filters.Proto = value
+	case "state":
+		filters.State = value
+	case "pid":
+		pid, err := strconv.Atoi(value)
+		if err != nil {
+			return fmt.Errorf("invalid pid value: %s", value)
+		}
+		filters.Pid = pid
+	case "proc":
+		filters.Proc = value
+	case "lport":
+		port, err := strconv.Atoi(value)
+		if err != nil {
+			return fmt.Errorf("invalid lport value: %s", value)
+		}
+		filters.Lport = port
+	case "rport":
+		port, err := strconv.Atoi(value)
+		if err != nil {
+			return fmt.Errorf("invalid rport value: %s", value)
+		}
+		filters.Rport = port
+	case "user":
+		uid, err := strconv.Atoi(value)
+		if err == nil {
+			filters.UID = uid
+		} else {
+			filters.User = value
+		}
+	case "laddr":
+		filters.Laddr = value
+	case "raddr":
+		filters.Raddr = value
+	case "contains":
+		filters.Contains = value
+	case "if", "interface":
+		filters.Interface = value
+	case "mark":
+		filters.Mark = value
+	case "namespace":
+		filters.Namespace = value
+	case "inode":
+		inode, err := strconv.ParseInt(value, 10, 64)
+		if err != nil {
+			return fmt.Errorf("invalid inode value: %s", value)
+		}
+		filters.Inode = inode
+	case "since":
+		since, sinceRel, err := collector.ParseTimeFilter(value)
+		if err != nil {
+			return fmt.Errorf("invalid since value: %s", value)
+		}
+		filters.Since = since
+		filters.SinceRel = sinceRel
+	default:
+		return fmt.Errorf("unknown filter key: %s", key)
+	}
+	return nil
+}
+
+// FilterFlagsHelp returns the help text for common filter flags.
+const FilterFlagsHelp = `
+Filters are specified in key=value format. For example:
+  snitch ls proto=tcp state=established
+
+Available filters:
+  proto, state, pid, proc, lport, rport, user, laddr, raddr, contains, if, mark, namespace, inode, since`
+
+// addFilterFlags adds the common filter flags to a command.
+func addFilterFlags(cmd *cobra.Command) {
+	cmd.Flags().BoolVarP(&filterTCP, "tcp", "t", false, "Show only TCP connections")
+	cmd.Flags().BoolVarP(&filterUDP, "udp", "u", false, "Show only UDP connections")
+	cmd.Flags().BoolVarP(&filterListen, "listen", "l", false, "Show only listening sockets")
+	cmd.Flags().BoolVarP(&filterEstab, "established", "e", false, "Show only established connections")
+	cmd.Flags().BoolVarP(&filterIPv4, "ipv4", "4", false, "Only show IPv4 connections")
+	cmd.Flags().BoolVarP(&filterIPv6, "ipv6", "6", false, "Only show IPv6 connections")
+}
+
+// addResolutionFlags adds the common resolution flags to a command.
+func addResolutionFlags(cmd *cobra.Command) {
+	cfg := config.Get()
+	cmd.Flags().BoolVar(&resolveAddrs, "resolve-addrs", !cfg.Defaults.Numeric, "Resolve IP addresses to hostnames")
+	cmd.Flags().BoolVar(&resolvePorts, "resolve-ports", false, "Resolve port numbers to service names")
+	cmd.Flags().BoolVar(&noCache, "no-cache", !cfg.Defaults.DNSCache, "Disable DNS caching (force fresh lookups)")
+}
+

cmd/runtime_test.go

@@ -0,0 +1,525 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/karol-broda/snitch/internal/collector"
+)
+
+func TestParseFilterArgs_Empty(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "" {
+		t.Errorf("expected empty proto, got %q", filters.Proto)
+	}
+}
+
+func TestParseFilterArgs_Proto(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"proto=tcp"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "tcp" {
+		t.Errorf("expected proto 'tcp', got %q", filters.Proto)
+	}
+}
+
+func TestParseFilterArgs_State(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"state=LISTEN"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.State != "LISTEN" {
+		t.Errorf("expected state 'LISTEN', got %q", filters.State)
+	}
+}
+
+func TestParseFilterArgs_PID(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"pid=1234"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Pid != 1234 {
+		t.Errorf("expected pid 1234, got %d", filters.Pid)
+	}
+}
+
+func TestParseFilterArgs_InvalidPID(t *testing.T) {
+	_, err := ParseFilterArgs([]string{"pid=notanumber"})
+	if err == nil {
+		t.Error("expected error for invalid pid")
+	}
+}
+
+func TestParseFilterArgs_Proc(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"proc=nginx"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proc != "nginx" {
+		t.Errorf("expected proc 'nginx', got %q", filters.Proc)
+	}
+}
+
+func TestParseFilterArgs_Lport(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"lport=80"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Lport != 80 {
+		t.Errorf("expected lport 80, got %d", filters.Lport)
+	}
+}
+
+func TestParseFilterArgs_InvalidLport(t *testing.T) {
+	_, err := ParseFilterArgs([]string{"lport=notaport"})
+	if err == nil {
+		t.Error("expected error for invalid lport")
+	}
+}
+
+func TestParseFilterArgs_Rport(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"rport=443"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Rport != 443 {
+		t.Errorf("expected rport 443, got %d", filters.Rport)
+	}
+}
+
+func TestParseFilterArgs_InvalidRport(t *testing.T) {
+	_, err := ParseFilterArgs([]string{"rport=invalid"})
+	if err == nil {
+		t.Error("expected error for invalid rport")
+	}
+}
+
+func TestParseFilterArgs_UserByName(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"user=root"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.User != "root" {
+		t.Errorf("expected user 'root', got %q", filters.User)
+	}
+}
+
+func TestParseFilterArgs_UserByUID(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"user=1000"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.UID != 1000 {
+		t.Errorf("expected uid 1000, got %d", filters.UID)
+	}
+}
+
+func TestParseFilterArgs_Laddr(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"laddr=127.0.0.1"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Laddr != "127.0.0.1" {
+		t.Errorf("expected laddr '127.0.0.1', got %q", filters.Laddr)
+	}
+}
+
+func TestParseFilterArgs_Raddr(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"raddr=8.8.8.8"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Raddr != "8.8.8.8" {
+		t.Errorf("expected raddr '8.8.8.8', got %q", filters.Raddr)
+	}
+}
+
+func TestParseFilterArgs_Contains(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"contains=google"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Contains != "google" {
+		t.Errorf("expected contains 'google', got %q", filters.Contains)
+	}
+}
+
+func TestParseFilterArgs_Interface(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"if=eth0"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Interface != "eth0" {
+		t.Errorf("expected interface 'eth0', got %q", filters.Interface)
+	}
+
+	// test alternative syntax
+	filters2, err := ParseFilterArgs([]string{"interface=lo"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters2.Interface != "lo" {
+		t.Errorf("expected interface 'lo', got %q", filters2.Interface)
+	}
+}
+
+func TestParseFilterArgs_Mark(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"mark=0x1234"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Mark != "0x1234" {
+		t.Errorf("expected mark '0x1234', got %q", filters.Mark)
+	}
+}
+
+func TestParseFilterArgs_Namespace(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"namespace=default"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Namespace != "default" {
+		t.Errorf("expected namespace 'default', got %q", filters.Namespace)
+	}
+}
+
+func TestParseFilterArgs_Inode(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"inode=123456"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Inode != 123456 {
+		t.Errorf("expected inode 123456, got %d", filters.Inode)
+	}
+}
+
+func TestParseFilterArgs_InvalidInode(t *testing.T) {
+	_, err := ParseFilterArgs([]string{"inode=notanumber"})
+	if err == nil {
+		t.Error("expected error for invalid inode")
+	}
+}
+
+func TestParseFilterArgs_Multiple(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"proto=tcp", "state=LISTEN", "lport=80"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "tcp" {
+		t.Errorf("expected proto 'tcp', got %q", filters.Proto)
+	}
+	if filters.State != "LISTEN" {
+		t.Errorf("expected state 'LISTEN', got %q", filters.State)
+	}
+	if filters.Lport != 80 {
+		t.Errorf("expected lport 80, got %d", filters.Lport)
+	}
+}
+
+func TestParseFilterArgs_InvalidFormat(t *testing.T) {
+	_, err := ParseFilterArgs([]string{"invalidformat"})
+	if err == nil {
+		t.Error("expected error for invalid format")
+	}
+}
+
+func TestParseFilterArgs_UnknownKey(t *testing.T) {
+	_, err := ParseFilterArgs([]string{"unknownkey=value"})
+	if err == nil {
+		t.Error("expected error for unknown key")
+	}
+}
+
+func TestParseFilterArgs_CaseInsensitiveKeys(t *testing.T) {
+	filters, err := ParseFilterArgs([]string{"PROTO=tcp", "State=LISTEN"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "tcp" {
+		t.Errorf("expected proto 'tcp', got %q", filters.Proto)
+	}
+	if filters.State != "LISTEN" {
+		t.Errorf("expected state 'LISTEN', got %q", filters.State)
+	}
+}
+
+func TestBuildFilters_TCPOnly(t *testing.T) {
+	// save and restore global flags
+	oldTCP, oldUDP := filterTCP, filterUDP
+	defer func() {
+		filterTCP, filterUDP = oldTCP, oldUDP
+	}()
+
+	filterTCP = true
+	filterUDP = false
+
+	filters, err := BuildFilters([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "tcp" {
+		t.Errorf("expected proto 'tcp', got %q", filters.Proto)
+	}
+}
+
+func TestBuildFilters_UDPOnly(t *testing.T) {
+	oldTCP, oldUDP := filterTCP, filterUDP
+	defer func() {
+		filterTCP, filterUDP = oldTCP, oldUDP
+	}()
+
+	filterTCP = false
+	filterUDP = true
+
+	filters, err := BuildFilters([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "udp" {
+		t.Errorf("expected proto 'udp', got %q", filters.Proto)
+	}
+}
+
+func TestBuildFilters_ListenOnly(t *testing.T) {
+	oldListen, oldEstab := filterListen, filterEstab
+	defer func() {
+		filterListen, filterEstab = oldListen, oldEstab
+	}()
+
+	filterListen = true
+	filterEstab = false
+
+	filters, err := BuildFilters([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.State != "LISTEN" {
+		t.Errorf("expected state 'LISTEN', got %q", filters.State)
+	}
+}
+
+func TestBuildFilters_EstablishedOnly(t *testing.T) {
+	oldListen, oldEstab := filterListen, filterEstab
+	defer func() {
+		filterListen, filterEstab = oldListen, oldEstab
+	}()
+
+	filterListen = false
+	filterEstab = true
+
+	filters, err := BuildFilters([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.State != "ESTABLISHED" {
+		t.Errorf("expected state 'ESTABLISHED', got %q", filters.State)
+	}
+}
+
+func TestBuildFilters_IPv4Flag(t *testing.T) {
+	oldIPv4 := filterIPv4
+	defer func() {
+		filterIPv4 = oldIPv4
+	}()
+
+	filterIPv4 = true
+
+	filters, err := BuildFilters([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !filters.IPv4 {
+		t.Error("expected IPv4 to be true")
+	}
+}
+
+func TestBuildFilters_IPv6Flag(t *testing.T) {
+	oldIPv6 := filterIPv6
+	defer func() {
+		filterIPv6 = oldIPv6
+	}()
+
+	filterIPv6 = true
+
+	filters, err := BuildFilters([]string{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !filters.IPv6 {
+		t.Error("expected IPv6 to be true")
+	}
+}
+
+func TestBuildFilters_CombinedArgsAndFlags(t *testing.T) {
+	oldTCP := filterTCP
+	defer func() {
+		filterTCP = oldTCP
+	}()
+
+	filterTCP = true
+
+	filters, err := BuildFilters([]string{"lport=80"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if filters.Proto != "tcp" {
+		t.Errorf("expected proto 'tcp', got %q", filters.Proto)
+	}
+	if filters.Lport != 80 {
+		t.Errorf("expected lport 80, got %d", filters.Lport)
+	}
+}
+
+func TestRuntime_PreWarmDNS(t *testing.T) {
+	rt := &Runtime{
+		Connections: []collector.Connection{
+			{Laddr: "127.0.0.1", Raddr: "192.168.1.1"},
+			{Laddr: "127.0.0.1", Raddr: "10.0.0.1"},
+		},
+	}
+
+	// should not panic
+	rt.PreWarmDNS()
+}
+
+func TestRuntime_PreWarmDNS_Empty(t *testing.T) {
+	rt := &Runtime{
+		Connections: []collector.Connection{},
+	}
+
+	// should not panic with empty connections
+	rt.PreWarmDNS()
+}
+
+func TestRuntime_SortConnections(t *testing.T) {
+	rt := &Runtime{
+		Connections: []collector.Connection{
+			{Lport: 443},
+			{Lport: 80},
+			{Lport: 8080},
+		},
+	}
+
+	rt.SortConnections(collector.SortOptions{
+		Field:     collector.SortByLport,
+		Direction: collector.SortAsc,
+	})
+
+	if rt.Connections[0].Lport != 80 {
+		t.Errorf("expected first connection to have lport 80, got %d", rt.Connections[0].Lport)
+	}
+	if rt.Connections[1].Lport != 443 {
+		t.Errorf("expected second connection to have lport 443, got %d", rt.Connections[1].Lport)
+	}
+	if rt.Connections[2].Lport != 8080 {
+		t.Errorf("expected third connection to have lport 8080, got %d", rt.Connections[2].Lport)
+	}
+}
+
+func TestRuntime_SortConnections_Desc(t *testing.T) {
+	rt := &Runtime{
+		Connections: []collector.Connection{
+			{Lport: 80},
+			{Lport: 443},
+			{Lport: 8080},
+		},
+	}
+
+	rt.SortConnections(collector.SortOptions{
+		Field:     collector.SortByLport,
+		Direction: collector.SortDesc,
+	})
+
+	if rt.Connections[0].Lport != 8080 {
+		t.Errorf("expected first connection to have lport 8080, got %d", rt.Connections[0].Lport)
+	}
+}
+
+func TestApplyFilter_AllKeys(t *testing.T) {
+	tests := []struct {
+		key      string
+		value    string
+		validate func(t *testing.T, f *collector.FilterOptions)
+	}{
+		{"proto", "tcp", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Proto != "tcp" {
+				t.Errorf("proto: expected 'tcp', got %q", f.Proto)
+			}
+		}},
+		{"state", "LISTEN", func(t *testing.T, f *collector.FilterOptions) {
+			if f.State != "LISTEN" {
+				t.Errorf("state: expected 'LISTEN', got %q", f.State)
+			}
+		}},
+		{"pid", "100", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Pid != 100 {
+				t.Errorf("pid: expected 100, got %d", f.Pid)
+			}
+		}},
+		{"proc", "nginx", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Proc != "nginx" {
+				t.Errorf("proc: expected 'nginx', got %q", f.Proc)
+			}
+		}},
+		{"lport", "80", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Lport != 80 {
+				t.Errorf("lport: expected 80, got %d", f.Lport)
+			}
+		}},
+		{"rport", "443", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Rport != 443 {
+				t.Errorf("rport: expected 443, got %d", f.Rport)
+			}
+		}},
+		{"laddr", "127.0.0.1", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Laddr != "127.0.0.1" {
+				t.Errorf("laddr: expected '127.0.0.1', got %q", f.Laddr)
+			}
+		}},
+		{"raddr", "8.8.8.8", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Raddr != "8.8.8.8" {
+				t.Errorf("raddr: expected '8.8.8.8', got %q", f.Raddr)
+			}
+		}},
+		{"contains", "test", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Contains != "test" {
+				t.Errorf("contains: expected 'test', got %q", f.Contains)
+			}
+		}},
+		{"if", "eth0", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Interface != "eth0" {
+				t.Errorf("interface: expected 'eth0', got %q", f.Interface)
+			}
+		}},
+		{"mark", "0xff", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Mark != "0xff" {
+				t.Errorf("mark: expected '0xff', got %q", f.Mark)
+			}
+		}},
+		{"namespace", "ns1", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Namespace != "ns1" {
+				t.Errorf("namespace: expected 'ns1', got %q", f.Namespace)
+			}
+		}},
+		{"inode", "12345", func(t *testing.T, f *collector.FilterOptions) {
+			if f.Inode != 12345 {
+				t.Errorf("inode: expected 12345, got %d", f.Inode)
+			}
+		}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.key, func(t *testing.T) {
+			filters := &collector.FilterOptions{}
+			err := applyFilter(filters, tt.key, tt.value)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			tt.validate(t, filters)
+		})
+	}
+}
+

cmd/stats.go

@@ -8,7 +8,6 @@ import (
 	"log"
 	"os"
 	"os/signal"
-	"snitch/internal/collector"
 	"sort"
 	"strconv"
 	"strings"
@@ -17,6 +16,9 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 type StatsData struct {
@@ -39,6 +41,7 @@ type InterfaceStats struct {
 	Count     int    `json:"count"`
 }
 
+// stats-specific flags
 var (
 	statsOutputFormat string
 	statsInterval     time.Duration
@@ -63,12 +66,10 @@ Available filters:
 }
 
 func runStatsCommand(args []string) {
-	filters, err := parseFilters(args)
+	filters, err := BuildFilters(args)
 	if err != nil {
 		log.Fatalf("Error parsing filters: %v", err)
 	}
-	filters.IPv4 = ipv4
-	filters.IPv6 = ipv6
 
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -121,13 +122,11 @@ func runStatsCommand(args []string) {
 }
 
 func generateStats(filters collector.FilterOptions) (*StatsData, error) {
-	connections, err := collector.GetConnections()
+	filteredConnections, err := FetchConnections(filters)
 	if err != nil {
 		return nil, err
 	}
 
-	filteredConnections := collector.FilterConnections(connections, filters)
-
 	stats := &StatsData{
 		Timestamp: time.Now(),
 		Total:     len(filteredConnections),
@@ -230,19 +229,19 @@ func printStatsCSV(stats *StatsData, headers bool) {
 
 func printStatsTable(stats *StatsData, headers bool) {
 	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0)
-	defer w.Flush()
+	defer errutil.Flush(w)
 
 	if headers {
-		fmt.Fprintf(w, "TIMESTAMP\t%s\n", stats.Timestamp.Format(time.RFC3339))
-		fmt.Fprintf(w, "TOTAL CONNECTIONS\t%d\n", stats.Total)
-		fmt.Fprintln(w)
+		errutil.Ignore(fmt.Fprintf(w, "TIMESTAMP\t%s\n", stats.Timestamp.Format(time.RFC3339)))
+		errutil.Ignore(fmt.Fprintf(w, "TOTAL CONNECTIONS\t%d\n", stats.Total))
+		errutil.Ignore(fmt.Fprintln(w))
 	}
 
 	// Protocol breakdown
 	if len(stats.ByProto) > 0 {
 		if headers {
-			fmt.Fprintln(w, "BY PROTOCOL:")
-			fmt.Fprintln(w, "PROTO\tCOUNT")
+			errutil.Ignore(fmt.Fprintln(w, "BY PROTOCOL:"))
+			errutil.Ignore(fmt.Fprintln(w, "PROTO\tCOUNT"))
 		}
 		protocols := make([]string, 0, len(stats.ByProto))
 		for proto := range stats.ByProto {
@@ -250,16 +249,16 @@ func printStatsTable(stats *StatsData, headers bool) {
 		}
 		sort.Strings(protocols)
 		for _, proto := range protocols {
-			fmt.Fprintf(w, "%s\t%d\n", strings.ToUpper(proto), stats.ByProto[proto])
+			errutil.Ignore(fmt.Fprintf(w, "%s\t%d\n", strings.ToUpper(proto), stats.ByProto[proto]))
 		}
-		fmt.Fprintln(w)
+		errutil.Ignore(fmt.Fprintln(w))
 	}
 
 	// State breakdown
 	if len(stats.ByState) > 0 {
 		if headers {
-			fmt.Fprintln(w, "BY STATE:")
-			fmt.Fprintln(w, "STATE\tCOUNT")
+			errutil.Ignore(fmt.Fprintln(w, "BY STATE:"))
+			errutil.Ignore(fmt.Fprintln(w, "STATE\tCOUNT"))
 		}
 		states := make([]string, 0, len(stats.ByState))
 		for state := range stats.ByState {
@@ -267,16 +266,16 @@ func printStatsTable(stats *StatsData, headers bool) {
 		}
 		sort.Strings(states)
 		for _, state := range states {
-			fmt.Fprintf(w, "%s\t%d\n", state, stats.ByState[state])
+			errutil.Ignore(fmt.Fprintf(w, "%s\t%d\n", state, stats.ByState[state]))
 		}
-		fmt.Fprintln(w)
+		errutil.Ignore(fmt.Fprintln(w))
 	}
 
 	// Process breakdown (top 10)
 	if len(stats.ByProc) > 0 {
 		if headers {
-			fmt.Fprintln(w, "BY PROCESS (TOP 10):")
-			fmt.Fprintln(w, "PID\tPROCESS\tCOUNT")
+			errutil.Ignore(fmt.Fprintln(w, "BY PROCESS (TOP 10):"))
+			errutil.Ignore(fmt.Fprintln(w, "PID\tPROCESS\tCOUNT"))
 		}
 		limit := 10
 		if len(stats.ByProc) < limit {
@@ -284,17 +283,20 @@ func printStatsTable(stats *StatsData, headers bool) {
 		}
 		for i := 0; i < limit; i++ {
 			proc := stats.ByProc[i]
-			fmt.Fprintf(w, "%d\t%s\t%d\n", proc.PID, proc.Process, proc.Count)
+			errutil.Ignore(fmt.Fprintf(w, "%d\t%s\t%d\n", proc.PID, proc.Process, proc.Count))
 		}
 	}
 }
 
 func init() {
 	rootCmd.AddCommand(statsCmd)
+
+	// stats-specific flags
 	statsCmd.Flags().StringVarP(&statsOutputFormat, "output", "o", "table", "Output format (table, json, csv)")
 	statsCmd.Flags().DurationVarP(&statsInterval, "interval", "i", 0, "Refresh interval (0 = one-shot)")
 	statsCmd.Flags().IntVarP(&statsCount, "count", "c", 0, "Number of iterations (0 = unlimited)")
 	statsCmd.Flags().BoolVar(&statsNoHeaders, "no-headers", false, "Omit headers for table/csv output")
-	statsCmd.Flags().BoolVarP(&ipv4, "ipv4", "4", false, "Only show IPv4 connections")
-	statsCmd.Flags().BoolVarP(&ipv6, "ipv6", "6", false, "Only show IPv6 connections")
+
+	// shared filter flags
+	addFilterFlags(statsCmd)
 }

cmd/testdata/golden/mixed_protocols_json.golden

@@ -28,7 +28,7 @@
     "uid": 0,
     "proto": "udp",
     "ipversion": "",
-    "state": "CONNECTED",
+    "state": "LISTEN",
     "laddr": "0.0.0.0",
     "lport": 53,
     "raddr": "",

cmd/testdata/golden/mixed_protocols_table.golden

@@ -1,4 +1,4 @@
 PID   PROCESS      USER   PROTO           STATE                LADDR            LPORT    RADDR   RPORT
 1            tcp-server          tcp    LISTEN      0.0.0.0          http             0
-2            udp-server          udp    CONNECTED   0.0.0.0          domain           0
+2            udp-server          udp    LISTEN      0.0.0.0          domain           0
 3            unix-app            unix   CONNECTED   /tmp/test.sock   0                0

cmd/testdata/golden/udp_filter_json.golden

@@ -7,7 +7,7 @@
     "uid": 0,
     "proto": "udp",
     "ipversion": "",
-    "state": "CONNECTED",
+    "state": "LISTEN",
     "laddr": "0.0.0.0",
     "lport": 53,
     "raddr": "",

cmd/themes.go

@@ -0,0 +1,24 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/karol-broda/snitch/internal/theme"
+	"github.com/spf13/cobra"
+)
+
+var themesCmd = &cobra.Command{
+	Use:   "themes",
+	Short: "List available themes",
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Printf("Available themes (default: %s):\n\n", theme.DefaultTheme)
+		for _, name := range theme.ListThemes() {
+			fmt.Printf("  %s\n", name)
+		}
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(themesCmd)
+}
+

cmd/top.go

@@ -2,21 +2,19 @@ package cmd
 
 import (
 	"log"
-	"snitch/internal/config"
-	"snitch/internal/tui"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
+	"github.com/karol-broda/snitch/internal/config"
+	"github.com/karol-broda/snitch/internal/resolver"
+	"github.com/karol-broda/snitch/internal/tui"
 	"github.com/spf13/cobra"
 )
 
+// top-specific flags
 var (
 	topTheme    string
 	topInterval time.Duration
-	topTCP      bool
-	topUDP      bool
-	topListen   bool
-	topEstab    bool
 )
 
 var topCmd = &cobra.Command{
@@ -30,17 +28,25 @@ var topCmd = &cobra.Command{
 			theme = cfg.Defaults.Theme
 		}
 
+		// configure resolver with cache setting
+		effectiveNoCache := noCache || !cfg.Defaults.DNSCache
+		resolver.SetNoCache(effectiveNoCache)
+
 		opts := tui.Options{
 			Theme:         theme,
 			Interval:      topInterval,
+			ResolveAddrs:  resolveAddrs,
+			ResolvePorts:  resolvePorts,
+			NoCache:       effectiveNoCache,
+			RememberState: cfg.TUI.RememberState,
 		}
 
 		// if any filter flag is set, use exclusive mode
-		if topTCP || topUDP || topListen || topEstab {
-			opts.TCP = topTCP
-			opts.UDP = topUDP
-			opts.Listening = topListen
-			opts.Established = topEstab
+		if filterTCP || filterUDP || filterListen || filterEstab {
+			opts.TCP = filterTCP
+			opts.UDP = filterUDP
+			opts.Listening = filterListen
+			opts.Established = filterEstab
 			opts.Other = false
 			opts.FilterSet = true
 		}
@@ -57,10 +63,12 @@ var topCmd = &cobra.Command{
 func init() {
 	rootCmd.AddCommand(topCmd)
 	cfg := config.Get()
-	topCmd.Flags().StringVar(&topTheme, "theme", cfg.Defaults.Theme, "Theme for TUI (dark, light, mono, auto)")
+
+	// top-specific flags
+	topCmd.Flags().StringVar(&topTheme, "theme", cfg.Defaults.Theme, "Theme for TUI (see 'snitch themes')")
 	topCmd.Flags().DurationVarP(&topInterval, "interval", "i", time.Second, "Refresh interval")
-	topCmd.Flags().BoolVarP(&topTCP, "tcp", "t", false, "Show only TCP connections")
-	topCmd.Flags().BoolVarP(&topUDP, "udp", "u", false, "Show only UDP connections")
-	topCmd.Flags().BoolVarP(&topListen, "listen", "l", false, "Show only listening sockets")
-	topCmd.Flags().BoolVarP(&topEstab, "established", "e", false, "Show only established connections")
+
+	// shared flags
+	addFilterFlags(topCmd)
+	addResolutionFlags(topCmd)
 }

cmd/trace.go

@@ -7,12 +7,14 @@ import (
 	"log"
 	"os"
 	"os/signal"
-	"snitch/internal/collector"
-	"snitch/internal/resolver"
 	"strings"
 	"syscall"
 	"time"
 
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/config"
+	"github.com/karol-broda/snitch/internal/resolver"
+
 	"github.com/spf13/cobra"
 )
 
@@ -26,7 +28,6 @@ var (
 	traceInterval     time.Duration
 	traceCount        int
 	traceOutputFormat string
-	traceNumeric     bool
 	traceTimestamp    bool
 )
 
@@ -47,12 +48,16 @@ Available filters:
 }
 
 func runTraceCommand(args []string) {
-	filters, err := parseFilters(args)
+	cfg := config.Get()
+	
+	// configure resolver with cache setting
+	effectiveNoCache := noCache || !cfg.Defaults.DNSCache
+	resolver.SetNoCache(effectiveNoCache)
+
+	filters, err := BuildFilters(args)
 	if err != nil {
 		log.Fatalf("Error parsing filters: %v", err)
 	}
-	filters.IPv4 = ipv4
-	filters.IPv6 = ipv6
 
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -182,14 +187,16 @@ func printTraceEventHuman(event TraceEvent) {
 	lportStr := fmt.Sprintf("%d", conn.Lport)
 	rportStr := fmt.Sprintf("%d", conn.Rport)
 	
-	// Handle name resolution based on numeric flag
-	if !traceNumeric {
+	// apply name resolution
+	if resolveAddrs {
 		if resolvedLaddr := resolver.ResolveAddr(conn.Laddr); resolvedLaddr != conn.Laddr {
 			laddr = resolvedLaddr
 		}
 		if resolvedRaddr := resolver.ResolveAddr(conn.Raddr); resolvedRaddr != conn.Raddr && conn.Raddr != "*" && conn.Raddr != "" {
 			raddr = resolvedRaddr
 		}
+	}
+	if resolvePorts {
 		if resolvedLport := resolver.ResolvePort(conn.Lport, conn.Proto); resolvedLport != fmt.Sprintf("%d", conn.Lport) {
 			lportStr = resolvedLport
 		}
@@ -222,11 +229,14 @@ func printTraceEventHuman(event TraceEvent) {
 
 func init() {
 	rootCmd.AddCommand(traceCmd)
+
+	// trace-specific flags
 	traceCmd.Flags().DurationVarP(&traceInterval, "interval", "i", time.Second, "Polling interval (e.g., 500ms, 2s)")
 	traceCmd.Flags().IntVarP(&traceCount, "count", "c", 0, "Number of events to capture (0 = unlimited)")
 	traceCmd.Flags().StringVarP(&traceOutputFormat, "output", "o", "human", "Output format (human, json)")
-	traceCmd.Flags().BoolVarP(&traceNumeric, "numeric", "n", false, "Don't resolve hostnames")
 	traceCmd.Flags().BoolVar(&traceTimestamp, "ts", false, "Include timestamp in output")
-	traceCmd.Flags().BoolVarP(&ipv4, "ipv4", "4", false, "Only trace IPv4 connections")
-	traceCmd.Flags().BoolVarP(&ipv6, "ipv6", "6", false, "Only trace IPv6 connections")
+
+	// shared flags
+	addFilterFlags(traceCmd)
+	addResolutionFlags(traceCmd)
 }

cmd/upgrade.go

@@ -0,0 +1,689 @@
+package cmd
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strconv"
+	"strings"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/errutil"
+	"github.com/karol-broda/snitch/internal/tui"
+)
+
+const (
+	repoOwner = "karol-broda"
+	repoName  = "snitch"
+	githubAPI = "https://api.github.com"
+	firstUpgradeVersion = "0.1.8"
+)
+
+var (
+	upgradeYes     bool
+	upgradeVersion string
+)
+
+var upgradeCmd = &cobra.Command{
+	Use:   "upgrade",
+	Short: "Check for updates and optionally upgrade snitch",
+	Long: `Check for available updates and show upgrade instructions.
+
+Use --yes to perform an in-place upgrade automatically.
+Use --version to install a specific version.`,
+	RunE: runUpgrade,
+}
+
+func init() {
+	upgradeCmd.Flags().BoolVarP(&upgradeYes, "yes", "y", false, "Perform the upgrade automatically")
+	upgradeCmd.Flags().StringVarP(&upgradeVersion, "version", "v", "", "Install a specific version (e.g., v0.1.7)")
+	rootCmd.AddCommand(upgradeCmd)
+}
+
+type githubRelease struct {
+	TagName string `json:"tag_name"`
+	HTMLURL string `json:"html_url"`
+}
+
+type githubCommit struct {
+	SHA string `json:"sha"`
+}
+
+type githubCompare struct {
+	Status      string `json:"status"`
+	AheadBy     int    `json:"ahead_by"`
+	BehindBy    int    `json:"behind_by"`
+	TotalCommits int   `json:"total_commits"`
+}
+
+func runUpgrade(cmd *cobra.Command, args []string) error {
+	current := Version
+	nixInstall := isNixInstall()
+	nixVersion := isNixVersion(current)
+
+	if upgradeVersion != "" {
+		if nixInstall || nixVersion {
+			return handleNixSpecificVersion(current, upgradeVersion)
+		}
+		return handleSpecificVersion(current, upgradeVersion)
+	}
+
+	latest, err := fetchLatestVersion()
+	if err != nil {
+		return fmt.Errorf("failed to check for updates: %w", err)
+	}
+
+	if nixInstall || nixVersion {
+		return handleNixUpgrade(current, latest)
+	}
+
+	currentClean := strings.TrimPrefix(current, "v")
+	latestClean := strings.TrimPrefix(latest, "v")
+
+	printVersionComparison(current, latest)
+
+	if currentClean == latestClean {
+		green := color.New(color.FgGreen)
+		errutil.Println(green, tui.SymbolSuccess+" you are running the latest version")
+		return nil
+	}
+
+	if current == "dev" {
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" you are running a development build")
+		fmt.Println()
+		fmt.Println("use one of the methods below to install a release version:")
+		fmt.Println()
+		printUpgradeInstructions()
+		return nil
+	}
+
+	green := color.New(color.FgGreen, color.Bold)
+	errutil.Printf(green, tui.SymbolSuccess+" update available: %s "+tui.SymbolArrowRight+" %s\n", current, latest)
+	fmt.Println()
+
+	if !upgradeYes {
+		printUpgradeInstructions()
+		fmt.Println()
+		faint := color.New(color.Faint)
+		cmdStyle := color.New(color.FgCyan)
+		errutil.Print(faint, "  in-place      ")
+		errutil.Println(cmdStyle, "snitch upgrade --yes")
+		return nil
+	}
+
+	return performUpgrade(latest)
+}
+
+func handleSpecificVersion(current, target string) error {
+	if !strings.HasPrefix(target, "v") {
+		target = "v" + target
+	}
+	targetClean := strings.TrimPrefix(target, "v")
+
+	printVersionComparisonTarget(current, target)
+
+	if isVersionLower(targetClean, firstUpgradeVersion) {
+		yellow := color.New(color.FgYellow)
+		errutil.Printf(yellow, tui.SymbolWarning+" warning: the upgrade command was introduced in v%s\n", firstUpgradeVersion)
+		faint := color.New(color.Faint)
+		errutil.Printf(faint, "  version %s does not include this command\n", target)
+		errutil.Println(faint, "  you will need to use other methods to upgrade from that version")
+		fmt.Println()
+	}
+
+	currentClean := strings.TrimPrefix(current, "v")
+	if currentClean == targetClean {
+		green := color.New(color.FgGreen)
+		errutil.Println(green, tui.SymbolSuccess+" you are already running this version")
+		return nil
+	}
+
+	if !upgradeYes {
+		faint := color.New(color.Faint)
+		cmdStyle := color.New(color.FgCyan)
+		if isVersionLower(targetClean, currentClean) {
+			yellow := color.New(color.FgYellow)
+			errutil.Printf(yellow, tui.SymbolArrowDown+" this will downgrade from %s to %s\n", current, target)
+		} else {
+			green := color.New(color.FgGreen)
+			errutil.Printf(green, tui.SymbolArrowUp+" this will upgrade from %s to %s\n", current, target)
+		}
+		fmt.Println()
+		errutil.Print(faint, "run ")
+		errutil.Printf(cmdStyle, "snitch upgrade --version %s --yes", target)
+		errutil.Println(faint, " to proceed")
+		return nil
+	}
+
+	return performUpgrade(target)
+}
+
+func handleNixUpgrade(current, latest string) error {
+	faint := color.New(color.Faint)
+	version := color.New(color.FgCyan)
+
+	currentCommit := extractCommitFromVersion(current)
+	dirty := isNixDirty(current)
+
+	errutil.Print(faint, "current  ")
+	errutil.Print(version, current)
+	if currentCommit != "" {
+		errutil.Printf(faint, " (commit %s)", currentCommit)
+	}
+	fmt.Println()
+
+	errutil.Print(faint, "latest   ")
+	errutil.Println(version, latest)
+	fmt.Println()
+
+	if dirty {
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" you are running a dirty nix build (uncommitted changes)")
+		fmt.Println()
+		printNixUpgradeInstructions()
+		return nil
+	}
+
+	if currentCommit == "" {
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
+		fmt.Println()
+		printNixUpgradeInstructions()
+		return nil
+	}
+
+	releaseCommit, err := fetchCommitForTag(latest)
+	if err != nil {
+		errutil.Printf(faint, "  (could not fetch release commit: %v)\n", err)
+		fmt.Println()
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
+		fmt.Println()
+		printNixUpgradeInstructions()
+		return nil
+	}
+
+	releaseShort := releaseCommit
+	if len(releaseShort) > 7 {
+		releaseShort = releaseShort[:7]
+	}
+
+	if strings.HasPrefix(releaseCommit, currentCommit) || strings.HasPrefix(currentCommit, releaseShort) {
+		green := color.New(color.FgGreen)
+		errutil.Printf(green, tui.SymbolSuccess+" you are running %s (commit %s)\n", latest, releaseShort)
+		return nil
+	}
+
+	comparison, err := compareCommits(latest, currentCommit)
+	if err != nil {
+		green := color.New(color.FgGreen, color.Bold)
+		errutil.Printf(green, tui.SymbolSuccess+" update available: %s "+tui.SymbolArrowRight+" %s\n", currentCommit, latest)
+		errutil.Printf(faint, "  your commit: %s\n", currentCommit)
+		errutil.Printf(faint, "  release:     %s (%s)\n", releaseShort, latest)
+		fmt.Println()
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
+		fmt.Println()
+		printNixUpgradeInstructions()
+		return nil
+	}
+
+	if comparison.AheadBy > 0 {
+		cyan := color.New(color.FgCyan)
+		errutil.Printf(cyan, tui.SymbolArrowUp+" you are %d commit(s) ahead of %s\n", comparison.AheadBy, latest)
+		errutil.Printf(faint, "  your commit: %s\n", currentCommit)
+		errutil.Printf(faint, "  release:     %s (%s)\n", releaseShort, latest)
+		fmt.Println()
+		errutil.Println(faint, "you are running a newer build than the latest release")
+		return nil
+	}
+
+	if comparison.BehindBy > 0 {
+		green := color.New(color.FgGreen, color.Bold)
+		errutil.Printf(green, tui.SymbolSuccess+" update available: %d commit(s) behind %s\n", comparison.BehindBy, latest)
+		errutil.Printf(faint, "  your commit: %s\n", currentCommit)
+		errutil.Printf(faint, "  release:     %s (%s)\n", releaseShort, latest)
+		fmt.Println()
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
+		fmt.Println()
+		printNixUpgradeInstructions()
+		return nil
+	}
+
+	green := color.New(color.FgGreen)
+	errutil.Printf(green, tui.SymbolSuccess+" you are running %s (commit %s)\n", latest, releaseShort)
+	return nil
+}
+
+func handleNixSpecificVersion(current, target string) error {
+	if !strings.HasPrefix(target, "v") {
+		target = "v" + target
+	}
+
+	printVersionComparisonTarget(current, target)
+
+	yellow := color.New(color.FgYellow)
+	errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
+	faint := color.New(color.Faint)
+	errutil.Println(faint, "  nix store is immutable; in-place upgrades are not supported")
+	fmt.Println()
+
+	bold := color.New(color.Bold)
+	cmd := color.New(color.FgCyan)
+
+	errutil.Println(bold, "to install a specific version with nix:")
+	fmt.Println()
+
+	errutil.Print(faint, "  specific ref    ")
+	errutil.Printf(cmd, "nix profile install github:%s/%s/%s\n", repoOwner, repoName, target)
+
+	errutil.Print(faint, "  latest          ")
+	errutil.Printf(cmd, "nix profile install github:%s/%s\n", repoOwner, repoName)
+
+	return nil
+}
+
+func isVersionLower(v1, v2 string) bool {
+	parts1 := parseVersion(v1)
+	parts2 := parseVersion(v2)
+
+	for i := 0; i < 3; i++ {
+		if parts1[i] < parts2[i] {
+			return true
+		}
+		if parts1[i] > parts2[i] {
+			return false
+		}
+	}
+	return false
+}
+
+func parseVersion(v string) [3]int {
+	var parts [3]int
+	segments := strings.Split(v, ".")
+
+	for i := 0; i < len(segments) && i < 3; i++ {
+		n, err := strconv.Atoi(segments[i])
+		if err == nil {
+			parts[i] = n
+		}
+	}
+	return parts
+}
+
+func fetchLatestVersion() (string, error) {
+	url := fmt.Sprintf("%s/repos/%s/%s/releases/latest", githubAPI, repoOwner, repoName)
+
+	resp, err := http.Get(url)
+	if err != nil {
+		return "", err
+	}
+	defer errutil.Close(resp.Body)
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("github api returned status %d", resp.StatusCode)
+	}
+
+	var release githubRelease
+	if err := json.NewDecoder(resp.Body).Decode(&release); err != nil {
+		return "", err
+	}
+
+	if release.TagName == "" {
+		return "", fmt.Errorf("no releases found")
+	}
+
+	return release.TagName, nil
+}
+
+func printVersionComparison(current, latest string) {
+	faint := color.New(color.Faint)
+	version := color.New(color.FgCyan)
+
+	errutil.Print(faint, "current  ")
+	errutil.Println(version, current)
+	errutil.Print(faint, "latest   ")
+	errutil.Println(version, latest)
+	fmt.Println()
+}
+
+func printVersionComparisonTarget(current, target string) {
+	faint := color.New(color.Faint)
+	version := color.New(color.FgCyan)
+
+	errutil.Print(faint, "current  ")
+	errutil.Println(version, current)
+	errutil.Print(faint, "target   ")
+	errutil.Println(version, target)
+	fmt.Println()
+}
+
+func printUpgradeInstructions() {
+	bold := color.New(color.Bold)
+	faint := color.New(color.Faint)
+	cmd := color.New(color.FgCyan)
+
+	errutil.Println(bold, "upgrade options:")
+	fmt.Println()
+
+	errutil.Print(faint, "  go install    ")
+	errutil.Printf(cmd, "go install github.com/%s/%s@latest\n", repoOwner, repoName)
+
+	errutil.Print(faint, "  shell script  ")
+	errutil.Printf(cmd, "curl -sSL https://raw.githubusercontent.com/%s/%s/master/install.sh | sh\n", repoOwner, repoName)
+
+	errutil.Print(faint, "  arch (aur)    ")
+	errutil.Println(cmd, "yay -S snitch-bin")
+
+	errutil.Print(faint, "  nix           ")
+	errutil.Printf(cmd, "nix profile upgrade --inputs-from github:%s/%s\n", repoOwner, repoName)
+}
+
+func performUpgrade(version string) error {
+	execPath, err := os.Executable()
+	if err != nil {
+		return fmt.Errorf("failed to get executable path: %w", err)
+	}
+
+	execPath, err = filepath.EvalSymlinks(execPath)
+	if err != nil {
+		return fmt.Errorf("failed to resolve executable path: %w", err)
+	}
+
+	if strings.HasPrefix(execPath, "/nix/store/") {
+		yellow := color.New(color.FgYellow)
+		errutil.Println(yellow, tui.SymbolWarning+" cannot perform in-place upgrade for nix installation")
+		fmt.Println()
+		printNixUpgradeInstructions()
+		return nil
+	}
+
+	goos := runtime.GOOS
+	goarch := runtime.GOARCH
+
+	versionClean := strings.TrimPrefix(version, "v")
+	archiveName := fmt.Sprintf("%s_%s_%s_%s.tar.gz", repoName, versionClean, goos, goarch)
+	downloadURL := fmt.Sprintf("https://github.com/%s/%s/releases/download/%s/%s",
+		repoOwner, repoName, version, archiveName)
+
+	faint := color.New(color.Faint)
+	cyan := color.New(color.FgCyan)
+	errutil.Print(faint, tui.SymbolDownload+" downloading ")
+	errutil.Printf(cyan, "%s", archiveName)
+	errutil.Println(faint, "...")
+
+	resp, err := http.Get(downloadURL)
+	if err != nil {
+		return fmt.Errorf("failed to download: %w", err)
+	}
+	defer errutil.Close(resp.Body)
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("download failed with status %d", resp.StatusCode)
+	}
+
+	tmpDir, err := os.MkdirTemp("", "snitch-upgrade-*")
+	if err != nil {
+		return fmt.Errorf("failed to create temp directory: %w", err)
+	}
+	defer errutil.RemoveAll(tmpDir)
+
+	binaryPath, err := extractBinaryFromTarGz(resp.Body, tmpDir)
+	if err != nil {
+		return fmt.Errorf("failed to extract binary: %w", err)
+	}
+
+	if goos == "darwin" {
+		removeQuarantine(binaryPath)
+	}
+
+	// check if we can write to the target location
+	targetDir := filepath.Dir(execPath)
+	if !isWritable(targetDir) {
+		yellow := color.New(color.FgYellow)
+		cmdStyle := color.New(color.FgCyan)
+
+		errutil.Printf(yellow, tui.SymbolWarning+" elevated permissions required to install to %s\n", targetDir)
+		fmt.Println()
+		errutil.Println(faint, "run with sudo or install to a user-writable location:")
+		fmt.Println()
+		errutil.Print(faint, "  sudo         ")
+		errutil.Println(cmdStyle, "sudo snitch upgrade --yes")
+		errutil.Print(faint, "  custom dir   ")
+		errutil.Printf(cmdStyle, "curl -sSL https://raw.githubusercontent.com/%s/%s/master/install.sh | INSTALL_DIR=~/.local/bin sh\n",
+			repoOwner, repoName)
+		return nil
+	}
+
+	// replace the binary
+	backupPath := execPath + ".bak"
+	if err := os.Rename(execPath, backupPath); err != nil {
+		return fmt.Errorf("failed to backup current binary: %w", err)
+	}
+
+	if err := copyFile(binaryPath, execPath); err != nil {
+		// try to restore backup
+		if restoreErr := os.Rename(backupPath, execPath); restoreErr != nil {
+			return fmt.Errorf("failed to install new binary and restore backup: %w (restore error: %v)", err, restoreErr)
+		}
+		return fmt.Errorf("failed to install new binary: %w", err)
+	}
+
+	if err := os.Chmod(execPath, 0755); err != nil {
+		return fmt.Errorf("failed to set executable permissions: %w", err)
+	}
+
+	if err := os.Remove(backupPath); err != nil {
+		// non-fatal, just warn
+		yellow := color.New(color.FgYellow)
+		errutil.Fprintf(yellow, os.Stderr, tui.SymbolWarning+" warning: failed to remove backup file %s: %v\n", backupPath, err)
+	}
+
+	green := color.New(color.FgGreen, color.Bold)
+	errutil.Printf(green, tui.SymbolSuccess+" successfully upgraded to %s\n", version)
+	return nil
+}
+
+func extractBinaryFromTarGz(r io.Reader, destDir string) (string, error) {
+	gzr, err := gzip.NewReader(r)
+	if err != nil {
+		return "", err
+	}
+	defer errutil.Close(gzr)
+
+	tr := tar.NewReader(gzr)
+
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return "", err
+		}
+
+		if header.Typeflag != tar.TypeReg {
+			continue
+		}
+
+		// look for the snitch binary
+		name := filepath.Base(header.Name)
+		if name != repoName {
+			continue
+		}
+
+		destPath := filepath.Join(destDir, name)
+		outFile, err := os.Create(destPath)
+		if err != nil {
+			return "", err
+		}
+
+		if _, err := io.Copy(outFile, tr); err != nil {
+			errutil.Close(outFile)
+			return "", err
+		}
+		errutil.Close(outFile)
+
+		return destPath, nil
+	}
+
+	return "", fmt.Errorf("binary not found in archive")
+}
+
+func isWritable(path string) bool {
+	testFile := filepath.Join(path, ".snitch-write-test")
+	f, err := os.Create(testFile)
+	if err != nil {
+		return false
+	}
+	errutil.Close(f)
+	errutil.Remove(testFile)
+	return true
+}
+
+func copyFile(src, dst string) error {
+	srcFile, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer errutil.Close(srcFile)
+
+	dstFile, err := os.Create(dst)
+	if err != nil {
+		return err
+	}
+	defer errutil.Close(dstFile)
+
+	if _, err := io.Copy(dstFile, srcFile); err != nil {
+		return err
+	}
+
+	return dstFile.Sync()
+}
+
+func removeQuarantine(path string) {
+	cmd := exec.Command("xattr", "-d", "com.apple.quarantine", path)
+	if err := cmd.Run(); err == nil {
+		faint := color.New(color.Faint)
+		errutil.Println(faint, "  removed macOS quarantine attribute")
+	}
+}
+
+func isNixInstall() bool {
+	execPath, err := os.Executable()
+	if err != nil {
+		return false
+	}
+
+	resolved, err := filepath.EvalSymlinks(execPath)
+	if err != nil {
+		return false
+	}
+
+	return strings.HasPrefix(resolved, "/nix/store/")
+}
+
+var nixVersionPattern = regexp.MustCompile(`^nix-([a-f0-9]+)(-dirty)?$`)
+var commitHashPattern = regexp.MustCompile(`^[a-f0-9]{7,40}$`)
+
+func isNixVersion(version string) bool {
+	if nixVersionPattern.MatchString(version) {
+		return true
+	}
+	if commitHashPattern.MatchString(version) {
+		return true
+	}
+	return false
+}
+
+func extractCommitFromVersion(version string) string {
+	matches := nixVersionPattern.FindStringSubmatch(version)
+	if len(matches) >= 2 {
+		return matches[1]
+	}
+	if commitHashPattern.MatchString(version) {
+		return version
+	}
+	return ""
+}
+
+func isNixDirty(version string) bool {
+	return strings.HasSuffix(version, "-dirty")
+}
+
+func fetchCommitForTag(tag string) (string, error) {
+	url := fmt.Sprintf("%s/repos/%s/%s/commits/%s", githubAPI, repoOwner, repoName, tag)
+
+	resp, err := http.Get(url)
+	if err != nil {
+		return "", err
+	}
+	defer errutil.Close(resp.Body)
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("github api returned status %d", resp.StatusCode)
+	}
+
+	var commit githubCommit
+	if err := json.NewDecoder(resp.Body).Decode(&commit); err != nil {
+		return "", err
+	}
+
+	return commit.SHA, nil
+}
+
+func compareCommits(base, head string) (*githubCompare, error) {
+	url := fmt.Sprintf("%s/repos/%s/%s/compare/%s...%s", githubAPI, repoOwner, repoName, base, head)
+
+	resp, err := http.Get(url)
+	if err != nil {
+		return nil, err
+	}
+	defer errutil.Close(resp.Body)
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("github api returned status %d", resp.StatusCode)
+	}
+
+	var compare githubCompare
+	if err := json.NewDecoder(resp.Body).Decode(&compare); err != nil {
+		return nil, err
+	}
+
+	return &compare, nil
+}
+
+func printNixUpgradeInstructions() {
+	bold := color.New(color.Bold)
+	faint := color.New(color.Faint)
+	cmd := color.New(color.FgCyan)
+
+	errutil.Println(bold, "nix upgrade options:")
+	fmt.Println()
+
+	errutil.Print(faint, "  flake profile   ")
+	errutil.Printf(cmd, "nix profile install github:%s/%s\n", repoOwner, repoName)
+
+	errutil.Print(faint, "  flake update    ")
+	errutil.Println(cmd, "nix flake update snitch  (in your system/home-manager config)")
+
+	errutil.Print(faint, "  rebuild         ")
+	errutil.Println(cmd, "nixos-rebuild switch  or  home-manager switch")
+}
+

cmd/version.go

@@ -4,7 +4,10 @@ import (
 	"fmt"
 	"runtime"
 
+	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 var (
@@ -17,11 +20,25 @@ var versionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Show version/build info",
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Printf("snitch %s\n", Version)
-		fmt.Printf("  commit: %s\n", Commit)
-		fmt.Printf("  built:  %s\n", Date)
-		fmt.Printf("  go:     %s\n", runtime.Version())
-		fmt.Printf("  os:     %s/%s\n", runtime.GOOS, runtime.GOARCH)
+		bold := color.New(color.Bold)
+		cyan := color.New(color.FgCyan)
+		faint := color.New(color.Faint)
+
+		errutil.Print(bold, "snitch ")
+		errutil.Println(cyan, Version)
+		fmt.Println()
+
+		errutil.Print(faint, "  commit  ")
+		fmt.Println(Commit)
+
+		errutil.Print(faint, "  built   ")
+		fmt.Println(Date)
+
+		errutil.Print(faint, "  go      ")
+		fmt.Println(runtime.Version())
+
+		errutil.Print(faint, "  os      ")
+		fmt.Printf("%s/%s\n", runtime.GOOS, runtime.GOARCH)
 	},
 }
 

cmd/watch.go

@@ -7,7 +7,6 @@ import (
 	"log"
 	"os"
 	"os/signal"
-	"snitch/internal/collector"
 	"syscall"
 	"time"
 
@@ -36,17 +35,14 @@ Available filters:
 }
 
 func runWatchCommand(args []string) {
-	filters, err := parseFilters(args)
+	filters, err := BuildFilters(args)
 	if err != nil {
 		log.Fatalf("Error parsing filters: %v", err)
 	}
-	filters.IPv4 = ipv4
-	filters.IPv6 = ipv6
 
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	// Handle interrupts gracefully
 	sigChan := make(chan os.Signal, 1)
 	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
 	go func() {
@@ -63,18 +59,16 @@ func runWatchCommand(args []string) {
 		case <-ctx.Done():
 			return
 		case <-ticker.C:
-			connections, err := collector.GetConnections()
+			connections, err := FetchConnections(filters)
 			if err != nil {
 				log.Printf("Error getting connections: %v", err)
 				continue
 			}
 
-			filteredConnections := collector.FilterConnections(connections, filters)
-			
 			frame := map[string]interface{}{
 				"timestamp":   time.Now().Format(time.RFC3339Nano),
-				"connections": filteredConnections,
-				"count":       len(filteredConnections),
+				"connections": connections,
+				"count":       len(connections),
 			}
 
 			jsonOutput, err := json.Marshal(frame)
@@ -95,8 +89,11 @@ func runWatchCommand(args []string) {
 
 func init() {
 	rootCmd.AddCommand(watchCmd)
+
+	// watch-specific flags
 	watchCmd.Flags().DurationVarP(&watchInterval, "interval", "i", time.Second, "Refresh interval (e.g., 500ms, 2s)")
 	watchCmd.Flags().IntVarP(&watchCount, "count", "c", 0, "Number of frames to emit (0 = unlimited)")
-	watchCmd.Flags().BoolVarP(&ipv4, "ipv4", "4", false, "Only show IPv4 connections")
-	watchCmd.Flags().BoolVarP(&ipv6, "ipv6", "6", false, "Only show IPv6 connections")
+
+	// shared filter flags
+	addFilterFlags(watchCmd)
 }

demo/Dockerfile

@@ -0,0 +1,36 @@
+# syntax=docker/dockerfile:1
+
+# build stage - compile snitch
+FROM golang:1.25.0-bookworm AS builder
+WORKDIR /src
+COPY . .
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    go build -o snitch .
+
+# runtime stage - official vhs image has ffmpeg, chromium, ttyd pre-installed
+FROM ghcr.io/charmbracelet/vhs
+
+# install only lightweight tools for fake services
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update --allow-releaseinfo-change && apt-get install -y --no-install-recommends \
+    netcat-openbsd \
+    procps \
+    socat \
+    nginx-light
+
+WORKDIR /app
+
+# copy built binary from builder
+COPY --from=builder /src/snitch /app/snitch
+
+# copy demo files
+COPY demo/demo.tape /app/demo.tape
+COPY demo/entrypoint.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+ENV TERM=xterm-256color
+ENV COLORTERM=truecolor
+
+ENTRYPOINT ["/app/entrypoint.sh"]

demo/README.md

@@ -0,0 +1,45 @@
+# Demo Recording
+
+This directory contains files for recording the snitch demo GIF in a controlled Docker environment.
+
+## Files
+
+- `Dockerfile` - builds snitch and sets up fake network services
+- `demo.tape` - VHS script that records the demo
+- `entrypoint.sh` - starts fake services before recording
+
+## Recording the Demo
+
+From the project root:
+
+```bash
+# build the demo image
+docker build -f demo/Dockerfile -t snitch-demo .
+
+# run and output demo.gif to this directory
+docker run --rm -v $(pwd)/demo:/output snitch-demo
+```
+
+The resulting `demo.gif` will be saved to this directory.
+
+## Fake Services
+
+The container runs several fake services to demonstrate snitch:
+
+| Service | Port | Protocol |
+|---------|------|----------|
+| nginx   | 80   | TCP      |
+| web app | 8080 | TCP      |
+| node    | 3000 | TCP      |
+| postgres| 5432 | TCP      |
+| redis   | 6379 | TCP      |
+| mongo   | 27017| TCP      |
+| mdns    | 5353 | UDP      |
+| ssdp    | 1900 | UDP      |
+
+Plus some simulated established connections between services.
+
+## Customizing
+
+Edit `demo.tape` to change what's shown in the demo. See [VHS documentation](https://github.com/charmbracelet/vhs) for available commands.
+

demo/demo.tape

@@ -0,0 +1,94 @@
+Output demo.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set FontFamily "DejaVu Sans Mono"
+Set Width 1400
+Set Height 700
+Set Theme "Catppuccin Frappe"
+Set Padding 15
+Set Framerate 24
+Set TypingSpeed 30ms
+Set PlaybackSpeed 1.5
+
+# force color output
+Env TERM "xterm-256color"
+Env COLORTERM "truecolor"
+Env CLICOLOR "1"
+Env CLICOLOR_FORCE "1"
+Env FORCE_COLOR "1"
+
+# launch snitch
+Type "./snitch top"
+Enter
+Sleep 1s
+
+# navigate down through connections
+Down
+Sleep 200ms
+Down
+Sleep 200ms
+Down
+Sleep 200ms
+Down
+Sleep 200ms
+Down
+Sleep 600ms
+
+# open detail view for selected connection
+Enter
+Sleep 1.5s
+
+# close detail view
+Escape
+Sleep 500ms
+
+# search for nginx
+Type "/"
+Sleep 300ms
+Type "nginx"
+Sleep 600ms
+Enter
+Sleep 1.2s
+
+# clear search
+Type "/"
+Sleep 200ms
+Escape
+Sleep 500ms
+
+# filter: hide udp, show only tcp
+Type "u"
+Sleep 800ms
+
+# show only listening connections
+Type "e"
+Sleep 800ms
+Type "o"
+Sleep 800ms
+
+# reset to show all
+Type "a"
+Sleep 800ms
+
+# cycle through sort options
+Type "s"
+Sleep 500ms
+Type "s"
+Sleep 500ms
+
+# reverse sort order
+Type "S"
+Sleep 800ms
+
+# show help screen
+Type "?"
+Sleep 2s
+
+# close help
+Escape
+Sleep 500ms
+
+# quit
+Type "q"
+Sleep 200ms

demo/entrypoint.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# entrypoint script that creates fake network services for demo
+
+set -e
+
+echo "starting demo services..."
+
+# start nginx on port 80
+nginx &
+sleep 0.5
+
+# start some listening services with socat (stderr silenced)
+socat TCP-LISTEN:8080,fork,reuseaddr SYSTEM:"echo HTTP/1.1 200 OK" 2>/dev/null &
+socat TCP-LISTEN:3000,fork,reuseaddr SYSTEM:"echo hello" 2>/dev/null &
+socat TCP-LISTEN:5432,fork,reuseaddr SYSTEM:"echo postgres" 2>/dev/null &
+socat TCP-LISTEN:6379,fork,reuseaddr SYSTEM:"echo redis" 2>/dev/null &
+socat TCP-LISTEN:27017,fork,reuseaddr SYSTEM:"echo mongo" 2>/dev/null &
+
+# create some "established" connections by connecting to our own services
+sleep 0.5
+(while true; do echo "ping" | nc -q 1 localhost 8080 2>/dev/null; sleep 2; done) >/dev/null 2>&1 &
+(while true; do echo "ping" | nc -q 1 localhost 3000 2>/dev/null; sleep 2; done) >/dev/null 2>&1 &
+(while true; do curl -s http://localhost:80 >/dev/null 2>&1; sleep 3; done) &
+
+# udp listeners
+socat UDP-LISTEN:5353,fork,reuseaddr SYSTEM:"echo mdns" 2>/dev/null &
+socat UDP-LISTEN:1900,fork,reuseaddr SYSTEM:"echo ssdp" 2>/dev/null &
+
+sleep 1
+echo "services started, recording demo..."
+
+# run vhs to record the demo
+cd /app
+vhs demo.tape
+
+echo "demo recorded, copying output..."
+
+# output will be in /app/demo.gif
+cp /app/demo.gif /output/demo.gif 2>/dev/null || echo "output copied"
+
+echo "done!"

flake.lock

@@ -2,39 +2,23 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1756217674,
-        "narHash": "sha256-TH1SfSP523QI7kcPiNtMAEuwZR3Jdz0MCDXPs7TS8uo=",
+        "lastModified": 1766201043,
+        "narHash": "sha256-eplAP+rorKKd0gNjV3rA6+0WMzb1X1i16F5m5pASnjA=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "4e7667a90c167f7a81d906e5a75cba4ad8bee620",
+        "rev": "b3aad468604d3e488d627c0b43984eb60e75e782",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-25.05",
+        "ref": "nixos-25.11",
         "repo": "nixpkgs",
         "type": "github"
       }
     },
     "root": {
       "inputs": {
-        "nixpkgs": "nixpkgs",
-        "systems": "systems"
-      }
-    },
-    "systems": {
-      "locked": {
-        "lastModified": 1681028828,
-        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
-        "owner": "nix-systems",
-        "repo": "default",
-        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-systems",
-        "repo": "default",
-        "type": "github"
+        "nixpkgs": "nixpkgs"
       }
     }
   },

flake.nix

@@ -1,96 +1,137 @@
 {
-  description = "go 1.25.0 dev flake";
+  description = "snitch - a friendlier ss/netstat for humans";
 
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
-    systems.url = "github:nix-systems/default";
-  };
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
 
-  outputs = { self, nixpkgs, systems }:
+  outputs = { self, nixpkgs }:
     let
-      supportedSystems = import systems;
-      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
-    in
-    {
-      overlays.default = final: prev:
+      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+      eachSystem = nixpkgs.lib.genAttrs systems;
+
+      # go 1.25 binary derivation (required until nixpkgs ships it)
+      mkGo125 = pkgs:
         let
           version = "1.25.0";
-
-          platformInfo = {
-            "x86_64-linux" = { suffix = "linux-amd64"; sri = "sha256-KFKvDLIKExObNEiZLmm4aOUO0Pih5ZQO4d6eGaEjthM="; };
-            "aarch64-linux" = { suffix = "linux-arm64"; sri = "sha256-Bd511plKJ4NpmBXuVTvVqTJ9i3mZHeNuOLZoYngvVK4="; };
-            "i686-linux" = { suffix = "linux-386"; sri = "sha256-jGAt2dmbyUU7OZXSDOS684LMUIVZAKDs5d6ZKd9KmTo="; };
-            "armv6l-linux" = { suffix = "linux-armv6l"; sri = "sha256-paj4GY/PAOHkhbjs757gIHeL8ypAik6Iczcb/ORYzQk="; };
-
-            "x86_64-darwin" = { suffix = "darwin-amd64"; sri = "sha256-W9YOgjA3BiwjB8cegRGAmGURZxTW9rQQWXz1B139gO8="; };
-            "aarch64-darwin" = { suffix = "darwin-arm64"; sri = "sha256-VEkyhEFW2Bcveij3fyrJwVojBGaYtiQ/YzsKCwDAdJw="; };
-          };
-
-          hostSystem = prev.stdenv.hostPlatform.system;
-
-          chosen =
-            if prev.lib.hasAttr hostSystem platformInfo then platformInfo.${hostSystem}
-            else
-              throw ''
-                unsupported system: ${hostSystem}
-                add a mapping for your platform using the upstream tarball + sri sha256
-              '';
+          platform = {
+            "x86_64-linux" = { suffix = "linux-amd64"; hash = "sha256-KFKvDLIKExObNEiZLmm4aOUO0Pih5ZQO4d6eGaEjthM="; GOOS = "linux"; GOARCH = "amd64"; };
+            "aarch64-linux" = { suffix = "linux-arm64"; hash = "sha256-Bd511plKJ4NpmBXuVTvVqTJ9i3mZHeNuOLZoYngvVK4="; GOOS = "linux"; GOARCH = "arm64"; };
+            "x86_64-darwin" = { suffix = "darwin-amd64"; hash = "sha256-W9YOgjA3BiwjB8cegRGAmGURZxTW9rQQWXz1B139gO8="; GOOS = "darwin"; GOARCH = "amd64"; };
+            "aarch64-darwin" = { suffix = "darwin-arm64"; hash = "sha256-VEkyhEFW2Bcveij3fyrJwVojBGaYtiQ/YzsKCwDAdJw="; GOOS = "darwin"; GOARCH = "arm64"; };
+          }.${pkgs.stdenv.hostPlatform.system} or (throw "unsupported system: ${pkgs.stdenv.hostPlatform.system}");
         in
-        {
-          go_1_25_bin = prev.stdenvNoCC.mkDerivation {
+        pkgs.stdenv.mkDerivation {
           pname = "go";
-            version = version;
-
-            src = prev.fetchurl {
-              url = "https://go.dev/dl/go${version}.${chosen.suffix}.tar.gz";
-              hash = chosen.sri;
+          inherit version;
+          src = pkgs.fetchurl {
+            url = "https://go.dev/dl/go${version}.${platform.suffix}.tar.gz";
+            inherit (platform) hash;
           };
-
           dontBuild = true;
-
-            installPhase = ''
-              runHook preInstall
-              mkdir -p "$out"/{bin,share}
-              tar -C "$TMPDIR" -xzf "$src"
-              cp -a "$TMPDIR/go" "$out/share/go"
-              ln -s "$out/share/go/bin/go"    "$out/bin/go"
-              ln -s "$out/share/go/bin/gofmt" "$out/bin/gofmt"
-              runHook postInstall
-            '';
-
           dontPatchELF = true;
           dontStrip = true;
-
-            meta = with prev.lib; {
-              description = "go compiler and tools v${version}";
-              homepage = "https://go.dev/dl/";
-              license = licenses.bsd3;
-              platforms = [ hostSystem ];
-            };
+          installPhase = ''
+            runHook preInstall
+            mkdir -p $out/{bin,share/go}
+            tar -xzf $src --strip-components=1 -C $out/share/go
+            ln -s $out/share/go/bin/go $out/bin/go
+            ln -s $out/share/go/bin/gofmt $out/bin/gofmt
+            runHook postInstall
+          '';
+          passthru = {
+            inherit (platform) GOOS GOARCH;
           };
         };
 
-      packages = forAllSystems (system:
-        let pkgs = import nixpkgs { inherit system; overlays = [ self.overlays.default ]; };
-        in {
-          default = pkgs.go_1_25_bin;
-          go_1_25_bin = pkgs.go_1_25_bin;
+      pkgsFor = system: import nixpkgs { inherit system; };
+
+      mkSnitch = pkgs:
+        let
+          rev = self.shortRev or self.dirtyShortRev or "unknown";
+          version = "nix-${rev}";
+          isDarwin = pkgs.stdenv.isDarwin;
+          go = mkGo125 pkgs;
+          buildGoModule = pkgs.buildGoModule.override { inherit go; };
+        in
+        buildGoModule {
+          pname = "snitch";
+          inherit version;
+          src = self;
+          vendorHash = "sha256-fX3wOqeOgjH7AuWGxPQxJ+wbhp240CW8tiF4rVUUDzk=";
+          # darwin requires cgo for libproc, linux uses pure go with /proc
+          env.CGO_ENABLED = if isDarwin then "1" else "0";
+          env.GOTOOLCHAIN = "local";
+          # darwin: use macOS 15 SDK for SecTrustCopyCertificateChain (Go 1.25 crypto/x509)
+          buildInputs = pkgs.lib.optionals isDarwin [ pkgs.apple-sdk_15 ];
+          ldflags = [
+            "-s"
+            "-w"
+            "-X snitch/cmd.Version=${version}"
+            "-X snitch/cmd.Commit=${rev}"
+            "-X snitch/cmd.Date=${self.lastModifiedDate or "unknown"}"
+          ];
+          meta = {
+            description = "a friendlier ss/netstat for humans";
+            homepage = "https://github.com/karol-broda/snitch";
+            license = pkgs.lib.licenses.mit;
+            platforms = pkgs.lib.platforms.linux ++ pkgs.lib.platforms.darwin;
+            mainProgram = "snitch";
+          };
+        };
+    in
+    {
+      packages = eachSystem (system:
+        let pkgs = pkgsFor system; in
+        {
+          default = mkSnitch pkgs;
+          snitch = mkSnitch pkgs;
         }
       );
 
-      devShells = forAllSystems (system:
-        let pkgs = import nixpkgs { inherit system; overlays = [ self.overlays.default ]; };
-        in {
+      devShells = eachSystem (system:
+        let
+          pkgs = pkgsFor system;
+          go = mkGo125 pkgs;
+        in
+        {
           default = pkgs.mkShell {
-            packages = [ pkgs.go_1_25_bin pkgs.git ];
-
-            GOTOOLCHAIN = "local";
-
+            packages = [ go pkgs.git pkgs.vhs ];
+            env.GOTOOLCHAIN = "local";
             shellHook = ''
               echo "go toolchain: $(go version)"
             '';
           };
         }
       );
+
+      overlays.default = final: _prev: {
+        snitch = mkSnitch final;
+      };
+
+      homeManagerModules.default = import ./nix/hm-module.nix;
+      homeManagerModules.snitch = self.homeManagerModules.default;
+
+      # alias for flake-parts compatibility
+      homeModules.default = self.homeManagerModules.default;
+      homeModules.snitch = self.homeManagerModules.default;
+
+      checks = eachSystem (system:
+        let
+          pkgs = import nixpkgs {
+            inherit system;
+            overlays = [ self.overlays.default ];
+          };
+        in
+        {
+          # home manager module tests
+          hm-module = import ./nix/tests/hm-module-test.nix {
+            inherit pkgs;
+            lib = pkgs.lib;
+            hmModule = self.homeManagerModules.default;
+          };
+
+          # package builds correctly
+          package = self.packages.${system}.default;
+        }
+      );
     };
 }

go.mod

@@ -1,20 +1,26 @@
-module snitch
+module github.com/karol-broda/snitch
 
-go 1.24.0
+go 1.25.0
 
 require (
 	github.com/charmbracelet/bubbletea v1.3.6
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/charmbracelet/x/exp/teatest v0.0.0-20251215102626-e0db08df7383
 	github.com/fatih/color v1.18.0
+	github.com/mattn/go-runewidth v0.0.16
 	github.com/spf13/cobra v1.9.1
+	github.com/spf13/viper v1.19.0
 	github.com/tidwall/pretty v1.2.1
+	golang.org/x/term v0.38.0
 )
 
 require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
-	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
-	github.com/charmbracelet/x/ansi v0.9.3 // indirect
+	github.com/aymanbagabas/go-udiff v0.3.1 // indirect
+	github.com/charmbracelet/colorprofile v0.3.2 // indirect
+	github.com/charmbracelet/x/ansi v0.10.1 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
+	github.com/charmbracelet/x/exp/golden v0.0.0-20240806155701-69247e0abc2a // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
@@ -25,7 +31,6 @@ require (
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
-	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
@@ -38,16 +43,14 @@ require (
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
-	github.com/spf13/viper v1.19.0 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
-	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
-	golang.org/x/sync v0.15.0 // indirect
+	golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect
+	golang.org/x/sync v0.16.0 // indirect
 	golang.org/x/sys v0.39.0 // indirect
-	golang.org/x/term v0.38.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/text v0.28.0 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,30 +1,46 @@
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/aymanbagabas/go-udiff v0.3.1 h1:LV+qyBQ2pqe0u42ZsUEtPiCaUoqgA9gYRDs3vj1nolY=
+github.com/aymanbagabas/go-udiff v0.3.1/go.mod h1:G0fsKmG+P6ylD0r6N/KgQD/nWzgfnl8ZBcNLgcbrw8E=
 github.com/charmbracelet/bubbletea v1.3.6 h1:VkHIxPJQeDt0aFJIsVxw8BQdh/F/L2KKZGsK6et5taU=
 github.com/charmbracelet/bubbletea v1.3.6/go.mod h1:oQD9VCRQFF8KplacJLo28/jofOI2ToOfGYeFgBBxHOc=
-github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
-github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc/go.mod h1:X4/0JoqgTIPSFcRA/P6INZzIuyqdFY5rm8tb41s9okk=
+github.com/charmbracelet/colorprofile v0.3.2 h1:9J27WdztfJQVAQKX2WOlSSRB+5gaKqqITmrvb1uTIiI=
+github.com/charmbracelet/colorprofile v0.3.2/go.mod h1:mTD5XzNeWHj8oqHb+S1bssQb7vIHbepiebQ2kPKVKbI=
 github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
 github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
-github.com/charmbracelet/x/ansi v0.9.3 h1:BXt5DHS/MKF+LjuK4huWrC6NCvHtexww7dMayh6GXd0=
-github.com/charmbracelet/x/ansi v0.9.3/go.mod h1:3RQDQ6lDnROptfpWuUVIUG64bD2g2BgntdxH0Ya5TeE=
+github.com/charmbracelet/x/ansi v0.10.1 h1:rL3Koar5XvX0pHGfovN03f5cxLbCF2YvLeyz7D2jVDQ=
+github.com/charmbracelet/x/ansi v0.10.1/go.mod h1:3RQDQ6lDnROptfpWuUVIUG64bD2g2BgntdxH0Ya5TeE=
 github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0GVL4jeHEwG5YOXDmi86oYw2yuYUGqz6a8sLwg0X8=
 github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
+github.com/charmbracelet/x/exp/golden v0.0.0-20240806155701-69247e0abc2a h1:G99klV19u0QnhiizODirwVksQB91TJKV/UaTnACcG30=
+github.com/charmbracelet/x/exp/golden v0.0.0-20240806155701-69247e0abc2a/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
+github.com/charmbracelet/x/exp/teatest v0.0.0-20251215102626-e0db08df7383 h1:nCaK/2JwS/z7GoS3cIQlNYIC6MMzWLC8zkT6JkGvkn0=
+github.com/charmbracelet/x/exp/teatest v0.0.0-20251215102626-e0db08df7383/go.mod h1:aPVjFrBwbJgj5Qz1F0IXsnbcOVJcMKgu1ySUfTAxh7k=
 github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
 github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
 github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
 github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
 github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
@@ -49,9 +65,13 @@ github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3
 github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
 github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
 github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
@@ -77,6 +97,7 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
@@ -88,22 +109,22 @@ go.uber.org/atomic v1.9.0 h1:ECmE8Bn/WFTYwEW/bpKD3M8VtR/zQVbavAoalC1PYyE=
 go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
 go.uber.org/multierr v1.9.0 h1:7fIwc/ZtS0q++VgcfqFDxSBZVv/Xo49/SYnDFupUwlI=
 go.uber.org/multierr v1.9.0/go.mod h1:X2jQV1h+kxSjClGpnseKVIxpmcjrj7MNnI0bnlfKTVQ=
-golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g=
-golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
-golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8=
-golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
+golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw=
+golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
-golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
 golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/term v0.38.0 h1:PQ5pkm/rLO6HnxFR7N2lJHOZX6Kez5Y1gDSJla6jo7Q=
 golang.org/x/term v0.38.0/go.mod h1:bSEAKrOT1W+VSu9TSCMtoGEOUcKxOKgl3LE5QEF/xVg=
-golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
-golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
+golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
 gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

install.sh

@@ -0,0 +1,113 @@
+#!/bin/sh
+set -e
+
+REPO="karol-broda/snitch"
+BINARY_NAME="snitch"
+
+# allow override via environment
+INSTALL_DIR="${INSTALL_DIR:-}"
+KEEP_QUARANTINE="${KEEP_QUARANTINE:-}"
+
+detect_install_dir() {
+    if [ -n "$INSTALL_DIR" ]; then
+        echo "$INSTALL_DIR"
+        return
+    fi
+
+    # prefer user-local directory if it exists and is in PATH
+    if [ -d "$HOME/.local/bin" ] && echo "$PATH" | grep -q "$HOME/.local/bin"; then
+        echo "$HOME/.local/bin"
+        return
+    fi
+
+    # fallback to /usr/local/bin
+    echo "/usr/local/bin"
+}
+
+detect_os() {
+    os=$(uname -s | tr '[:upper:]' '[:lower:]')
+    case "$os" in
+        darwin) echo "darwin" ;;
+        linux) echo "linux" ;;
+        *)
+            echo "error: unsupported operating system: $os" >&2
+            exit 1
+            ;;
+    esac
+}
+
+detect_arch() {
+    arch=$(uname -m)
+    case "$arch" in
+        x86_64|amd64) echo "amd64" ;;
+        aarch64|arm64) echo "arm64" ;;
+        armv7l) echo "armv7" ;;
+        *)
+            echo "error: unsupported architecture: $arch" >&2
+            exit 1
+            ;;
+    esac
+}
+
+fetch_latest_version() {
+    version=$(curl -sL "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name"' | head -1 | cut -d'"' -f4)
+    if [ -z "$version" ]; then
+        echo "error: failed to fetch latest version" >&2
+        exit 1
+    fi
+    echo "$version"
+}
+
+main() {
+    os=$(detect_os)
+    arch=$(detect_arch)
+    install_dir=$(detect_install_dir)
+    version=$(fetch_latest_version)
+    version_no_v="${version#v}"
+
+    archive_name="${BINARY_NAME}_${version_no_v}_${os}_${arch}.tar.gz"
+    download_url="https://github.com/${REPO}/releases/download/${version}/${archive_name}"
+
+    echo "installing ${BINARY_NAME} ${version} for ${os}/${arch}..."
+
+    tmp_dir=$(mktemp -d)
+    trap 'rm -rf "$tmp_dir"' EXIT
+
+    echo "downloading ${download_url}..."
+    if ! curl -sL --fail "$download_url" -o "${tmp_dir}/${archive_name}"; then
+        echo "error: failed to download ${download_url}" >&2
+        exit 1
+    fi
+
+    echo "extracting..."
+    tar -xzf "${tmp_dir}/${archive_name}" -C "$tmp_dir"
+
+    if [ ! -f "${tmp_dir}/${BINARY_NAME}" ]; then
+        echo "error: binary not found in archive" >&2
+        exit 1
+    fi
+
+    # remove macos quarantine attribute unless disabled
+    if [ "$os" = "darwin" ] && [ -z "$KEEP_QUARANTINE" ]; then
+        if xattr -d com.apple.quarantine "${tmp_dir}/${BINARY_NAME}" 2>/dev/null; then
+            echo "warning: removed macOS quarantine attribute from binary"
+        fi
+    fi
+
+    # install binary
+    if [ -w "$install_dir" ]; then
+        mv "${tmp_dir}/${BINARY_NAME}" "${install_dir}/${BINARY_NAME}"
+    else
+        echo "elevated permissions required to install to ${install_dir}"
+        sudo mv "${tmp_dir}/${BINARY_NAME}" "${install_dir}/${BINARY_NAME}"
+    fi
+
+    chmod +x "${install_dir}/${BINARY_NAME}"
+
+    echo "installed ${BINARY_NAME} to ${install_dir}/${BINARY_NAME}"
+    echo ""
+    echo "run '${BINARY_NAME} --help' to get started"
+}
+
+main
+

internal/collector/collector.go

@@ -1,17 +1,8 @@
 package collector
 
 import (
-	"bufio"
-	"bytes"
-	"fmt"
 	"net"
-	"os"
-	"os/user"
-	"path/filepath"
-	"runtime"
-	"strconv"
 	"strings"
-	"time"
 )
 
 // Collector interface defines methods for collecting connection data
@@ -19,9 +10,6 @@ type Collector interface {
 	GetConnections() ([]Connection, error)
 }
 
-// DefaultCollector implements the Collector interface using /proc
-type DefaultCollector struct{}
-
 // Global collector instance (can be overridden for testing)
 var globalCollector Collector = &DefaultCollector{}
 
@@ -40,64 +28,6 @@ func GetConnections() ([]Connection, error) {
 	return globalCollector.GetConnections()
 }
 
-// GetConnections fetches all network connections by parsing /proc files.
-func (dc *DefaultCollector) GetConnections() ([]Connection, error) {
-	if runtime.GOOS != "linux" {
-		return nil, fmt.Errorf("proc-based collector only supports Linux")
-	}
-
-	// Build map of inode -> process info by scanning /proc
-	inodeMap, err := buildInodeToProcessMap()
-	if err != nil {
-		return nil, fmt.Errorf("failed to build inode map: %w", err)
-	}
-
-	var connections []Connection
-
-	// Parse TCP connections
-	tcpConns, err := parseProcNet("/proc/net/tcp", "tcp", 4, inodeMap)
-	if err == nil {
-		connections = append(connections, tcpConns...)
-	}
-
-	tcpConns6, err := parseProcNet("/proc/net/tcp6", "tcp6", 6, inodeMap)
-	if err == nil {
-		connections = append(connections, tcpConns6...)
-	}
-
-	// Parse UDP connections
-	udpConns, err := parseProcNet("/proc/net/udp", "udp", 4, inodeMap)
-	if err == nil {
-		connections = append(connections, udpConns...)
-	}
-
-	udpConns6, err := parseProcNet("/proc/net/udp6", "udp6", 6, inodeMap)
-	if err == nil {
-		connections = append(connections, udpConns6...)
-	}
-
-	return connections, nil
-}
-
-// GetAllConnections returns both network and Unix domain socket connections
-func GetAllConnections() ([]Connection, error) {
-	// Get network connections
-	networkConns, err := GetConnections()
-	if err != nil {
-		return nil, err
-	}
-
-	// Get Unix sockets (only on Linux)
-	if runtime.GOOS == "linux" {
-		unixConns, err := GetUnixSockets()
-		if err == nil {
-			networkConns = append(networkConns, unixConns...)
-		}
-	}
-
-	return networkConns, nil
-}
-
 func FilterConnections(conns []Connection, filters FilterOptions) []Connection {
 	if filters.IsEmpty() {
 		return conns
@@ -112,395 +42,60 @@ func FilterConnections(conns []Connection, filters FilterOptions) []Connection {
 	return filtered
 }
 
-// processInfo holds information about a process
-type processInfo struct {
-	pid     int
-	command string
-	uid     int
-	user    string
-}
-
-// buildInodeToProcessMap scans /proc to map socket inodes to processes
-func buildInodeToProcessMap() (map[int64]*processInfo, error) {
-	inodeMap := make(map[int64]*processInfo)
-
-	procDir, err := os.Open("/proc")
-	if err != nil {
-		return nil, err
-	}
-	defer procDir.Close()
-
-	entries, err := procDir.Readdir(-1)
-	if err != nil {
-		return nil, err
-	}
-
-	for _, entry := range entries {
-		if !entry.IsDir() {
-			continue
-		}
-
-		// check if directory name is a number (pid)
-		pidStr := entry.Name()
-		pid, err := strconv.Atoi(pidStr)
-		if err != nil {
-			continue
-		}
-
-		// get process info
-		procInfo, err := getProcessInfo(pid)
-		if err != nil {
-			continue
-		}
-
-		// scan /proc/[pid]/fd/ for socket file descriptors
-		fdDir := filepath.Join("/proc", pidStr, "fd")
-		fdEntries, err := os.ReadDir(fdDir)
-		if err != nil {
-			continue
-		}
-
-		for _, fdEntry := range fdEntries {
-			fdPath := filepath.Join(fdDir, fdEntry.Name())
-			link, err := os.Readlink(fdPath)
-			if err != nil {
-				continue
-			}
-
-			// socket inodes look like: socket:[12345]
-			if strings.HasPrefix(link, "socket:[") && strings.HasSuffix(link, "]") {
-				inodeStr := link[8 : len(link)-1]
-				inode, err := strconv.ParseInt(inodeStr, 10, 64)
-				if err != nil {
-					continue
-				}
-				inodeMap[inode] = procInfo
-			}
-		}
-	}
-
-	return inodeMap, nil
-}
-
-// getProcessInfo reads process information from /proc/[pid]/
-func getProcessInfo(pid int) (*processInfo, error) {
-	info := &processInfo{pid: pid}
-
-	// prefer /proc/[pid]/comm as it's always just the command name
-	commPath := filepath.Join("/proc", strconv.Itoa(pid), "comm")
-	commData, err := os.ReadFile(commPath)
-	if err == nil && len(commData) > 0 {
-		info.command = strings.TrimSpace(string(commData))
-	}
-
-	// if comm is not available, try cmdline
-	if info.command == "" {
-		cmdlinePath := filepath.Join("/proc", strconv.Itoa(pid), "cmdline")
-		cmdlineData, err := os.ReadFile(cmdlinePath)
-		if err != nil {
-			return nil, err
-		}
-
-		// cmdline is null-separated, take first part
-		if len(cmdlineData) > 0 {
-			parts := bytes.Split(cmdlineData, []byte{0})
-			if len(parts) > 0 && len(parts[0]) > 0 {
-				fullPath := string(parts[0])
-				// extract basename from full path
-				baseName := filepath.Base(fullPath)
-				// if basename contains spaces (single-string cmdline), take first word
-				if strings.Contains(baseName, " ") {
-					baseName = strings.Fields(baseName)[0]
-				}
-				info.command = baseName
-			}
-		}
-	}
-
-	// read UID from /proc/[pid]/status
-	statusPath := filepath.Join("/proc", strconv.Itoa(pid), "status")
-	statusFile, err := os.Open(statusPath)
-	if err != nil {
-		return info, nil
-	}
-	defer statusFile.Close()
-
-	scanner := bufio.NewScanner(statusFile)
-	for scanner.Scan() {
-		line := scanner.Text()
-		if strings.HasPrefix(line, "Uid:") {
-			fields := strings.Fields(line)
-			if len(fields) >= 2 {
-				uid, err := strconv.Atoi(fields[1])
-				if err == nil {
-					info.uid = uid
-					// get username from uid
-					u, err := user.LookupId(strconv.Itoa(uid))
-					if err == nil {
-						info.user = u.Username
-					} else {
-						info.user = strconv.Itoa(uid)
-					}
-				}
-			}
-			break
-		}
-	}
-
-	return info, nil
-}
-
-// parseProcNet parses a /proc/net/tcp or /proc/net/udp file
-func parseProcNet(path, proto string, ipVersion int, inodeMap map[int64]*processInfo) ([]Connection, error) {
-	file, err := os.Open(path)
-	if err != nil {
-		return nil, err
-	}
-	defer file.Close()
-
-	var connections []Connection
-	scanner := bufio.NewScanner(file)
-
-	// skip header
-	scanner.Scan()
-
-	for scanner.Scan() {
-		line := strings.TrimSpace(scanner.Text())
-		if line == "" {
-			continue
-		}
-
-		fields := strings.Fields(line)
-		if len(fields) < 10 {
-			continue
-		}
-
-		// parse local address and port
-		localAddr, localPort, err := parseHexAddr(fields[1])
-		if err != nil {
-			continue
-		}
-
-		// parse remote address and port
-		remoteAddr, remotePort, err := parseHexAddr(fields[2])
-		if err != nil {
-			continue
-		}
-
-		// parse state (field 3)
-		stateHex := fields[3]
-		state := parseState(stateHex, proto)
-
-		// parse inode (field 9)
-		inode, _ := strconv.ParseInt(fields[9], 10, 64)
-
-		conn := Connection{
-			TS:        time.Now(),
-			Proto:     proto,
-			IPVersion: fmt.Sprintf("IPv%d", ipVersion),
-			State:     state,
-			Laddr:     localAddr,
-			Lport:     localPort,
-			Raddr:     remoteAddr,
-			Rport:     remotePort,
-			Inode:     inode,
-		}
-
-		// add process info if available
-		if procInfo, exists := inodeMap[inode]; exists {
-			conn.PID = procInfo.pid
-			conn.Process = procInfo.command
-			conn.UID = procInfo.uid
-			conn.User = procInfo.user
-		}
-
-		// determine interface
-		conn.Interface = guessNetworkInterface(localAddr, nil)
-
-		connections = append(connections, conn)
-	}
-
-	return connections, scanner.Err()
-}
-
-// parseState converts hex state value to string
-func parseState(hexState, proto string) string {
-	state, err := strconv.ParseInt(hexState, 16, 32)
-	if err != nil {
-		return ""
-	}
-
-	// TCP states
-	tcpStates := map[int64]string{
-		0x01: "ESTABLISHED",
-		0x02: "SYN_SENT",
-		0x03: "SYN_RECV",
-		0x04: "FIN_WAIT1",
-		0x05: "FIN_WAIT2",
-		0x06: "TIME_WAIT",
-		0x07: "CLOSE",
-		0x08: "CLOSE_WAIT",
-		0x09: "LAST_ACK",
-		0x0A: "LISTEN",
-		0x0B: "CLOSING",
-	}
-
-	if strings.HasPrefix(proto, "tcp") {
-		if s, exists := tcpStates[state]; exists {
-			return s
-		}
-	} else {
-		// UDP doesn't have states in the same way
-		if state == 0x07 {
-			return "CLOSE"
-		}
-		return ""
-	}
-
-	return ""
-}
-
-// parseHexAddr parses hex-encoded address:port from /proc/net files
-func parseHexAddr(hexAddr string) (string, int, error) {
-	parts := strings.Split(hexAddr, ":")
-	if len(parts) != 2 {
-		return "", 0, fmt.Errorf("invalid address format")
-	}
-
-	hexIP := parts[0]
-
-	// parse hex port
-	port, err := strconv.ParseInt(parts[1], 16, 32)
-	if err != nil {
-		return "", 0, err
-	}
-
-	if len(hexIP) == 8 {
-		// IPv4 (stored in little-endian)
-		ip1, _ := strconv.ParseInt(hexIP[6:8], 16, 32)
-		ip2, _ := strconv.ParseInt(hexIP[4:6], 16, 32)
-		ip3, _ := strconv.ParseInt(hexIP[2:4], 16, 32)
-		ip4, _ := strconv.ParseInt(hexIP[0:2], 16, 32)
-		addr := fmt.Sprintf("%d.%d.%d.%d", ip1, ip2, ip3, ip4)
-
-		// handle wildcard address
-		if addr == "0.0.0.0" {
-			addr = "*"
-		}
-
-		return addr, int(port), nil
-	} else if len(hexIP) == 32 {
-		// IPv6 (stored in little-endian per 32-bit word)
-		var ipv6Parts []string
-		for i := 0; i < 32; i += 8 {
-			word := hexIP[i : i+8]
-			// reverse byte order within each 32-bit word
-			p1 := word[6:8] + word[4:6] + word[2:4] + word[0:2]
-			ipv6Parts = append(ipv6Parts, p1)
-		}
-
-		// convert to standard IPv6 notation
-		fullAddr := strings.Join(ipv6Parts, "")
-		var formatted []string
-		for i := 0; i < len(fullAddr); i += 4 {
-			formatted = append(formatted, fullAddr[i:i+4])
-		}
-		addr := strings.Join(formatted, ":")
-
-		// simplify IPv6 address
-		addr = simplifyIPv6(addr)
-
-		// handle wildcard address
-		if addr == "::" || addr == "0:0:0:0:0:0:0:0" {
-			addr = "*"
-		}
-
-		return addr, int(port), nil
-	}
-
-	return "", 0, fmt.Errorf("unsupported address format")
-}
-
-// simplifyIPv6 simplifies IPv6 address notation
-func simplifyIPv6(addr string) string {
-	// remove leading zeros from each group
-	parts := strings.Split(addr, ":")
-	for i, part := range parts {
-		// convert to int and back to remove leading zeros
-		val, err := strconv.ParseInt(part, 16, 64)
-		if err == nil {
-			parts[i] = strconv.FormatInt(val, 16)
-		}
-	}
-	return strings.Join(parts, ":")
-}
-
-func guessNetworkInterface(addr string, interfaces map[string]string) string {
-	// Simple heuristic - try to match common interface patterns
+func guessNetworkInterface(addr string) string {
 	if addr == "127.0.0.1" || addr == "::1" {
 		return "lo"
 	}
 
-	// Check if it's a private network address
 	ip := net.ParseIP(addr)
-	if ip != nil {
+	if ip == nil {
+		return ""
+	}
+
 	if ip.IsLoopback() {
 		return "lo"
 	}
-		// More sophisticated interface detection would require routing table analysis
-		// For now, return a placeholder
-		if ip.To4() != nil {
-			return "eth0" // Common default for IPv4
-		} else {
-			return "eth0" // Common default for IPv6
-		}
-	}
 
+	// default interface name varies by OS but we return a generic value
+	// actual interface detection would require routing table analysis
 	return ""
 }
 
-// Add Unix socket support
-func GetUnixSockets() ([]Connection, error) {
-	connections := []Connection{}
-
-	// Parse /proc/net/unix for Unix domain sockets
-	file, err := os.Open("/proc/net/unix")
-	if err != nil {
-		return connections, nil // silently fail on non-Linux systems
+func simplifyIPv6(addr string) string {
+	parts := strings.Split(addr, ":")
+	for i, part := range parts {
+		// parse as hex then format back to remove leading zeros
+		var val int64
+		for _, c := range part {
+			val = val*16 + int64(hexCharToInt(c))
 		}
-	defer file.Close()
-
-	scanner := bufio.NewScanner(file)
-	// Skip header
-	scanner.Scan()
-
-	for scanner.Scan() {
-		line := strings.TrimSpace(scanner.Text())
-		fields := strings.Fields(line)
-		if len(fields) < 7 {
-			continue
+		parts[i] = formatHex(val)
 	}
-
-		// Parse Unix socket information
-		inode, _ := strconv.ParseInt(fields[6], 10, 64)
-		path := ""
-		if len(fields) > 7 {
-			path = fields[7]
-		}
-
-		conn := Connection{
-			TS:        time.Now(),
-			Proto:     "unix",
-			Laddr:     path,
-			Raddr:     "",
-			State:     "CONNECTED", // Simplified
-			Inode:     inode,
-			Interface: "unix",
-		}
-
-		connections = append(connections, conn)
-	}
-
-	return connections, nil
+	return strings.Join(parts, ":")
 }
 
+func hexCharToInt(c rune) int {
+	switch {
+	case c >= '0' && c <= '9':
+		return int(c - '0')
+	case c >= 'a' && c <= 'f':
+		return int(c - 'a' + 10)
+	case c >= 'A' && c <= 'F':
+		return int(c - 'A' + 10)
+	default:
+		return 0
+	}
+}
+
+func formatHex(val int64) string {
+	if val == 0 {
+		return "0"
+	}
+	const hexDigits = "0123456789abcdef"
+	var result []byte
+	for val > 0 {
+		result = append([]byte{hexDigits[val%16]}, result...)
+		val /= 16
+	}
+	return string(result)
+}

internal/collector/collector_darwin.go

@@ -0,0 +1,338 @@
+//go:build darwin
+
+package collector
+
+/*
+#include <libproc.h>
+#include <sys/proc_info.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <netinet/tcp_fsm.h>
+#include <arpa/inet.h>
+#include <pwd.h>
+#include <stdlib.h>
+#include <string.h>
+
+// get process name by pid
+static int get_proc_name(int pid, char *name, int namelen) {
+    return proc_name(pid, name, namelen);
+}
+
+// get uid for a process
+static int get_proc_uid(int pid) {
+    struct proc_bsdinfo info;
+    int ret = proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, &info, sizeof(info));
+    if (ret <= 0) {
+        return -1;
+    }
+    return info.pbi_uid;
+}
+
+// get username from uid
+static const char* get_username(int uid) {
+    struct passwd *pw = getpwuid(uid);
+    if (pw == NULL) {
+        return NULL;
+    }
+    return pw->pw_name;
+}
+
+// socket info extraction - handles the union properly in C
+typedef struct {
+    int family;
+    int sock_type;
+    int protocol;
+    int state;
+    uint32_t laddr4;
+    uint32_t raddr4;
+    uint8_t laddr6[16];
+    uint8_t raddr6[16];
+    int lport;
+    int rport;
+} socket_info_t;
+
+static int get_socket_info(int pid, int fd, socket_info_t *info) {
+    struct socket_fdinfo si;
+    int ret = proc_pidfdinfo(pid, fd, PROC_PIDFDSOCKETINFO, &si, sizeof(si));
+    if (ret <= 0) {
+        return -1;
+    }
+
+    info->family = si.psi.soi_family;
+    info->sock_type = si.psi.soi_type;
+    info->protocol = si.psi.soi_protocol;
+
+    if (info->family == AF_INET) {
+        if (info->sock_type == SOCK_STREAM) {
+            // TCP
+            info->state = si.psi.soi_proto.pri_tcp.tcpsi_state;
+            info->laddr4 = si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_laddr.ina_46.i46a_addr4.s_addr;
+            info->raddr4 = si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_faddr.ina_46.i46a_addr4.s_addr;
+            info->lport = ntohs(si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_lport);
+            info->rport = ntohs(si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_fport);
+        } else if (info->sock_type == SOCK_DGRAM) {
+            // UDP
+            info->state = 0;
+            info->laddr4 = si.psi.soi_proto.pri_in.insi_laddr.ina_46.i46a_addr4.s_addr;
+            info->raddr4 = si.psi.soi_proto.pri_in.insi_faddr.ina_46.i46a_addr4.s_addr;
+            info->lport = ntohs(si.psi.soi_proto.pri_in.insi_lport);
+            info->rport = ntohs(si.psi.soi_proto.pri_in.insi_fport);
+        }
+    } else if (info->family == AF_INET6) {
+        if (info->sock_type == SOCK_STREAM) {
+            // TCP6
+            info->state = si.psi.soi_proto.pri_tcp.tcpsi_state;
+            memcpy(info->laddr6, &si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_laddr.ina_6, 16);
+            memcpy(info->raddr6, &si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_faddr.ina_6, 16);
+            info->lport = ntohs(si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_lport);
+            info->rport = ntohs(si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_fport);
+        } else if (info->sock_type == SOCK_DGRAM) {
+            // UDP6
+            info->state = 0;
+            memcpy(info->laddr6, &si.psi.soi_proto.pri_in.insi_laddr.ina_6, 16);
+            memcpy(info->raddr6, &si.psi.soi_proto.pri_in.insi_faddr.ina_6, 16);
+            info->lport = ntohs(si.psi.soi_proto.pri_in.insi_lport);
+            info->rport = ntohs(si.psi.soi_proto.pri_in.insi_fport);
+        }
+    }
+
+    return 0;
+}
+*/
+import "C"
+
+import (
+	"fmt"
+	"net"
+	"strconv"
+	"time"
+	"unsafe"
+)
+
+// DefaultCollector implements the Collector interface using libproc on macOS
+type DefaultCollector struct{}
+
+// GetConnections fetches all network connections using libproc
+func (dc *DefaultCollector) GetConnections() ([]Connection, error) {
+	pids, err := listAllPids()
+	if err != nil {
+		return nil, fmt.Errorf("failed to list pids: %w", err)
+	}
+
+	var connections []Connection
+
+	for _, pid := range pids {
+		procConns, err := getConnectionsForPid(pid)
+		if err != nil {
+			continue
+		}
+		connections = append(connections, procConns...)
+	}
+
+	return connections, nil
+}
+
+// GetAllConnections returns network connections
+func GetAllConnections() ([]Connection, error) {
+	return GetConnections()
+}
+
+func listAllPids() ([]int, error) {
+	numPids := C.proc_listpids(C.PROC_ALL_PIDS, 0, nil, 0)
+	if numPids <= 0 {
+		return nil, fmt.Errorf("proc_listpids failed")
+	}
+
+	bufSize := C.int(numPids) * C.int(unsafe.Sizeof(C.int(0)))
+	buf := make([]C.int, numPids)
+
+	numPids = C.proc_listpids(C.PROC_ALL_PIDS, 0, unsafe.Pointer(&buf[0]), bufSize)
+	if numPids <= 0 {
+		return nil, fmt.Errorf("proc_listpids failed")
+	}
+
+	count := int(numPids) / int(unsafe.Sizeof(C.int(0)))
+	pids := make([]int, 0, count)
+	for i := 0; i < count; i++ {
+		if buf[i] > 0 {
+			pids = append(pids, int(buf[i]))
+		}
+	}
+
+	return pids, nil
+}
+
+func getConnectionsForPid(pid int) ([]Connection, error) {
+	procName := getProcessName(pid)
+	uid := int(C.get_proc_uid(C.int(pid)))
+	user := ""
+	if uid >= 0 {
+		cUser := C.get_username(C.int(uid))
+		if cUser != nil {
+			user = C.GoString(cUser)
+		} else {
+			user = strconv.Itoa(uid)
+		}
+	}
+
+	bufSize := C.proc_pidinfo(C.int(pid), C.PROC_PIDLISTFDS, 0, nil, 0)
+	if bufSize <= 0 {
+		return nil, fmt.Errorf("failed to get fd list size")
+	}
+
+	buf := make([]byte, bufSize)
+	ret := C.proc_pidinfo(C.int(pid), C.PROC_PIDLISTFDS, 0, unsafe.Pointer(&buf[0]), bufSize)
+	if ret <= 0 {
+		return nil, fmt.Errorf("failed to get fd list")
+	}
+
+	fdInfoSize := int(unsafe.Sizeof(C.struct_proc_fdinfo{}))
+	numFds := int(ret) / fdInfoSize
+
+	var connections []Connection
+
+	for i := 0; i < numFds; i++ {
+		fdInfo := (*C.struct_proc_fdinfo)(unsafe.Pointer(&buf[i*fdInfoSize]))
+
+		if fdInfo.proc_fdtype != C.PROX_FDTYPE_SOCKET {
+			continue
+		}
+
+		conn, ok := getSocketInfo(pid, int(fdInfo.proc_fd), procName, uid, user)
+		if ok {
+			connections = append(connections, conn)
+		}
+	}
+
+	return connections, nil
+}
+
+func getSocketInfo(pid, fd int, procName string, uid int, user string) (Connection, bool) {
+	var info C.socket_info_t
+
+	ret := C.get_socket_info(C.int(pid), C.int(fd), &info)
+	if ret != 0 {
+		return Connection{}, false
+	}
+
+	// only interested in IPv4 and IPv6
+	if info.family != C.AF_INET && info.family != C.AF_INET6 {
+		return Connection{}, false
+	}
+
+	// only TCP and UDP
+	if info.sock_type != C.SOCK_STREAM && info.sock_type != C.SOCK_DGRAM {
+		return Connection{}, false
+	}
+
+	proto := "tcp"
+	if info.sock_type == C.SOCK_DGRAM {
+		proto = "udp"
+	}
+
+	ipVersion := "IPv4"
+	if info.family == C.AF_INET6 {
+		ipVersion = "IPv6"
+		proto = proto + "6"
+	}
+
+	var laddr, raddr string
+
+	if info.family == C.AF_INET {
+		laddr = ipv4ToString(uint32(info.laddr4))
+		raddr = ipv4ToString(uint32(info.raddr4))
+	} else {
+		laddr = ipv6ToString(info.laddr6)
+		raddr = ipv6ToString(info.raddr6)
+	}
+
+	if laddr == "0.0.0.0" || laddr == "::" {
+		laddr = "*"
+	}
+	if raddr == "0.0.0.0" || raddr == "::" {
+		raddr = "*"
+	}
+
+	state := ""
+	if info.sock_type == C.SOCK_STREAM {
+		state = tcpStateToString(int(info.state))
+	} else if info.sock_type == C.SOCK_DGRAM {
+		// udp is connectionless - infer state from remote address
+		if raddr == "*" && int(info.rport) == 0 {
+			state = "LISTEN"
+		} else {
+			state = "ESTABLISHED"
+		}
+	}
+
+	conn := Connection{
+		TS:        time.Now(),
+		Proto:     proto,
+		IPVersion: ipVersion,
+		State:     state,
+		Laddr:     laddr,
+		Lport:     int(info.lport),
+		Raddr:     raddr,
+		Rport:     int(info.rport),
+		PID:       pid,
+		Process:   procName,
+		UID:       uid,
+		User:      user,
+		Interface: guessNetworkInterface(laddr),
+	}
+
+	return conn, true
+}
+
+func getProcessName(pid int) string {
+	var name [256]C.char
+	ret := C.get_proc_name(C.int(pid), &name[0], 256)
+	if ret <= 0 {
+		return ""
+	}
+	return C.GoString(&name[0])
+}
+
+func ipv4ToString(addr uint32) string {
+	ip := make(net.IP, 4)
+	ip[0] = byte(addr)
+	ip[1] = byte(addr >> 8)
+	ip[2] = byte(addr >> 16)
+	ip[3] = byte(addr >> 24)
+	return ip.String()
+}
+
+func ipv6ToString(addr [16]C.uint8_t) string {
+	ip := make(net.IP, 16)
+	for i := 0; i < 16; i++ {
+		ip[i] = byte(addr[i])
+	}
+
+	if ip.To4() != nil {
+		return ip.To4().String()
+	}
+
+	return ip.String()
+}
+
+func tcpStateToString(state int) string {
+	// macOS TCP states from netinet/tcp_fsm.h
+	states := map[int]string{
+		0:  "CLOSED",
+		1:  "LISTEN",
+		2:  "SYN_SENT",
+		3:  "SYN_RECV",
+		4:  "ESTABLISHED",
+		5:  "CLOSE_WAIT",
+		6:  "FIN_WAIT1",
+		7:  "CLOSING",
+		8:  "LAST_ACK",
+		9:  "FIN_WAIT2",
+		10: "TIME_WAIT",
+	}
+
+	if s, exists := states[state]; exists {
+		return s
+	}
+	return ""
+}

internal/collector/collector_linux.go

@@ -0,0 +1,511 @@
+//go:build linux
+
+package collector
+
+import (
+	"bufio"
+	"bytes"
+	"fmt"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/karol-broda/snitch/internal/errutil"
+)
+
+// set SNITCH_DEBUG_TIMING=1 to enable timing diagnostics
+var debugTiming = os.Getenv("SNITCH_DEBUG_TIMING") != ""
+
+func logTiming(label string, start time.Time, extra ...string) {
+	if !debugTiming {
+		return
+	}
+	elapsed := time.Since(start)
+	if len(extra) > 0 {
+		fmt.Fprintf(os.Stderr, "[timing] %s: %v (%s)\n", label, elapsed, extra[0])
+	} else {
+		fmt.Fprintf(os.Stderr, "[timing] %s: %v\n", label, elapsed)
+	}
+}
+
+// userCache caches uid to username mappings to avoid repeated lookups
+var userCache = struct {
+	sync.RWMutex
+	m map[int]string
+}{m: make(map[int]string)}
+
+func lookupUsername(uid int) string {
+	userCache.RLock()
+	if username, exists := userCache.m[uid]; exists {
+		userCache.RUnlock()
+		return username
+	}
+	userCache.RUnlock()
+
+	start := time.Now()
+	username := strconv.Itoa(uid)
+	u, err := user.LookupId(strconv.Itoa(uid))
+	if err == nil && u != nil {
+		username = u.Username
+	}
+	elapsed := time.Since(start)
+	if debugTiming && elapsed > 10*time.Millisecond {
+		fmt.Fprintf(os.Stderr, "[timing] user.LookupId(%d) slow: %v\n", uid, elapsed)
+	}
+
+	userCache.Lock()
+	userCache.m[uid] = username
+	userCache.Unlock()
+
+	return username
+}
+
+// DefaultCollector implements the Collector interface using /proc filesystem
+type DefaultCollector struct{}
+
+// GetConnections fetches all network connections by parsing /proc files
+func (dc *DefaultCollector) GetConnections() ([]Connection, error) {
+	totalStart := time.Now()
+	defer func() { logTiming("GetConnections total", totalStart) }()
+
+	inodeStart := time.Now()
+	inodeMap, err := buildInodeToProcessMap()
+	logTiming("buildInodeToProcessMap", inodeStart, fmt.Sprintf("%d inodes", len(inodeMap)))
+	if err != nil {
+		return nil, fmt.Errorf("failed to build inode map: %w", err)
+	}
+
+	var connections []Connection
+
+	parseStart := time.Now()
+	tcpConns, err := parseProcNet("/proc/net/tcp", "tcp", 4, inodeMap)
+	if err == nil {
+		connections = append(connections, tcpConns...)
+	}
+
+	tcpConns6, err := parseProcNet("/proc/net/tcp6", "tcp6", 6, inodeMap)
+	if err == nil {
+		connections = append(connections, tcpConns6...)
+	}
+
+	udpConns, err := parseProcNet("/proc/net/udp", "udp", 4, inodeMap)
+	if err == nil {
+		connections = append(connections, udpConns...)
+	}
+
+	udpConns6, err := parseProcNet("/proc/net/udp6", "udp6", 6, inodeMap)
+	if err == nil {
+		connections = append(connections, udpConns6...)
+	}
+	logTiming("parseProcNet (all)", parseStart, fmt.Sprintf("%d connections", len(connections)))
+
+	return connections, nil
+}
+
+// GetAllConnections returns both network and Unix domain socket connections
+func GetAllConnections() ([]Connection, error) {
+	networkConns, err := GetConnections()
+	if err != nil {
+		return nil, err
+	}
+
+	unixConns, err := GetUnixSockets()
+	if err == nil {
+		networkConns = append(networkConns, unixConns...)
+	}
+
+	return networkConns, nil
+}
+
+type processInfo struct {
+	pid     int
+	command string
+	uid     int
+	user    string
+}
+
+type inodeEntry struct {
+	inode int64
+	info  *processInfo
+}
+
+func buildInodeToProcessMap() (map[int64]*processInfo, error) {
+	readDirStart := time.Now()
+	procDir, err := os.Open("/proc")
+	if err != nil {
+		return nil, err
+	}
+	defer errutil.Close(procDir)
+
+	entries, err := procDir.Readdir(-1)
+	if err != nil {
+		return nil, err
+	}
+
+	// collect pids first
+	pids := make([]int, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		pid, err := strconv.Atoi(entry.Name())
+		if err != nil {
+			continue
+		}
+		pids = append(pids, pid)
+	}
+	logTiming("  readdir /proc", readDirStart, fmt.Sprintf("%d pids", len(pids)))
+
+	// process pids in parallel with limited concurrency
+	scanStart := time.Now()
+	const numWorkers = 8
+	pidChan := make(chan int, len(pids))
+	resultChan := make(chan []inodeEntry, len(pids))
+
+	var totalFDs atomic.Int64
+	var wg sync.WaitGroup
+	for i := 0; i < numWorkers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for pid := range pidChan {
+				entries := scanProcessSockets(pid)
+				if len(entries) > 0 {
+					totalFDs.Add(int64(len(entries)))
+					resultChan <- entries
+				}
+			}
+		}()
+	}
+
+	for _, pid := range pids {
+		pidChan <- pid
+	}
+	close(pidChan)
+
+	go func() {
+		wg.Wait()
+		close(resultChan)
+	}()
+
+	inodeMap := make(map[int64]*processInfo)
+	for entries := range resultChan {
+		for _, e := range entries {
+			inodeMap[e.inode] = e.info
+		}
+	}
+	logTiming("  scan all processes", scanStart, fmt.Sprintf("%d socket fds scanned", totalFDs.Load()))
+
+	return inodeMap, nil
+}
+
+func scanProcessSockets(pid int) []inodeEntry {
+	start := time.Now()
+
+	procInfo, err := getProcessInfo(pid)
+	if err != nil {
+		return nil
+	}
+
+	pidStr := strconv.Itoa(pid)
+	fdDir := filepath.Join("/proc", pidStr, "fd")
+	fdEntries, err := os.ReadDir(fdDir)
+	if err != nil {
+		return nil
+	}
+
+	var results []inodeEntry
+	for _, fdEntry := range fdEntries {
+		fdPath := filepath.Join(fdDir, fdEntry.Name())
+		link, err := os.Readlink(fdPath)
+		if err != nil {
+			continue
+		}
+
+		if strings.HasPrefix(link, "socket:[") && strings.HasSuffix(link, "]") {
+			inodeStr := link[8 : len(link)-1]
+			inode, err := strconv.ParseInt(inodeStr, 10, 64)
+			if err != nil {
+				continue
+			}
+			results = append(results, inodeEntry{inode: inode, info: procInfo})
+		}
+	}
+
+	elapsed := time.Since(start)
+	if debugTiming && elapsed > 20*time.Millisecond {
+		fmt.Fprintf(os.Stderr, "[timing] slow process scan: pid=%d (%s) fds=%d time=%v\n",
+			pid, procInfo.command, len(fdEntries), elapsed)
+	}
+
+	return results
+}
+
+func getProcessInfo(pid int) (*processInfo, error) {
+	info := &processInfo{pid: pid}
+
+	commPath := filepath.Join("/proc", strconv.Itoa(pid), "comm")
+	commData, err := os.ReadFile(commPath)
+	if err == nil && len(commData) > 0 {
+		info.command = strings.TrimSpace(string(commData))
+	}
+
+	if info.command == "" {
+		cmdlinePath := filepath.Join("/proc", strconv.Itoa(pid), "cmdline")
+		cmdlineData, err := os.ReadFile(cmdlinePath)
+		if err != nil {
+			return nil, err
+		}
+
+		if len(cmdlineData) > 0 {
+			parts := bytes.Split(cmdlineData, []byte{0})
+			if len(parts) > 0 && len(parts[0]) > 0 {
+				fullPath := string(parts[0])
+				baseName := filepath.Base(fullPath)
+				if strings.Contains(baseName, " ") {
+					baseName = strings.Fields(baseName)[0]
+				}
+				info.command = baseName
+			}
+		}
+	}
+
+	statusPath := filepath.Join("/proc", strconv.Itoa(pid), "status")
+	statusFile, err := os.Open(statusPath)
+	if err != nil {
+		return info, nil
+	}
+	defer errutil.Close(statusFile)
+
+	scanner := bufio.NewScanner(statusFile)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if strings.HasPrefix(line, "Uid:") {
+			fields := strings.Fields(line)
+			if len(fields) >= 2 {
+				uid, err := strconv.Atoi(fields[1])
+				if err == nil {
+					info.uid = uid
+					info.user = lookupUsername(uid)
+				}
+			}
+			break
+		}
+	}
+
+	return info, nil
+}
+
+func parseProcNet(path, proto string, ipVersion int, inodeMap map[int64]*processInfo) ([]Connection, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer errutil.Close(file)
+
+	var connections []Connection
+	scanner := bufio.NewScanner(file)
+
+	scanner.Scan()
+
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+
+		fields := strings.Fields(line)
+		if len(fields) < 10 {
+			continue
+		}
+
+		localAddr, localPort, err := parseHexAddr(fields[1])
+		if err != nil {
+			continue
+		}
+
+		remoteAddr, remotePort, err := parseHexAddr(fields[2])
+		if err != nil {
+			continue
+		}
+
+		stateHex := fields[3]
+		state := parseState(stateHex, proto)
+
+		inode, _ := strconv.ParseInt(fields[9], 10, 64)
+
+		// refine udp state: if unconnected and remote is wildcard, it's listening
+		if strings.HasPrefix(proto, "udp") && state == "UNCONNECTED" {
+			if remoteAddr == "*" && remotePort == 0 {
+				state = "LISTEN"
+			}
+		}
+
+		conn := Connection{
+			TS:        time.Now(),
+			Proto:     proto,
+			IPVersion: fmt.Sprintf("IPv%d", ipVersion),
+			State:     state,
+			Laddr:     localAddr,
+			Lport:     localPort,
+			Raddr:     remoteAddr,
+			Rport:     remotePort,
+			Inode:     inode,
+		}
+
+		if procInfo, exists := inodeMap[inode]; exists {
+			conn.PID = procInfo.pid
+			conn.Process = procInfo.command
+			conn.UID = procInfo.uid
+			conn.User = procInfo.user
+		}
+
+		conn.Interface = guessNetworkInterface(localAddr)
+
+		connections = append(connections, conn)
+	}
+
+	return connections, scanner.Err()
+}
+
+func parseState(hexState, proto string) string {
+	state, err := strconv.ParseInt(hexState, 16, 32)
+	if err != nil {
+		return ""
+	}
+
+	tcpStates := map[int64]string{
+		0x01: "ESTABLISHED",
+		0x02: "SYN_SENT",
+		0x03: "SYN_RECV",
+		0x04: "FIN_WAIT1",
+		0x05: "FIN_WAIT2",
+		0x06: "TIME_WAIT",
+		0x07: "CLOSE",
+		0x08: "CLOSE_WAIT",
+		0x09: "LAST_ACK",
+		0x0A: "LISTEN",
+		0x0B: "CLOSING",
+	}
+
+	if strings.HasPrefix(proto, "tcp") {
+		if s, exists := tcpStates[state]; exists {
+			return s
+		}
+		return ""
+	}
+
+	// udp states - udp is connectionless so the kernel reuses tcp state values
+	// with different meanings:
+	// 0x07 (TCP_CLOSE) = unconnected socket, typically bound and listening
+	// 0x01 (TCP_ESTABLISHED) = "connected" socket (connect() was called)
+	udpStates := map[int64]string{
+		0x01: "ESTABLISHED",
+		0x07: "UNCONNECTED",
+	}
+
+	if s, exists := udpStates[state]; exists {
+		return s
+	}
+
+	return ""
+}
+
+func parseHexAddr(hexAddr string) (string, int, error) {
+	parts := strings.Split(hexAddr, ":")
+	if len(parts) != 2 {
+		return "", 0, fmt.Errorf("invalid address format")
+	}
+
+	hexIP := parts[0]
+
+	port, err := strconv.ParseInt(parts[1], 16, 32)
+	if err != nil {
+		return "", 0, err
+	}
+
+	if len(hexIP) == 8 {
+		ip1, _ := strconv.ParseInt(hexIP[6:8], 16, 32)
+		ip2, _ := strconv.ParseInt(hexIP[4:6], 16, 32)
+		ip3, _ := strconv.ParseInt(hexIP[2:4], 16, 32)
+		ip4, _ := strconv.ParseInt(hexIP[0:2], 16, 32)
+		addr := fmt.Sprintf("%d.%d.%d.%d", ip1, ip2, ip3, ip4)
+
+		if addr == "0.0.0.0" {
+			addr = "*"
+		}
+
+		return addr, int(port), nil
+	} else if len(hexIP) == 32 {
+		var ipv6Parts []string
+		for i := 0; i < 32; i += 8 {
+			word := hexIP[i : i+8]
+			p1 := word[6:8] + word[4:6] + word[2:4] + word[0:2]
+			ipv6Parts = append(ipv6Parts, p1)
+		}
+
+		fullAddr := strings.Join(ipv6Parts, "")
+		var formatted []string
+		for i := 0; i < len(fullAddr); i += 4 {
+			formatted = append(formatted, fullAddr[i:i+4])
+		}
+		addr := strings.Join(formatted, ":")
+
+		addr = simplifyIPv6(addr)
+
+		if addr == "::" || addr == "0:0:0:0:0:0:0:0" {
+			addr = "*"
+		}
+
+		return addr, int(port), nil
+	}
+
+	return "", 0, fmt.Errorf("unsupported address format")
+}
+
+func GetUnixSockets() ([]Connection, error) {
+	connections := []Connection{}
+
+	file, err := os.Open("/proc/net/unix")
+	if err != nil {
+		return connections, nil
+	}
+	defer errutil.Close(file)
+
+	scanner := bufio.NewScanner(file)
+	scanner.Scan()
+
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		fields := strings.Fields(line)
+		if len(fields) < 7 {
+			continue
+		}
+
+		inode, _ := strconv.ParseInt(fields[6], 10, 64)
+		path := ""
+		if len(fields) > 7 {
+			path = fields[7]
+		}
+
+		conn := Connection{
+			TS:        time.Now(),
+			Proto:     "unix",
+			Laddr:     path,
+			Raddr:     "",
+			State:     "CONNECTED",
+			Inode:     inode,
+			Interface: "unix",
+		}
+
+		connections = append(connections, conn)
+	}
+
+	return connections, nil
+}
+

internal/collector/collector_test.go

@@ -1,7 +1,10 @@
+//go:build linux
+
 package collector
 
 import (
 	"testing"
+	"time"
 )
 
 func TestGetConnections(t *testing.T) {
@@ -14,3 +17,101 @@ func TestGetConnections(t *testing.T) {
 	// connections are dynamic, so just verify function succeeded
 	t.Logf("Successfully got %d connections", len(conns))
 }
+
+func TestGetConnectionsPerformance(t *testing.T) {
+	// measures performance to catch regressions
+	// run with: go test -v -run TestGetConnectionsPerformance
+
+	const maxDuration = 500 * time.Millisecond
+	const iterations = 5
+
+	// warm up caches first
+	_, err := GetConnections()
+	if err != nil {
+		t.Fatalf("warmup failed: %v", err)
+	}
+
+	var total time.Duration
+	var maxSeen time.Duration
+
+	for i := 0; i < iterations; i++ {
+		start := time.Now()
+		conns, err := GetConnections()
+		elapsed := time.Since(start)
+
+		if err != nil {
+			t.Fatalf("iteration %d failed: %v", i, err)
+		}
+
+		total += elapsed
+		if elapsed > maxSeen {
+			maxSeen = elapsed
+		}
+
+		t.Logf("iteration %d: %v (%d connections)", i+1, elapsed, len(conns))
+	}
+
+	avg := total / time.Duration(iterations)
+	t.Logf("average: %v, max: %v", avg, maxSeen)
+
+	if maxSeen > maxDuration {
+		t.Errorf("slowest iteration took %v, expected < %v", maxSeen, maxDuration)
+	}
+}
+
+func TestGetConnectionsColdCache(t *testing.T) {
+	// tests performance with cold user cache
+	// this simulates first run or after cache invalidation
+
+	const maxDuration = 2 * time.Second
+
+	clearUserCache()
+
+	start := time.Now()
+	conns, err := GetConnections()
+	elapsed := time.Since(start)
+
+	if err != nil {
+		t.Fatalf("GetConnections() failed: %v", err)
+	}
+
+	t.Logf("cold cache: %v (%d connections, %d cached users after)",
+		elapsed, len(conns), userCacheSize())
+
+	if elapsed > maxDuration {
+		t.Errorf("cold cache took %v, expected < %v", elapsed, maxDuration)
+	}
+}
+
+func BenchmarkGetConnections(b *testing.B) {
+	// warm cache benchmark - measures typical runtime
+	// run with: go test -bench=BenchmarkGetConnections -benchtime=5s
+
+	// warm up
+	_, _ = GetConnections()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = GetConnections()
+	}
+}
+
+func BenchmarkGetConnectionsColdCache(b *testing.B) {
+	// cold cache benchmark - measures worst-case with cache cleared each iteration
+	// run with: go test -bench=BenchmarkGetConnectionsColdCache -benchtime=10s
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		clearUserCache()
+		_, _ = GetConnections()
+	}
+}
+
+func BenchmarkBuildInodeMap(b *testing.B) {
+	// benchmarks just the inode map building (most expensive part)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = buildInodeToProcessMap()
+	}
+}

internal/collector/collector_test_helpers_linux.go

@@ -0,0 +1,18 @@
+//go:build linux
+
+package collector
+
+// clearUserCache clears the user lookup cache for testing
+func clearUserCache() {
+	userCache.Lock()
+	userCache.m = make(map[int]string)
+	userCache.Unlock()
+}
+
+// userCacheSize returns the number of cached user entries
+func userCacheSize() int {
+	userCache.RLock()
+	defer userCache.RUnlock()
+	return len(userCache.m)
+}
+

internal/collector/filter.go

@@ -36,7 +36,7 @@ func (f *FilterOptions) IsEmpty() bool {
 }
 
 func (f *FilterOptions) Matches(c Connection) bool {
-	if f.Proto != "" && !strings.EqualFold(c.Proto, f.Proto) {
+	if f.Proto != "" && !matchesProto(c.Proto, f.Proto) {
 		return false
 	}
 	if f.State != "" && !strings.EqualFold(c.State, f.State) {
@@ -104,6 +104,30 @@ func containsIgnoreCase(s, substr string) bool {
 	return strings.Contains(strings.ToLower(s), strings.ToLower(substr))
 }
 
+// checks if a connection's protocol matches the filter.
+// treats "tcp" as matching "tcp" and "tcp6", same for "udp"/"udp6"
+func matchesProto(connProto, filterProto string) bool {
+	connLower := strings.ToLower(connProto)
+	filterLower := strings.ToLower(filterProto)
+
+	// exact match
+	if connLower == filterLower {
+		return true
+	}
+
+	// "tcp" matches both "tcp" and "tcp6"
+	if filterLower == "tcp" && (connLower == "tcp" || connLower == "tcp6") {
+		return true
+	}
+
+	// "udp" matches both "udp" and "udp6"
+	if filterLower == "udp" && (connLower == "udp" || connLower == "udp6") {
+		return true
+	}
+
+	return false
+}
+
 func matchesContains(c Connection, query string) bool {
 	q := strings.ToLower(query)
 	return containsIgnoreCase(c.Process, q) ||

internal/collector/mock.go

@@ -162,7 +162,7 @@ func getDefaultTestConnections() []Connection {
 			UID:       25,
 			Proto:     "udp",
 			IPVersion: "IPv4",
-			State:     "CONNECTED",
+			State:     "LISTEN",
 			Laddr:     "0.0.0.0",
 			Lport:     53,
 			Raddr:     "*",
@@ -358,7 +358,7 @@ func GetTestFixtures() []TestFixture {
 					PID:       2,
 					Process:   "udp-server",
 					Proto:     "udp",
-					State:     "CONNECTED",
+					State:     "LISTEN",
 					Laddr:     "0.0.0.0",
 					Lport:     53,
 					Interface: "eth0",

internal/collector/sort.go

@@ -111,16 +111,17 @@ func compareConnections(a, b Connection, field SortField) bool {
 func stateOrder(state string) int {
 	order := map[string]int{
 		"LISTEN":      0,
-		"ESTABLISHED": 1,
-		"SYN_SENT":    2,
-		"SYN_RECV":    3,
-		"FIN_WAIT1":   4,
-		"FIN_WAIT2":   5,
-		"TIME_WAIT":   6,
-		"CLOSE_WAIT":  7,
-		"LAST_ACK":    8,
-		"CLOSING":     9,
-		"CLOSED":      10,
+		"UNCONNECTED": 1, // udp sockets bound but not connected to a specific peer
+		"ESTABLISHED": 2,
+		"SYN_SENT":    3,
+		"SYN_RECV":    4,
+		"FIN_WAIT1":   5,
+		"FIN_WAIT2":   6,
+		"TIME_WAIT":   7,
+		"CLOSE_WAIT":  8,
+		"LAST_ACK":    9,
+		"CLOSING":     10,
+		"CLOSED":      11,
 	}
 
 	if o, exists := order[strings.ToUpper(state)]; exists {

internal/color/color_test.go

@@ -5,6 +5,8 @@ import (
 	"testing"
 
 	"github.com/fatih/color"
+
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 func TestInit(t *testing.T) {
@@ -29,8 +31,8 @@ func TestInit(t *testing.T) {
 			origTerm := os.Getenv("TERM")
 
 			// Set test env vars
-			os.Setenv("NO_COLOR", tc.noColor)
-			os.Setenv("TERM", tc.term)
+			errutil.Setenv("NO_COLOR", tc.noColor)
+			errutil.Setenv("TERM", tc.term)
 
 			Init(tc.mode)
 
@@ -39,8 +41,8 @@ func TestInit(t *testing.T) {
 			}
 
 			// Restore original env vars
-			os.Setenv("NO_COLOR", origNoColor)
-			os.Setenv("TERM", origTerm)
+			errutil.Setenv("NO_COLOR", origNoColor)
+			errutil.Setenv("TERM", origTerm)
 		})
 	}
 }

internal/config/config.go

@@ -4,14 +4,22 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
+	"github.com/karol-broda/snitch/internal/theme"
 	"github.com/spf13/viper"
 )
 
 // Config represents the application configuration
 type Config struct {
 	Defaults DefaultConfig `mapstructure:"defaults"`
+	TUI      TUIConfig     `mapstructure:"tui"`
+}
+
+// TUIConfig contains TUI-specific configuration
+type TUIConfig struct {
+	RememberState bool `mapstructure:"remember_state"`
 }
 
 // DefaultConfig contains default values for CLI options
@@ -23,6 +31,7 @@ type DefaultConfig struct {
 	Units        string   `mapstructure:"units"`
 	Color        string   `mapstructure:"color"`
 	Resolve      bool     `mapstructure:"resolve"`
+	DNSCache     bool     `mapstructure:"dns_cache"`
 	IPv4         bool     `mapstructure:"ipv4"`
 	IPv6         bool     `mapstructure:"ipv6"`
 	NoHeaders    bool     `mapstructure:"no_headers"`
@@ -55,6 +64,7 @@ func Load() (*Config, error) {
 	// environment variable bindings for readme-documented variables
 	_ = v.BindEnv("config", "SNITCH_CONFIG")
 	_ = v.BindEnv("defaults.resolve", "SNITCH_RESOLVE")
+	_ = v.BindEnv("defaults.dns_cache", "SNITCH_DNS_CACHE")
 	_ = v.BindEnv("defaults.theme", "SNITCH_THEME")
 	_ = v.BindEnv("defaults.color", "SNITCH_NO_COLOR")
 	
@@ -88,19 +98,22 @@ func Load() (*Config, error) {
 }
 
 func setDefaults(v *viper.Viper) {
-	// Set default values matching the README specification
 	v.SetDefault("defaults.interval", "1s")
 	v.SetDefault("defaults.numeric", false)
 	v.SetDefault("defaults.fields", []string{"pid", "process", "user", "proto", "state", "laddr", "lport", "raddr", "rport"})
-	v.SetDefault("defaults.theme", "auto")
+	v.SetDefault("defaults.theme", "ansi")
 	v.SetDefault("defaults.units", "auto")
 	v.SetDefault("defaults.color", "auto")
 	v.SetDefault("defaults.resolve", true)
+	v.SetDefault("defaults.dns_cache", true)
 	v.SetDefault("defaults.ipv4", false)
 	v.SetDefault("defaults.ipv6", false)
 	v.SetDefault("defaults.no_headers", false)
 	v.SetDefault("defaults.output_format", "table")
 	v.SetDefault("defaults.sort_by", "")
+
+	// tui settings
+	v.SetDefault("tui.remember_state", false)
 }
 
 func handleSpecialEnvVars(v *viper.Viper) {
@@ -114,6 +127,11 @@ func handleSpecialEnvVars(v *viper.Viper) {
 		v.Set("defaults.resolve", false)
 		v.Set("defaults.numeric", true)
 	}
+
+	// Handle SNITCH_DNS_CACHE - if set to "0", disable dns caching
+	if os.Getenv("SNITCH_DNS_CACHE") == "0" {
+		v.Set("defaults.dns_cache", false)
+	}
 }
 
 // Get returns the global configuration, loading it if necessary
@@ -121,22 +139,25 @@ func Get() *Config {
 	if globalConfig == nil {
 		config, err := Load()
 		if err != nil {
-			// Return default config on error
 			return &Config{
 				Defaults: DefaultConfig{
 					Interval:     "1s",
 					Numeric:      false,
 					Fields:       []string{"pid", "process", "user", "proto", "state", "laddr", "lport", "raddr", "rport"},
-					Theme:        "auto",
+					Theme:        "ansi",
 					Units:        "auto",
 					Color:        "auto",
 					Resolve:      true,
+					DNSCache:     true,
 					IPv4:         false,
 					IPv6:         false,
 					NoHeaders:    false,
 					OutputFormat: "table",
 					SortBy:       "",
 				},
+				TUI: TUIConfig{
+					RememberState: false,
+				},
 			}
 		}
 		return config
@@ -154,7 +175,9 @@ func (c *Config) GetInterval() time.Duration {
 
 // CreateExampleConfig creates an example configuration file
 func CreateExampleConfig(path string) error {
-	exampleConfig := `# snitch configuration file
+	themeList := strings.Join(theme.ListThemes(), ", ")
+
+	exampleConfig := fmt.Sprintf(`# snitch configuration file
 # See https://github.com/you/snitch for full documentation
 
 [defaults]
@@ -167,8 +190,9 @@ numeric = false
 # Default fields to display (comma-separated list)
 fields = ["pid", "process", "user", "proto", "state", "laddr", "lport", "raddr", "rport"]
 
-# Default theme for TUI (dark, light, mono, auto)
-theme = "auto"
+# Default theme for TUI (ansi inherits terminal colors)
+# Available: %s
+theme = "%s"
 
 # Default units for byte display (auto, si, iec)
 units = "auto"
@@ -187,7 +211,12 @@ ipv6 = false
 no_headers = false
 output_format = "table"
 sort_by = ""
-`
+
+[tui]
+# remember view options (filters, sort, resolution) between sessions
+# state is saved to $XDG_STATE_HOME/snitch/tui.json
+remember_state = false
+`, themeList, theme.DefaultTheme)
 
 	// Ensure directory exists
 	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {

internal/errutil/errutil.go

@@ -0,0 +1,65 @@
+package errutil
+
+import (
+	"io"
+	"os"
+
+	"github.com/fatih/color"
+)
+
+func Ignore[T any](val T, _ error) T {
+	return val
+}
+
+func IgnoreErr(_ error) {}
+
+func Close(c io.Closer) {
+	if c != nil {
+		_ = c.Close()
+	}
+}
+
+// color.Color wrappers - these discard the (int, error) return values
+
+func Print(c *color.Color, a ...any) {
+	_, _ = c.Print(a...)
+}
+
+func Println(c *color.Color, a ...any) {
+	_, _ = c.Println(a...)
+}
+
+func Printf(c *color.Color, format string, a ...any) {
+	_, _ = c.Printf(format, a...)
+}
+
+func Fprintf(c *color.Color, w io.Writer, format string, a ...any) {
+	_, _ = c.Fprintf(w, format, a...)
+}
+
+// os function wrappers for test cleanup where errors are non-critical
+
+func Setenv(key, value string) {
+	_ = os.Setenv(key, value)
+}
+
+func Unsetenv(key string) {
+	_ = os.Unsetenv(key)
+}
+
+func Remove(name string) {
+	_ = os.Remove(name)
+}
+
+func RemoveAll(path string) {
+	_ = os.RemoveAll(path)
+}
+
+// Flush calls Flush on a tabwriter and discards the error
+type Flusher interface {
+	Flush() error
+}
+
+func Flush(f Flusher) {
+	_ = f.Flush()
+}

internal/resolver/resolver.go

@@ -2,17 +2,22 @@ package resolver
 
 import (
 	"context"
+	"fmt"
 	"net"
+	"os"
 	"strconv"
 	"sync"
 	"time"
 )
 
+var debugTiming = os.Getenv("SNITCH_DEBUG_TIMING") != ""
+
 // Resolver handles DNS and service name resolution with caching and timeouts
 type Resolver struct {
 	timeout  time.Duration
 	cache    map[string]string
 	mutex    sync.RWMutex
+	noCache  bool
 }
 
 // New creates a new resolver with the specified timeout
@@ -20,45 +25,60 @@ func New(timeout time.Duration) *Resolver {
 	return &Resolver{
 		timeout: timeout,
 		cache:   make(map[string]string),
+		noCache: false,
 	}
 }
 
+// SetNoCache disables caching - each lookup will hit DNS directly
+func (r *Resolver) SetNoCache(noCache bool) {
+	r.noCache = noCache
+}
+
 // ResolveAddr resolves an IP address to a hostname, with caching
 func (r *Resolver) ResolveAddr(addr string) string {
-	// Check cache first
+	// check cache first (unless caching is disabled)
+	if !r.noCache {
 		r.mutex.RLock()
 		if cached, exists := r.cache[addr]; exists {
 			r.mutex.RUnlock()
 			return cached
 		}
 		r.mutex.RUnlock()
+	}
 
-	// Parse IP to validate it
+	// parse ip to validate it
 	ip := net.ParseIP(addr)
 	if ip == nil {
-		// Not a valid IP, return as-is
 		return addr
 	}
 
-	// Perform resolution with timeout
+	// perform resolution with timeout
+	start := time.Now()
 	ctx, cancel := context.WithTimeout(context.Background(), r.timeout)
 	defer cancel()
 
 	names, err := net.DefaultResolver.LookupAddr(ctx, addr)
 
-	resolved := addr // fallback to original address
+	resolved := addr
 	if err == nil && len(names) > 0 {
 		resolved = names[0]
-		// Remove trailing dot if present
+		// remove trailing dot if present
 		if len(resolved) > 0 && resolved[len(resolved)-1] == '.' {
 			resolved = resolved[:len(resolved)-1]
 		}
 	}
 
-	// Cache the result
+	elapsed := time.Since(start)
+	if debugTiming && elapsed > 50*time.Millisecond {
+		fmt.Fprintf(os.Stderr, "[timing] slow DNS lookup: %s -> %s (%v)\n", addr, resolved, elapsed)
+	}
+
+	// cache the result (unless caching is disabled)
+	if !r.noCache {
 		r.mutex.Lock()
 		r.cache[addr] = resolved
 		r.mutex.Unlock()
+	}
 
 	return resolved
 }
@@ -71,15 +91,17 @@ func (r *Resolver) ResolvePort(port int, proto string) string {
 
 	cacheKey := strconv.Itoa(port) + "/" + proto
 
-	// Check cache first
+	// check cache first (unless caching is disabled)
+	if !r.noCache {
 		r.mutex.RLock()
 		if cached, exists := r.cache[cacheKey]; exists {
 			r.mutex.RUnlock()
 			return cached
 		}
 		r.mutex.RUnlock()
+	}
 
-	// Perform resolution with timeout
+	// perform resolution with timeout
 	ctx, cancel := context.WithTimeout(context.Background(), r.timeout)
 	defer cancel()
 
@@ -87,16 +109,18 @@ func (r *Resolver) ResolvePort(port int, proto string) string {
 
 	resolved := strconv.Itoa(port) // fallback to port number
 	if err == nil && service != 0 {
-		// Try to get service name
+		// try to get service name
 		if serviceName := getServiceName(port, proto); serviceName != "" {
 			resolved = serviceName
 		}
 	}
 
-	// Cache the result
+	// cache the result (unless caching is disabled)
+	if !r.noCache {
 		r.mutex.Lock()
 		r.cache[cacheKey] = resolved
 		r.mutex.Unlock()
+	}
 
 	return resolved
 }
@@ -159,22 +183,38 @@ func getServiceName(port int, proto string) string {
 	return ""
 }
 
-// Global resolver instance
+// global resolver instance
 var globalResolver *Resolver
 
-// SetGlobalResolver sets the global resolver instance
-func SetGlobalResolver(timeout time.Duration) {
+// ResolverOptions configures the global resolver
+type ResolverOptions struct {
+	Timeout time.Duration
+	NoCache bool
+}
+
+// SetGlobalResolver sets the global resolver instance with options
+func SetGlobalResolver(opts ResolverOptions) {
+	timeout := opts.Timeout
+	if timeout == 0 {
+		timeout = 200 * time.Millisecond
+	}
 	globalResolver = New(timeout)
+	globalResolver.SetNoCache(opts.NoCache)
 }
 
 // GetGlobalResolver returns the global resolver instance
 func GetGlobalResolver() *Resolver {
 	if globalResolver == nil {
-		globalResolver = New(200 * time.Millisecond) // Default timeout
+		globalResolver = New(200 * time.Millisecond)
 	}
 	return globalResolver
 }
 
+// SetNoCache configures whether the global resolver bypasses cache
+func SetNoCache(noCache bool) {
+	GetGlobalResolver().SetNoCache(noCache)
+}
+
 // ResolveAddr is a convenience function using the global resolver
 func ResolveAddr(addr string) string {
 	return GetGlobalResolver().ResolveAddr(addr)
@@ -189,3 +229,48 @@ func ResolvePort(port int, proto string) string {
 func ResolveAddrPort(addr string, port int, proto string) (string, string) {
 	return GetGlobalResolver().ResolveAddrPort(addr, port, proto)
 }
+
+// ResolveAddrsParallel resolves multiple addresses concurrently and caches results.
+// This should be called before rendering to pre-warm the cache.
+func (r *Resolver) ResolveAddrsParallel(addrs []string) {
+	// dedupe and filter addresses that need resolution
+	unique := make(map[string]struct{})
+	for _, addr := range addrs {
+		if addr == "" || addr == "*" {
+			continue
+		}
+		// skip if already cached
+		r.mutex.RLock()
+		_, exists := r.cache[addr]
+		r.mutex.RUnlock()
+		if exists {
+			continue
+		}
+		unique[addr] = struct{}{}
+	}
+
+	if len(unique) == 0 {
+		return
+	}
+
+	var wg sync.WaitGroup
+	// limit concurrency to avoid overwhelming dns
+	sem := make(chan struct{}, 32)
+
+	for addr := range unique {
+		wg.Add(1)
+		go func(a string) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+			r.ResolveAddr(a)
+		}(addr)
+	}
+
+	wg.Wait()
+}
+
+// ResolveAddrsParallel is a convenience function using the global resolver
+func ResolveAddrsParallel(addrs []string) {
+	GetGlobalResolver().ResolveAddrsParallel(addrs)
+}

internal/resolver/resolver_bench_test.go

@@ -0,0 +1,159 @@
+package resolver
+
+import (
+	"fmt"
+	"testing"
+	"time"
+)
+
+func BenchmarkResolveAddr_CacheHit(b *testing.B) {
+	r := New(100 * time.Millisecond)
+	addr := "127.0.0.1"
+
+	// pre-populate cache
+	r.ResolveAddr(addr)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r.ResolveAddr(addr)
+	}
+}
+
+func BenchmarkResolveAddr_CacheMiss(b *testing.B) {
+	r := New(10 * time.Millisecond) // short timeout for faster benchmarks
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		// use different addresses to avoid cache hits
+		addr := fmt.Sprintf("127.0.0.%d", i%256)
+		r.ClearCache() // clear cache to force miss
+		r.ResolveAddr(addr)
+	}
+}
+
+func BenchmarkResolveAddr_NoCache(b *testing.B) {
+	r := New(10 * time.Millisecond)
+	r.SetNoCache(true)
+	addr := "127.0.0.1"
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r.ResolveAddr(addr)
+	}
+}
+
+func BenchmarkResolvePort_CacheHit(b *testing.B) {
+	r := New(100 * time.Millisecond)
+
+	// pre-populate cache
+	r.ResolvePort(80, "tcp")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r.ResolvePort(80, "tcp")
+	}
+}
+
+func BenchmarkResolvePort_WellKnown(b *testing.B) {
+	r := New(100 * time.Millisecond)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r.ClearCache()
+		r.ResolvePort(443, "tcp")
+	}
+}
+
+func BenchmarkGetServiceName(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		getServiceName(80, "tcp")
+	}
+}
+
+func BenchmarkGetServiceName_NotFound(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		getServiceName(12345, "tcp")
+	}
+}
+
+func BenchmarkResolveAddrsParallel_10(b *testing.B) {
+	benchmarkResolveAddrsParallel(b, 10)
+}
+
+func BenchmarkResolveAddrsParallel_100(b *testing.B) {
+	benchmarkResolveAddrsParallel(b, 100)
+}
+
+func BenchmarkResolveAddrsParallel_1000(b *testing.B) {
+	benchmarkResolveAddrsParallel(b, 1000)
+}
+
+func benchmarkResolveAddrsParallel(b *testing.B, count int) {
+	addrs := make([]string, count)
+	for i := 0; i < count; i++ {
+		addrs[i] = fmt.Sprintf("127.0.%d.%d", i/256, i%256)
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r := New(10 * time.Millisecond)
+		r.ResolveAddrsParallel(addrs)
+	}
+}
+
+func BenchmarkConcurrentResolveAddr(b *testing.B) {
+	r := New(100 * time.Millisecond)
+	addr := "127.0.0.1"
+
+	// pre-populate cache
+	r.ResolveAddr(addr)
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			r.ResolveAddr(addr)
+		}
+	})
+}
+
+func BenchmarkConcurrentResolvePort(b *testing.B) {
+	r := New(100 * time.Millisecond)
+
+	// pre-populate cache
+	r.ResolvePort(80, "tcp")
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			r.ResolvePort(80, "tcp")
+		}
+	})
+}
+
+func BenchmarkGetCacheSize(b *testing.B) {
+	r := New(100 * time.Millisecond)
+
+	// populate with some entries
+	for i := 0; i < 100; i++ {
+		r.ResolvePort(i+1, "tcp")
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r.GetCacheSize()
+	}
+}
+
+func BenchmarkClearCache(b *testing.B) {
+	r := New(100 * time.Millisecond)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		// populate and clear
+		for j := 0; j < 10; j++ {
+			r.ResolvePort(j+1, "tcp")
+		}
+		r.ClearCache()
+	}
+}
+

internal/resolver/resolver_test.go

@@ -0,0 +1,387 @@
+package resolver
+
+import (
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestNew(t *testing.T) {
+	r := New(100 * time.Millisecond)
+	if r == nil {
+		t.Fatal("expected non-nil resolver")
+	}
+	if r.timeout != 100*time.Millisecond {
+		t.Errorf("expected timeout 100ms, got %v", r.timeout)
+	}
+	if r.cache == nil {
+		t.Error("expected cache to be initialized")
+	}
+	if r.noCache {
+		t.Error("expected noCache to be false by default")
+	}
+}
+
+func TestSetNoCache(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	r.SetNoCache(true)
+	if !r.noCache {
+		t.Error("expected noCache to be true")
+	}
+
+	r.SetNoCache(false)
+	if r.noCache {
+		t.Error("expected noCache to be false")
+	}
+}
+
+func TestResolveAddr_InvalidIP(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	// invalid ip should return as-is
+	result := r.ResolveAddr("not-an-ip")
+	if result != "not-an-ip" {
+		t.Errorf("expected 'not-an-ip', got %q", result)
+	}
+
+	// empty string should return as-is
+	result = r.ResolveAddr("")
+	if result != "" {
+		t.Errorf("expected empty string, got %q", result)
+	}
+}
+
+func TestResolveAddr_Caching(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	// first call should cache
+	addr := "127.0.0.1"
+	result1 := r.ResolveAddr(addr)
+
+	// verify cache is populated
+	if r.GetCacheSize() != 1 {
+		t.Errorf("expected cache size 1, got %d", r.GetCacheSize())
+	}
+
+	// second call should use cache
+	result2 := r.ResolveAddr(addr)
+	if result1 != result2 {
+		t.Errorf("expected same result from cache, got %q and %q", result1, result2)
+	}
+}
+
+func TestResolveAddr_NoCacheMode(t *testing.T) {
+	r := New(100 * time.Millisecond)
+	r.SetNoCache(true)
+
+	addr := "127.0.0.1"
+	r.ResolveAddr(addr)
+
+	// cache should remain empty when noCache is enabled
+	if r.GetCacheSize() != 0 {
+		t.Errorf("expected cache size 0 with noCache, got %d", r.GetCacheSize())
+	}
+}
+
+func TestResolvePort_Zero(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	result := r.ResolvePort(0, "tcp")
+	if result != "0" {
+		t.Errorf("expected '0' for port 0, got %q", result)
+	}
+}
+
+func TestResolvePort_WellKnown(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	tests := []struct {
+		port     int
+		proto    string
+		expected string
+	}{
+		{80, "tcp", "http"},
+		{443, "tcp", "https"},
+		{22, "tcp", "ssh"},
+		{53, "udp", "domain"},
+		{5432, "tcp", "postgresql"},
+	}
+
+	for _, tt := range tests {
+		result := r.ResolvePort(tt.port, tt.proto)
+		if result != tt.expected {
+			t.Errorf("ResolvePort(%d, %q) = %q, want %q", tt.port, tt.proto, result, tt.expected)
+		}
+	}
+}
+
+func TestResolvePort_Caching(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	r.ResolvePort(80, "tcp")
+	r.ResolvePort(443, "tcp")
+
+	if r.GetCacheSize() != 2 {
+		t.Errorf("expected cache size 2, got %d", r.GetCacheSize())
+	}
+
+	// same port/proto should not add new entry
+	r.ResolvePort(80, "tcp")
+	if r.GetCacheSize() != 2 {
+		t.Errorf("expected cache size still 2, got %d", r.GetCacheSize())
+	}
+}
+
+func TestResolveAddrPort(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	addr, port := r.ResolveAddrPort("127.0.0.1", 80, "tcp")
+
+	if addr == "" {
+		t.Error("expected non-empty address")
+	}
+	if port != "http" {
+		t.Errorf("expected port 'http', got %q", port)
+	}
+}
+
+func TestClearCache(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	r.ResolveAddr("127.0.0.1")
+	r.ResolvePort(80, "tcp")
+
+	if r.GetCacheSize() == 0 {
+		t.Error("expected non-empty cache before clear")
+	}
+
+	r.ClearCache()
+
+	if r.GetCacheSize() != 0 {
+		t.Errorf("expected empty cache after clear, got %d", r.GetCacheSize())
+	}
+}
+
+func TestGetCacheSize(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	if r.GetCacheSize() != 0 {
+		t.Errorf("expected initial cache size 0, got %d", r.GetCacheSize())
+	}
+
+	r.ResolveAddr("127.0.0.1")
+	if r.GetCacheSize() != 1 {
+		t.Errorf("expected cache size 1, got %d", r.GetCacheSize())
+	}
+}
+
+func TestGetServiceName(t *testing.T) {
+	tests := []struct {
+		port     int
+		proto    string
+		expected string
+	}{
+		{80, "tcp", "http"},
+		{443, "tcp", "https"},
+		{22, "tcp", "ssh"},
+		{53, "tcp", "domain"},
+		{53, "udp", "domain"},
+		{12345, "tcp", ""},
+		{0, "tcp", ""},
+	}
+
+	for _, tt := range tests {
+		result := getServiceName(tt.port, tt.proto)
+		if result != tt.expected {
+			t.Errorf("getServiceName(%d, %q) = %q, want %q", tt.port, tt.proto, result, tt.expected)
+		}
+	}
+}
+
+func TestResolveAddrsParallel(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	addrs := []string{
+		"127.0.0.1",
+		"127.0.0.2",
+		"127.0.0.3",
+		"", // should be skipped
+		"*", // should be skipped
+	}
+
+	r.ResolveAddrsParallel(addrs)
+
+	// should have cached 3 addresses (excluding empty and *)
+	if r.GetCacheSize() != 3 {
+		t.Errorf("expected cache size 3, got %d", r.GetCacheSize())
+	}
+}
+
+func TestResolveAddrsParallel_Dedupe(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	addrs := []string{
+		"127.0.0.1",
+		"127.0.0.1",
+		"127.0.0.1",
+		"127.0.0.2",
+	}
+
+	r.ResolveAddrsParallel(addrs)
+
+	// should have cached 2 unique addresses
+	if r.GetCacheSize() != 2 {
+		t.Errorf("expected cache size 2, got %d", r.GetCacheSize())
+	}
+}
+
+func TestResolveAddrsParallel_SkipsCached(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	// pre-cache one address
+	r.ResolveAddr("127.0.0.1")
+
+	addrs := []string{
+		"127.0.0.1", // already cached
+		"127.0.0.2", // not cached
+	}
+
+	initialSize := r.GetCacheSize()
+	r.ResolveAddrsParallel(addrs)
+
+	// should have added 1 more
+	if r.GetCacheSize() != initialSize+1 {
+		t.Errorf("expected cache size %d, got %d", initialSize+1, r.GetCacheSize())
+	}
+}
+
+func TestResolveAddrsParallel_Empty(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	// should not panic with empty input
+	r.ResolveAddrsParallel([]string{})
+	r.ResolveAddrsParallel(nil)
+
+	if r.GetCacheSize() != 0 {
+		t.Errorf("expected cache size 0, got %d", r.GetCacheSize())
+	}
+}
+
+func TestGlobalResolver(t *testing.T) {
+	// reset global resolver
+	globalResolver = nil
+
+	r := GetGlobalResolver()
+	if r == nil {
+		t.Fatal("expected non-nil global resolver")
+	}
+
+	// should return same instance
+	r2 := GetGlobalResolver()
+	if r != r2 {
+		t.Error("expected same global resolver instance")
+	}
+}
+
+func TestSetGlobalResolver(t *testing.T) {
+	SetGlobalResolver(ResolverOptions{
+		Timeout: 500 * time.Millisecond,
+		NoCache: true,
+	})
+
+	r := GetGlobalResolver()
+	if r.timeout != 500*time.Millisecond {
+		t.Errorf("expected timeout 500ms, got %v", r.timeout)
+	}
+	if !r.noCache {
+		t.Error("expected noCache to be true")
+	}
+
+	// reset for other tests
+	globalResolver = nil
+}
+
+func TestSetGlobalResolver_DefaultTimeout(t *testing.T) {
+	SetGlobalResolver(ResolverOptions{
+		Timeout: 0, // should use default
+	})
+
+	r := GetGlobalResolver()
+	if r.timeout != 200*time.Millisecond {
+		t.Errorf("expected default timeout 200ms, got %v", r.timeout)
+	}
+
+	// reset for other tests
+	globalResolver = nil
+}
+
+func TestGlobalConvenienceFunctions(t *testing.T) {
+	globalResolver = nil
+
+	// test global ResolveAddr
+	result := ResolveAddr("127.0.0.1")
+	if result == "" {
+		t.Error("expected non-empty result from global ResolveAddr")
+	}
+
+	// test global ResolvePort
+	port := ResolvePort(80, "tcp")
+	if port != "http" {
+		t.Errorf("expected 'http', got %q", port)
+	}
+
+	// test global ResolveAddrPort
+	addr, portStr := ResolveAddrPort("127.0.0.1", 443, "tcp")
+	if addr == "" {
+		t.Error("expected non-empty address")
+	}
+	if portStr != "https" {
+		t.Errorf("expected 'https', got %q", portStr)
+	}
+
+	// test global SetNoCache
+	SetNoCache(true)
+	if !GetGlobalResolver().noCache {
+		t.Error("expected global noCache to be true")
+	}
+
+	// reset
+	globalResolver = nil
+}
+
+func TestConcurrentAccess(t *testing.T) {
+	r := New(100 * time.Millisecond)
+
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(1)
+		go func(n int) {
+			defer wg.Done()
+			addr := "127.0.0.1"
+			r.ResolveAddr(addr)
+			r.ResolvePort(80+n%10, "tcp")
+			r.GetCacheSize()
+		}(i)
+	}
+
+	wg.Wait()
+
+	// should not panic and cache should have entries
+	if r.GetCacheSize() == 0 {
+		t.Error("expected non-empty cache after concurrent access")
+	}
+}
+
+func TestResolveAddr_TrailingDot(t *testing.T) {
+	// this test verifies the trailing dot removal logic
+	// by checking the internal logic works correctly
+	r := New(100 * time.Millisecond)
+
+	// localhost should resolve and have trailing dot removed
+	result := r.ResolveAddr("127.0.0.1")
+	if len(result) > 0 && result[len(result)-1] == '.' {
+		t.Error("expected trailing dot to be removed")
+	}
+}
+

internal/state/state.go

@@ -0,0 +1,133 @@
+package state
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/karol-broda/snitch/internal/collector"
+)
+
+// TUIState holds view options that can be persisted between sessions
+type TUIState struct {
+	ShowTCP         bool                `json:"show_tcp"`
+	ShowUDP         bool                `json:"show_udp"`
+	ShowListening   bool                `json:"show_listening"`
+	ShowEstablished bool                `json:"show_established"`
+	ShowOther       bool                `json:"show_other"`
+	SortField       collector.SortField `json:"sort_field"`
+	SortReverse     bool                `json:"sort_reverse"`
+	ResolveAddrs    bool                `json:"resolve_addrs"`
+	ResolvePorts    bool                `json:"resolve_ports"`
+}
+
+var (
+	saveMu   sync.Mutex
+	saveChan chan TUIState
+	once     sync.Once
+)
+
+// Path returns the XDG-compliant state file path
+func Path() string {
+	stateDir := os.Getenv("XDG_STATE_HOME")
+	if stateDir == "" {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return ""
+		}
+		stateDir = filepath.Join(home, ".local", "state")
+	}
+	return filepath.Join(stateDir, "snitch", "tui.json")
+}
+
+// Load reads the TUI state from disk.
+// returns nil if state file doesn't exist or can't be read.
+func Load() *TUIState {
+	path := Path()
+	if path == "" {
+		return nil
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+
+	var state TUIState
+	if err := json.Unmarshal(data, &state); err != nil {
+		return nil
+	}
+
+	return &state
+}
+
+// Save writes the TUI state to disk synchronously.
+// creates parent directories if needed.
+func Save(state TUIState) error {
+	path := Path()
+	if path == "" {
+		return nil
+	}
+
+	saveMu.Lock()
+	defer saveMu.Unlock()
+
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+
+	data, err := json.MarshalIndent(state, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, data, 0644)
+}
+
+// SaveAsync queues a state save to happen in the background.
+// only the most recent state is saved if multiple saves are queued.
+func SaveAsync(state TUIState) {
+	once.Do(func() {
+		saveChan = make(chan TUIState, 1)
+		go saveWorker()
+	})
+
+	// non-blocking send, replace pending save with newer state
+	select {
+	case saveChan <- state:
+	default:
+		// channel full, drain and replace
+		select {
+		case <-saveChan:
+		default:
+		}
+		select {
+		case saveChan <- state:
+		default:
+		}
+	}
+}
+
+func saveWorker() {
+	for state := range saveChan {
+		_ = Save(state)
+	}
+}
+
+// Default returns a TUIState with default values
+func Default() TUIState {
+	return TUIState{
+		ShowTCP:         true,
+		ShowUDP:         true,
+		ShowListening:   true,
+		ShowEstablished: true,
+		ShowOther:       true,
+		SortField:       collector.SortByLport,
+		SortReverse:     false,
+		ResolveAddrs:    false,
+		ResolvePorts:    false,
+	}
+}
+

internal/state/state_test.go

@@ -0,0 +1,236 @@
+package state
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/karol-broda/snitch/internal/collector"
+)
+
+func TestPath_XDGStateHome(t *testing.T) {
+	t.Setenv("XDG_STATE_HOME", "/custom/state")
+	path := Path()
+
+	expected := "/custom/state/snitch/tui.json"
+	if path != expected {
+		t.Errorf("Path() = %q, want %q", path, expected)
+	}
+}
+
+func TestPath_DefaultFallback(t *testing.T) {
+	t.Setenv("XDG_STATE_HOME", "")
+	path := Path()
+
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skip("cannot determine home directory")
+	}
+
+	expected := filepath.Join(home, ".local", "state", "snitch", "tui.json")
+	if path != expected {
+		t.Errorf("Path() = %q, want %q", path, expected)
+	}
+}
+
+func TestDefault(t *testing.T) {
+	d := Default()
+
+	if d.ShowTCP != true {
+		t.Error("expected ShowTCP to be true")
+	}
+	if d.ShowUDP != true {
+		t.Error("expected ShowUDP to be true")
+	}
+	if d.ShowListening != true {
+		t.Error("expected ShowListening to be true")
+	}
+	if d.ShowEstablished != true {
+		t.Error("expected ShowEstablished to be true")
+	}
+	if d.ShowOther != true {
+		t.Error("expected ShowOther to be true")
+	}
+	if d.SortField != collector.SortByLport {
+		t.Errorf("expected SortField to be %q, got %q", collector.SortByLport, d.SortField)
+	}
+	if d.SortReverse != false {
+		t.Error("expected SortReverse to be false")
+	}
+	if d.ResolveAddrs != false {
+		t.Error("expected ResolveAddrs to be false")
+	}
+	if d.ResolvePorts != false {
+		t.Error("expected ResolvePorts to be false")
+	}
+}
+
+func TestSaveAndLoad(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	state := TUIState{
+		ShowTCP:         false,
+		ShowUDP:         true,
+		ShowListening:   true,
+		ShowEstablished: false,
+		ShowOther:       true,
+		SortField:       collector.SortByProcess,
+		SortReverse:     true,
+		ResolveAddrs:    true,
+		ResolvePorts:    false,
+	}
+
+	err := Save(state)
+	if err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+
+	// verify file was created
+	path := Path()
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		t.Fatal("expected state file to exist after Save()")
+	}
+
+	loaded := Load()
+	if loaded == nil {
+		t.Fatal("Load() returned nil")
+	}
+
+	if loaded.ShowTCP != state.ShowTCP {
+		t.Errorf("ShowTCP = %v, want %v", loaded.ShowTCP, state.ShowTCP)
+	}
+	if loaded.ShowUDP != state.ShowUDP {
+		t.Errorf("ShowUDP = %v, want %v", loaded.ShowUDP, state.ShowUDP)
+	}
+	if loaded.ShowListening != state.ShowListening {
+		t.Errorf("ShowListening = %v, want %v", loaded.ShowListening, state.ShowListening)
+	}
+	if loaded.ShowEstablished != state.ShowEstablished {
+		t.Errorf("ShowEstablished = %v, want %v", loaded.ShowEstablished, state.ShowEstablished)
+	}
+	if loaded.ShowOther != state.ShowOther {
+		t.Errorf("ShowOther = %v, want %v", loaded.ShowOther, state.ShowOther)
+	}
+	if loaded.SortField != state.SortField {
+		t.Errorf("SortField = %v, want %v", loaded.SortField, state.SortField)
+	}
+	if loaded.SortReverse != state.SortReverse {
+		t.Errorf("SortReverse = %v, want %v", loaded.SortReverse, state.SortReverse)
+	}
+	if loaded.ResolveAddrs != state.ResolveAddrs {
+		t.Errorf("ResolveAddrs = %v, want %v", loaded.ResolveAddrs, state.ResolveAddrs)
+	}
+	if loaded.ResolvePorts != state.ResolvePorts {
+		t.Errorf("ResolvePorts = %v, want %v", loaded.ResolvePorts, state.ResolvePorts)
+	}
+}
+
+func TestLoad_NonExistent(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	loaded := Load()
+	if loaded != nil {
+		t.Error("expected Load() to return nil for non-existent file")
+	}
+}
+
+func TestLoad_InvalidJSON(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	// create directory and invalid json file
+	stateDir := filepath.Join(tmpDir, "snitch")
+	if err := os.MkdirAll(stateDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	stateFile := filepath.Join(stateDir, "tui.json")
+	if err := os.WriteFile(stateFile, []byte("not valid json"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	loaded := Load()
+	if loaded != nil {
+		t.Error("expected Load() to return nil for invalid JSON")
+	}
+}
+
+func TestSave_CreatesDirectories(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	// snitch directory should not exist yet
+	snitchDir := filepath.Join(tmpDir, "snitch")
+	if _, err := os.Stat(snitchDir); err == nil {
+		t.Fatal("expected snitch directory to not exist initially")
+	}
+
+	err := Save(Default())
+	if err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+
+	// directory should now exist
+	if _, err := os.Stat(snitchDir); os.IsNotExist(err) {
+		t.Error("expected Save() to create parent directories")
+	}
+}
+
+func TestSaveAsync(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	state := TUIState{
+		ShowTCP:   false,
+		SortField: collector.SortByPID,
+	}
+
+	SaveAsync(state)
+
+	// wait for background save with timeout
+	deadline := time.Now().Add(100 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if loaded := Load(); loaded != nil {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	t.Log("SaveAsync may not have completed in time (non-fatal in CI)")
+}
+
+func TestTUIState_JSONRoundtrip(t *testing.T) {
+	// verify all sort fields serialize correctly
+	sortFields := []collector.SortField{
+		collector.SortByLport,
+		collector.SortByProcess,
+		collector.SortByPID,
+		collector.SortByState,
+		collector.SortByProto,
+	}
+
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	for _, sf := range sortFields {
+		state := TUIState{
+			ShowTCP:   true,
+			SortField: sf,
+		}
+
+		if err := Save(state); err != nil {
+			t.Fatalf("Save() error for %q: %v", sf, err)
+		}
+
+		loaded := Load()
+		if loaded == nil {
+			t.Fatalf("Load() returned nil for %q", sf)
+		}
+
+		if loaded.SortField != sf {
+			t.Errorf("SortField roundtrip failed: got %q, want %q", loaded.SortField, sf)
+		}
+	}
+}

internal/testutil/testutil.go

@@ -5,7 +5,8 @@ import (
 	"path/filepath"
 	"testing"
 
-	"snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 // TestCollector wraps MockCollector for use in tests
@@ -47,13 +48,13 @@ func SetupTestEnvironment(t *testing.T) (string, func()) {
 	oldConfig := os.Getenv("SNITCH_CONFIG")
 	oldNoColor := os.Getenv("SNITCH_NO_COLOR")
 	
-	os.Setenv("SNITCH_NO_COLOR", "1") // Disable colors in tests
+	errutil.Setenv("SNITCH_NO_COLOR", "1")
 	
 	// Cleanup function
 	cleanup := func() {
-		os.RemoveAll(tempDir)
-		os.Setenv("SNITCH_CONFIG", oldConfig)
-		os.Setenv("SNITCH_NO_COLOR", oldNoColor)
+		errutil.RemoveAll(tempDir)
+		errutil.Setenv("SNITCH_CONFIG", oldConfig)
+		errutil.Setenv("SNITCH_NO_COLOR", oldNoColor)
 	}
 	
 	return tempDir, cleanup
@@ -192,8 +193,8 @@ func (oc *OutputCapture) Stop() (string, string, error) {
 	os.Stderr = oc.oldStderr
 	
 	// Close files
-	oc.stdout.Close()
-	oc.stderr.Close()
+	errutil.Close(oc.stdout)
+	errutil.Close(oc.stderr)
 	
 	// Read captured content
 	stdoutContent, err := os.ReadFile(oc.stdoutFile)
@@ -207,9 +208,9 @@ func (oc *OutputCapture) Stop() (string, string, error) {
 	}
 	
 	// Cleanup
-	os.Remove(oc.stdoutFile)
-	os.Remove(oc.stderrFile)
-	os.Remove(filepath.Dir(oc.stdoutFile))
+	errutil.Remove(oc.stdoutFile)
+	errutil.Remove(oc.stderrFile)
+	errutil.Remove(filepath.Dir(oc.stdoutFile))
 	
 	return string(stdoutContent), string(stderrContent), nil
 }

internal/theme/ansi.go

@@ -0,0 +1,24 @@
+package theme
+
+// ANSI palette uses standard terminal colors (0-15)
+// this allows the theme to inherit from the user's terminal color scheme
+var paletteANSI = Palette{
+	Name: "ansi",
+
+	Fg:       "15", // bright white
+	FgMuted:  "7",  // white
+	FgSubtle: "8",  // bright black (gray)
+	Bg:       "0",  // black
+	BgMuted:  "0",  // black
+	Border:   "8",  // bright black (gray)
+
+	Red:     "1",  // red
+	Green:   "2",  // green
+	Yellow:  "3",  // yellow
+	Blue:    "4",  // blue
+	Magenta: "5",  // magenta
+	Cyan:    "6",  // cyan
+	Orange:  "3",  // yellow (ansi has no orange, fallback to yellow)
+	Gray:    "8",  // bright black
+}
+

internal/theme/catppuccin.go

@@ -0,0 +1,87 @@
+package theme
+
+// catppuccin mocha (dark)
+// https://github.com/catppuccin/catppuccin
+var paletteCatppuccinMocha = Palette{
+	Name: "catppuccin-mocha",
+
+	Fg:       "#cdd6f4", // text
+	FgMuted:  "#a6adc8", // subtext0
+	FgSubtle: "#6c7086", // overlay0
+	Bg:       "#1e1e2e", // base
+	BgMuted:  "#313244", // surface0
+	Border:   "#45475a", // surface1
+
+	Red:     "#f38ba8",
+	Green:   "#a6e3a1",
+	Yellow:  "#f9e2af",
+	Blue:    "#89b4fa",
+	Magenta: "#cba6f7", // mauve
+	Cyan:    "#94e2d5", // teal
+	Orange:  "#fab387", // peach
+	Gray:    "#585b70", // surface2
+}
+
+// catppuccin macchiato (medium-dark)
+var paletteCatppuccinMacchiato = Palette{
+	Name: "catppuccin-macchiato",
+
+	Fg:       "#cad3f5", // text
+	FgMuted:  "#a5adcb", // subtext0
+	FgSubtle: "#6e738d", // overlay0
+	Bg:       "#24273a", // base
+	BgMuted:  "#363a4f", // surface0
+	Border:   "#494d64", // surface1
+
+	Red:     "#ed8796",
+	Green:   "#a6da95",
+	Yellow:  "#eed49f",
+	Blue:    "#8aadf4",
+	Magenta: "#c6a0f6", // mauve
+	Cyan:    "#8bd5ca", // teal
+	Orange:  "#f5a97f", // peach
+	Gray:    "#5b6078", // surface2
+}
+
+// catppuccin frappe (medium)
+var paletteCatppuccinFrappe = Palette{
+	Name: "catppuccin-frappe",
+
+	Fg:       "#c6d0f5", // text
+	FgMuted:  "#a5adce", // subtext0
+	FgSubtle: "#737994", // overlay0
+	Bg:       "#303446", // base
+	BgMuted:  "#414559", // surface0
+	Border:   "#51576d", // surface1
+
+	Red:     "#e78284",
+	Green:   "#a6d189",
+	Yellow:  "#e5c890",
+	Blue:    "#8caaee",
+	Magenta: "#ca9ee6", // mauve
+	Cyan:    "#81c8be", // teal
+	Orange:  "#ef9f76", // peach
+	Gray:    "#626880", // surface2
+}
+
+// catppuccin latte (light)
+var paletteCatppuccinLatte = Palette{
+	Name: "catppuccin-latte",
+
+	Fg:       "#4c4f69", // text
+	FgMuted:  "#6c6f85", // subtext0
+	FgSubtle: "#9ca0b0", // overlay0
+	Bg:       "#eff1f5", // base
+	BgMuted:  "#ccd0da", // surface0
+	Border:   "#bcc0cc", // surface1
+
+	Red:     "#d20f39",
+	Green:   "#40a02b",
+	Yellow:  "#df8e1d",
+	Blue:    "#1e66f5",
+	Magenta: "#8839ef", // mauve
+	Cyan:    "#179299", // teal
+	Orange:  "#fe640b", // peach
+	Gray:    "#acb0be", // surface2
+}
+

internal/theme/dracula.go

@@ -0,0 +1,24 @@
+package theme
+
+// dracula theme
+// https://draculatheme.com/
+var paletteDracula = Palette{
+	Name: "dracula",
+
+	Fg:       "#f8f8f2", // foreground
+	FgMuted:  "#f8f8f2", // foreground
+	FgSubtle: "#6272a4", // comment
+	Bg:       "#282a36", // background
+	BgMuted:  "#44475a", // selection
+	Border:   "#44475a", // selection
+
+	Red:     "#ff5555",
+	Green:   "#50fa7b",
+	Yellow:  "#f1fa8c",
+	Blue:    "#6272a4", // dracula uses comment color for blue tones
+	Magenta: "#bd93f9", // purple
+	Cyan:    "#8be9fd",
+	Orange:  "#ffb86c",
+	Gray:    "#6272a4", // comment
+}
+

internal/theme/gruvbox.go

@@ -0,0 +1,45 @@
+package theme
+
+// gruvbox dark
+// https://github.com/morhetz/gruvbox
+var paletteGruvboxDark = Palette{
+	Name: "gruvbox-dark",
+
+	Fg:       "#ebdbb2", // fg
+	FgMuted:  "#d5c4a1", // fg2
+	FgSubtle: "#a89984", // fg4
+	Bg:       "#282828", // bg
+	BgMuted:  "#3c3836", // bg1
+	Border:   "#504945", // bg2
+
+	Red:     "#fb4934",
+	Green:   "#b8bb26",
+	Yellow:  "#fabd2f",
+	Blue:    "#83a598",
+	Magenta: "#d3869b", // purple
+	Cyan:    "#8ec07c", // aqua
+	Orange:  "#fe8019",
+	Gray:    "#928374",
+}
+
+// gruvbox light
+var paletteGruvboxLight = Palette{
+	Name: "gruvbox-light",
+
+	Fg:       "#3c3836", // fg
+	FgMuted:  "#504945", // fg2
+	FgSubtle: "#7c6f64", // fg4
+	Bg:       "#fbf1c7", // bg
+	BgMuted:  "#ebdbb2", // bg1
+	Border:   "#d5c4a1", // bg2
+
+	Red:     "#cc241d",
+	Green:   "#98971a",
+	Yellow:  "#d79921",
+	Blue:    "#458588",
+	Magenta: "#b16286", // purple
+	Cyan:    "#689d6a", // aqua
+	Orange:  "#d65d0e",
+	Gray:    "#928374",
+}
+

internal/theme/mono.go

@@ -0,0 +1,49 @@
+package theme
+
+import "github.com/charmbracelet/lipgloss"
+
+// createMonoTheme creates a monochrome theme (no colors)
+// useful for accessibility, piping output, or minimal terminals
+func createMonoTheme() *Theme {
+	baseStyle := lipgloss.NewStyle()
+	boldStyle := lipgloss.NewStyle().Bold(true)
+
+	return &Theme{
+		Name: "mono",
+		Styles: Styles{
+			Header:     boldStyle,
+			Border:     baseStyle,
+			Selected:   boldStyle,
+			Watched:    boldStyle,
+			Normal:     baseStyle,
+			Error:      boldStyle,
+			Success:    boldStyle,
+			Warning:    boldStyle,
+			Footer:     baseStyle,
+			Background: baseStyle,
+
+			Proto: ProtoStyles{
+				TCP:  baseStyle,
+				UDP:  baseStyle,
+				Unix: baseStyle,
+				TCP6: baseStyle,
+				UDP6: baseStyle,
+			},
+
+			State: StateStyles{
+				Listen:      baseStyle,
+				Established: baseStyle,
+				TimeWait:    baseStyle,
+				CloseWait:   baseStyle,
+				SynSent:     baseStyle,
+				SynRecv:     baseStyle,
+				FinWait1:    baseStyle,
+				FinWait2:    baseStyle,
+				Closing:     baseStyle,
+				LastAck:     baseStyle,
+				Closed:      baseStyle,
+			},
+		},
+	}
+}
+

internal/theme/nord.go

@@ -0,0 +1,24 @@
+package theme
+
+// nord theme
+// https://www.nordtheme.com/
+var paletteNord = Palette{
+	Name: "nord",
+
+	Fg:       "#eceff4", // snow storm - nord6
+	FgMuted:  "#d8dee9", // snow storm - nord4
+	FgSubtle: "#4c566a", // polar night - nord3
+	Bg:       "#2e3440", // polar night - nord0
+	BgMuted:  "#3b4252", // polar night - nord1
+	Border:   "#434c5e", // polar night - nord2
+
+	Red:     "#bf616a", // aurora - nord11
+	Green:   "#a3be8c", // aurora - nord14
+	Yellow:  "#ebcb8b", // aurora - nord13
+	Blue:    "#81a1c1", // frost - nord9
+	Magenta: "#b48ead", // aurora - nord15
+	Cyan:    "#88c0d0", // frost - nord8
+	Orange:  "#d08770", // aurora - nord12
+	Gray:    "#4c566a", // polar night - nord3
+}
+

internal/theme/one_dark.go

@@ -0,0 +1,24 @@
+package theme
+
+// one dark theme (atom editor)
+// https://github.com/atom/atom/tree/master/packages/one-dark-syntax
+var paletteOneDark = Palette{
+	Name: "one-dark",
+
+	Fg:       "#abb2bf", // foreground
+	FgMuted:  "#9da5b4", // foreground muted
+	FgSubtle: "#5c6370", // comment
+	Bg:       "#282c34", // background
+	BgMuted:  "#21252b", // gutter background
+	Border:   "#3e4451", // selection
+
+	Red:     "#e06c75",
+	Green:   "#98c379",
+	Yellow:  "#e5c07b",
+	Blue:    "#61afef",
+	Magenta: "#c678dd", // purple
+	Cyan:    "#56b6c2",
+	Orange:  "#d19a66",
+	Gray:    "#5c6370", // comment
+}
+

internal/theme/palette.go

@@ -0,0 +1,111 @@
+package theme
+
+import (
+	"strconv"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+// Palette defines the semantic colors for a theme
+type Palette struct {
+	Name string
+
+	// base colors
+	Fg       string // primary foreground
+	FgMuted  string // secondary/muted foreground
+	FgSubtle string // subtle/disabled foreground
+	Bg       string // primary background
+	BgMuted  string // secondary background (selections, highlights)
+	Border   string // border color
+
+	// semantic colors
+	Red     string
+	Green   string
+	Yellow  string
+	Blue    string
+	Magenta string
+	Cyan    string
+	Orange  string
+	Gray    string
+}
+
+// Color converts a palette color string to a lipgloss.TerminalColor.
+// If the string is 1-2 characters, it's treated as an ANSI color code.
+// Otherwise, it's treated as a hex color.
+func (p *Palette) Color(c string) lipgloss.TerminalColor {
+	if c == "" {
+		return lipgloss.NoColor{}
+	}
+
+	if len(c) <= 2 {
+		n, err := strconv.Atoi(c)
+		if err == nil {
+			return lipgloss.ANSIColor(n)
+		}
+	}
+
+	return lipgloss.Color(c)
+}
+
+// ToTheme converts a Palette to a Theme with lipgloss styles
+func (p *Palette) ToTheme() *Theme {
+	return &Theme{
+		Name: p.Name,
+		Styles: Styles{
+			Header: lipgloss.NewStyle().
+				Bold(true).
+				Foreground(p.Color(p.Fg)),
+
+			Border: lipgloss.NewStyle().
+				Foreground(p.Color(p.Border)),
+
+			Selected: lipgloss.NewStyle().
+				Bold(true).
+				Foreground(p.Color(p.Fg)),
+
+			Watched: lipgloss.NewStyle().
+				Bold(true).
+				Foreground(p.Color(p.Orange)),
+
+			Normal: lipgloss.NewStyle().
+				Foreground(p.Color(p.FgMuted)),
+
+			Error: lipgloss.NewStyle().
+				Foreground(p.Color(p.Red)),
+
+			Success: lipgloss.NewStyle().
+				Foreground(p.Color(p.Green)),
+
+			Warning: lipgloss.NewStyle().
+				Foreground(p.Color(p.Yellow)),
+
+			Footer: lipgloss.NewStyle().
+				Foreground(p.Color(p.FgSubtle)),
+
+			Background: lipgloss.NewStyle(),
+
+			Proto: ProtoStyles{
+				TCP:  lipgloss.NewStyle().Foreground(p.Color(p.Green)),
+				UDP:  lipgloss.NewStyle().Foreground(p.Color(p.Magenta)),
+				Unix: lipgloss.NewStyle().Foreground(p.Color(p.Gray)),
+				TCP6: lipgloss.NewStyle().Foreground(p.Color(p.Cyan)),
+				UDP6: lipgloss.NewStyle().Foreground(p.Color(p.Blue)),
+			},
+
+			State: StateStyles{
+				Listen:      lipgloss.NewStyle().Foreground(p.Color(p.Green)),
+				Established: lipgloss.NewStyle().Foreground(p.Color(p.Blue)),
+				TimeWait:    lipgloss.NewStyle().Foreground(p.Color(p.Yellow)),
+				CloseWait:   lipgloss.NewStyle().Foreground(p.Color(p.Orange)),
+				SynSent:     lipgloss.NewStyle().Foreground(p.Color(p.Magenta)),
+				SynRecv:     lipgloss.NewStyle().Foreground(p.Color(p.Magenta)),
+				FinWait1:    lipgloss.NewStyle().Foreground(p.Color(p.Red)),
+				FinWait2:    lipgloss.NewStyle().Foreground(p.Color(p.Red)),
+				Closing:     lipgloss.NewStyle().Foreground(p.Color(p.Red)),
+				LastAck:     lipgloss.NewStyle().Foreground(p.Color(p.Red)),
+				Closed:      lipgloss.NewStyle().Foreground(p.Color(p.Gray)),
+			},
+		},
+	}
+}
+

internal/theme/readme.md

@@ -0,0 +1,14 @@
+# theme Palettes
+
+the color palettes in this directory were generated by an LLM agent (Claude Opus 4.5) using web search to fetch the official color specifications from each themes documentation
+as it is with llm agents its possible the colors may be wrong
+
+Sources:
+- [Catppuccin](https://github.com/catppuccin/catppuccin)
+- [Dracula](https://draculatheme.com/)
+- [Gruvbox](https://github.com/morhetz/gruvbox)
+- [Nord](https://www.nordtheme.com/)
+- [One Dark](https://github.com/atom/one-dark-syntax)
+- [Solarized](https://ethanschoonover.com/solarized/)
+- [Tokyo Night](https://github.com/enkia/tokyo-night-vscode-theme)
+

internal/theme/solarized.go

@@ -0,0 +1,45 @@
+package theme
+
+// solarized dark theme
+// https://ethanschoonover.com/solarized/
+var paletteSolarizedDark = Palette{
+	Name: "solarized-dark",
+
+	Fg:       "#839496", // base0
+	FgMuted:  "#93a1a1", // base1
+	FgSubtle: "#586e75", // base01
+	Bg:       "#002b36", // base03
+	BgMuted:  "#073642", // base02
+	Border:   "#073642", // base02
+
+	Red:     "#dc322f",
+	Green:   "#859900",
+	Yellow:  "#b58900",
+	Blue:    "#268bd2",
+	Magenta: "#d33682",
+	Cyan:    "#2aa198",
+	Orange:  "#cb4b16",
+	Gray:    "#657b83", // base00
+}
+
+// solarized light theme
+var paletteSolarizedLight = Palette{
+	Name: "solarized-light",
+
+	Fg:       "#657b83", // base00
+	FgMuted:  "#586e75", // base01
+	FgSubtle: "#93a1a1", // base1
+	Bg:       "#fdf6e3", // base3
+	BgMuted:  "#eee8d5", // base2
+	Border:   "#eee8d5", // base2
+
+	Red:     "#dc322f",
+	Green:   "#859900",
+	Yellow:  "#b58900",
+	Blue:    "#268bd2",
+	Magenta: "#d33682",
+	Cyan:    "#2aa198",
+	Orange:  "#cb4b16",
+	Gray:    "#839496", // base0
+}
+

internal/theme/theme.go

@@ -1,6 +1,7 @@
 package theme
 
 import (
+	"sort"
 	"strings"
 
 	"github.com/charmbracelet/lipgloss"
@@ -52,152 +53,73 @@ type StateStyles struct {
 	Closed      lipgloss.Style
 }
 
-var (
-	themes map[string]*Theme
-)
+var themes map[string]*Theme
 
 func init() {
-	themes = map[string]*Theme{
-		"default": createAdaptiveTheme(),
-		"mono":    createMonoTheme(),
-	}
+	themes = make(map[string]*Theme)
+
+	// ansi theme (default) - inherits from terminal colors
+	themes["ansi"] = paletteANSI.ToTheme()
+
+	// catppuccin variants
+	themes["catppuccin-mocha"] = paletteCatppuccinMocha.ToTheme()
+	themes["catppuccin-macchiato"] = paletteCatppuccinMacchiato.ToTheme()
+	themes["catppuccin-frappe"] = paletteCatppuccinFrappe.ToTheme()
+	themes["catppuccin-latte"] = paletteCatppuccinLatte.ToTheme()
+
+	// gruvbox variants
+	themes["gruvbox-dark"] = paletteGruvboxDark.ToTheme()
+	themes["gruvbox-light"] = paletteGruvboxLight.ToTheme()
+
+	// dracula
+	themes["dracula"] = paletteDracula.ToTheme()
+
+	// nord
+	themes["nord"] = paletteNord.ToTheme()
+
+	// tokyo night variants
+	themes["tokyo-night"] = paletteTokyoNight.ToTheme()
+	themes["tokyo-night-storm"] = paletteTokyoNightStorm.ToTheme()
+	themes["tokyo-night-light"] = paletteTokyoNightLight.ToTheme()
+
+	// solarized variants
+	themes["solarized-dark"] = paletteSolarizedDark.ToTheme()
+	themes["solarized-light"] = paletteSolarizedLight.ToTheme()
+
+	// one dark
+	themes["one-dark"] = paletteOneDark.ToTheme()
+
+	// monochrome (no colors)
+	themes["mono"] = createMonoTheme()
 }
 
-// GetTheme returns a theme by name, with auto-detection support
+// DefaultTheme is the theme used when none is specified
+const DefaultTheme = "ansi"
+
+// GetTheme returns a theme by name
 func GetTheme(name string) *Theme {
-	if name == "auto" {
-		// lipgloss handles adaptive colors, so we just return the default
-		return themes["default"]
+	if name == "" || name == "auto" || name == "default" {
+		return themes[DefaultTheme]
 	}
 
 	if theme, exists := themes[name]; exists {
 		return theme
 	}
 
-	// a specific theme was requested (e.g. "dark", "light"), but we now use adaptive
-	// so we can just return the default theme and lipgloss will handle it
-	if name == "dark" || name == "light" {
-		return themes["default"]
-	}
-
 	// fallback to default
-	return themes["default"]
+	return themes[DefaultTheme]
 }
 
-// ListThemes returns available theme names
+// ListThemes returns available theme names sorted alphabetically
 func ListThemes() []string {
-	var names []string
+	names := make([]string, 0, len(themes))
 	for name := range themes {
 		names = append(names, name)
 	}
+	sort.Strings(names)
 	return names
 }
 
-// createAdaptiveTheme creates a clean, minimal theme
-func createAdaptiveTheme() *Theme {
-	return &Theme{
-		Name: "default",
-		Styles: Styles{
-			Header: lipgloss.NewStyle().
-				Bold(true).
-				Foreground(lipgloss.AdaptiveColor{Light: "#1F2937", Dark: "#F9FAFB"}),
-
-			Watched: lipgloss.NewStyle().
-				Bold(true).
-				Foreground(lipgloss.AdaptiveColor{Light: "#D97706", Dark: "#F59E0B"}),
-
-			Border: lipgloss.NewStyle().
-				Foreground(lipgloss.AdaptiveColor{Light: "#D1D5DB", Dark: "#374151"}),
-
-			Selected: lipgloss.NewStyle().
-				Bold(true).
-				Foreground(lipgloss.AdaptiveColor{Light: "#1F2937", Dark: "#F9FAFB"}),
-
-			Normal: lipgloss.NewStyle().
-				Foreground(lipgloss.AdaptiveColor{Light: "#6B7280", Dark: "#9CA3AF"}),
-
-			Error: lipgloss.NewStyle().
-				Foreground(lipgloss.AdaptiveColor{Light: "#DC2626", Dark: "#F87171"}),
-
-			Success: lipgloss.NewStyle().
-				Foreground(lipgloss.AdaptiveColor{Light: "#059669", Dark: "#34D399"}),
-
-			Warning: lipgloss.NewStyle().
-				Foreground(lipgloss.AdaptiveColor{Light: "#D97706", Dark: "#FBBF24"}),
-
-			Footer: lipgloss.NewStyle().
-				Foreground(lipgloss.AdaptiveColor{Light: "#9CA3AF", Dark: "#6B7280"}),
-
-			Background: lipgloss.NewStyle(),
-
-			Proto: ProtoStyles{
-				TCP:  lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#059669", Dark: "#34D399"}),
-				UDP:  lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#7C3AED", Dark: "#A78BFA"}),
-				Unix: lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#6B7280", Dark: "#9CA3AF"}),
-				TCP6: lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#059669", Dark: "#34D399"}),
-				UDP6: lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#7C3AED", Dark: "#A78BFA"}),
-			},
-
-			State: StateStyles{
-				Listen:      lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#059669", Dark: "#34D399"}),
-				Established: lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#2563EB", Dark: "#60A5FA"}),
-				TimeWait:    lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#D97706", Dark: "#FBBF24"}),
-				CloseWait:   lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#D97706", Dark: "#FBBF24"}),
-				SynSent:     lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#7C3AED", Dark: "#A78BFA"}),
-				SynRecv:     lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#7C3AED", Dark: "#A78BFA"}),
-				FinWait1:    lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#DC2626", Dark: "#F87171"}),
-				FinWait2:    lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#DC2626", Dark: "#F87171"}),
-				Closing:     lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#DC2626", Dark: "#F87171"}),
-				LastAck:     lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#DC2626", Dark: "#F87171"}),
-				Closed:      lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#9CA3AF", Dark: "#6B7280"}),
-			},
-		},
-	}
-}
-
-// createMonoTheme creates a monochrome theme (no colors)
-func createMonoTheme() *Theme {
-	baseStyle := lipgloss.NewStyle()
-	boldStyle := lipgloss.NewStyle().Bold(true)
-
-	return &Theme{
-		Name: "mono",
-		Styles: Styles{
-			Header:     boldStyle,
-			Border:     baseStyle,
-			Selected:   boldStyle,
-			Normal:     baseStyle,
-			Error:      boldStyle,
-			Success:    boldStyle,
-			Warning:    boldStyle,
-			Footer:     baseStyle,
-			Background: baseStyle,
-
-			Proto: ProtoStyles{
-				TCP:  baseStyle,
-				UDP:  baseStyle,
-				Unix: baseStyle,
-				TCP6: baseStyle,
-				UDP6: baseStyle,
-			},
-
-			State: StateStyles{
-				Listen:      baseStyle,
-				Established: baseStyle,
-				TimeWait:    baseStyle,
-				CloseWait:   baseStyle,
-				SynSent:     baseStyle,
-				SynRecv:     baseStyle,
-				FinWait1:    baseStyle,
-				FinWait2:    baseStyle,
-				Closing:     baseStyle,
-				LastAck:     baseStyle,
-				Closed:      baseStyle,
-			},
-		},
-	}
-}
-
 // GetProtoStyle returns the appropriate style for a protocol
 func (s *Styles) GetProtoStyle(proto string) lipgloss.Style {
 	switch strings.ToLower(proto) {

internal/theme/tokyo_night.go

@@ -0,0 +1,66 @@
+package theme
+
+// tokyo night theme
+// https://github.com/enkia/tokyo-night-vscode-theme
+var paletteTokyoNight = Palette{
+	Name: "tokyo-night",
+
+	Fg:       "#c0caf5", // foreground
+	FgMuted:  "#a9b1d6", // foreground dark
+	FgSubtle: "#565f89", // comment
+	Bg:       "#1a1b26", // background
+	BgMuted:  "#24283b", // background highlight
+	Border:   "#414868", // border
+
+	Red:     "#f7768e",
+	Green:   "#9ece6a",
+	Yellow:  "#e0af68",
+	Blue:    "#7aa2f7",
+	Magenta: "#bb9af7", // purple
+	Cyan:    "#7dcfff",
+	Orange:  "#ff9e64",
+	Gray:    "#565f89", // comment
+}
+
+// tokyo night storm variant
+var paletteTokyoNightStorm = Palette{
+	Name: "tokyo-night-storm",
+
+	Fg:       "#c0caf5", // foreground
+	FgMuted:  "#a9b1d6", // foreground dark
+	FgSubtle: "#565f89", // comment
+	Bg:       "#24283b", // background (storm is slightly lighter)
+	BgMuted:  "#1f2335", // background dark
+	Border:   "#414868", // border
+
+	Red:     "#f7768e",
+	Green:   "#9ece6a",
+	Yellow:  "#e0af68",
+	Blue:    "#7aa2f7",
+	Magenta: "#bb9af7", // purple
+	Cyan:    "#7dcfff",
+	Orange:  "#ff9e64",
+	Gray:    "#565f89", // comment
+}
+
+// tokyo night light variant
+var paletteTokyoNightLight = Palette{
+	Name: "tokyo-night-light",
+
+	Fg:       "#343b58", // foreground
+	FgMuted:  "#565a6e", // foreground dark
+	FgSubtle: "#9699a3", // comment
+	Bg:       "#d5d6db", // background
+	BgMuted:  "#cbccd1", // background highlight
+	Border:   "#b4b5b9", // border
+
+	Red:     "#8c4351",
+	Green:   "#485e30",
+	Yellow:  "#8f5e15",
+	Blue:    "#34548a",
+	Magenta: "#5a4a78", // purple
+	Cyan:    "#0f4b6e",
+	Orange:  "#965027",
+	Gray:    "#9699a3", // comment
+}
+

internal/tui/helpers.go

@@ -1,9 +1,8 @@
 package tui
 
 import (
-	"fmt"
 	"regexp"
-	"snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/collector"
 	"strings"
 )
 
@@ -14,7 +13,7 @@ func truncate(s string, max int) string {
 	if max <= 2 {
 		return s[:max]
 	}
-	return s[:max-1] + "…"
+	return s[:max-1] + SymbolEllipsis
 }
 
 var ansiRegex = regexp.MustCompile(`\x1b\[[0-9;]*m`)
@@ -44,10 +43,3 @@ func sortFieldLabel(f collector.SortField) string {
 	}
 }
 
-func formatRemote(addr string, port int) string {
-	if addr == "" || addr == "*" || port == 0 {
-		return "-"
-	}
-	return fmt.Sprintf("%s:%d", addr, port)
-}
-

internal/tui/keys.go

@@ -1,7 +1,9 @@
 package tui
 
 import (
-	"snitch/internal/collector"
+	"fmt"
+	"github.com/karol-broda/snitch/internal/collector"
+	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
 )
@@ -12,6 +14,11 @@ func (m model) handleKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		return m.handleSearchKey(msg)
 	}
 
+	// kill confirmation dialog
+	if m.showKillConfirm {
+		return m.handleKillConfirmKey(msg)
+	}
+
 	// detail view only allows closing
 	if m.showDetail {
 		return m.handleDetailKey(msg)
@@ -62,6 +69,25 @@ func (m model) handleHelpKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	return m, nil
 }
 
+func (m model) handleKillConfirmKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
+	switch msg.String() {
+	case "y", "Y":
+		if m.killTarget != nil && m.killTarget.PID > 0 {
+			pid := m.killTarget.PID
+			process := m.killTarget.Process
+			m.showKillConfirm = false
+			m.killTarget = nil
+			return m, killProcess(pid, process)
+		}
+		m.showKillConfirm = false
+		m.killTarget = nil
+	case "n", "N", "esc", "q":
+		m.showKillConfirm = false
+		m.killTarget = nil
+	}
+	return m, nil
+}
+
 func (m model) handleNormalKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	switch msg.String() {
 	case "q", "ctrl+c":
@@ -92,31 +118,39 @@ func (m model) handleNormalKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	case "t":
 		m.showTCP = !m.showTCP
 		m.clampCursor()
+		m.saveState()
 	case "u":
 		m.showUDP = !m.showUDP
 		m.clampCursor()
+		m.saveState()
 	case "l":
 		m.showListening = !m.showListening
 		m.clampCursor()
+		m.saveState()
 	case "e":
 		m.showEstablished = !m.showEstablished
 		m.clampCursor()
+		m.saveState()
 	case "o":
 		m.showOther = !m.showOther
 		m.clampCursor()
+		m.saveState()
 	case "a":
 		m.showTCP = true
 		m.showUDP = true
 		m.showListening = true
 		m.showEstablished = true
 		m.showOther = true
+		m.saveState()
 
 	// sorting
 	case "s":
 		m.cycleSort()
+		m.saveState()
 	case "S":
 		m.sortReverse = !m.sortReverse
 		m.applySorting()
+		m.saveState()
 
 	// search
 	case "/":
@@ -135,6 +169,79 @@ func (m model) handleNormalKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		return m, m.fetchData()
 	case "?":
 		m.showHelp = true
+
+	// watch/monitor process
+	case "w":
+		visible := m.visibleConnections()
+		if m.cursor < len(visible) {
+			conn := visible[m.cursor]
+			if conn.PID > 0 {
+				wasWatched := m.isWatched(conn.PID)
+				m.toggleWatch(conn.PID)
+
+				// count connections for this pid
+				connCount := 0
+				for _, c := range m.connections {
+					if c.PID == conn.PID {
+						connCount++
+					}
+				}
+
+				if wasWatched {
+					m.statusMessage = fmt.Sprintf("unwatched %s (pid %d)", conn.Process, conn.PID)
+				} else if connCount > 1 {
+					m.statusMessage = fmt.Sprintf("watching %s (pid %d) - %d connections", conn.Process, conn.PID, connCount)
+				} else {
+					m.statusMessage = fmt.Sprintf("watching %s (pid %d)", conn.Process, conn.PID)
+				}
+				m.statusExpiry = time.Now().Add(2 * time.Second)
+				return m, clearStatusAfter(2 * time.Second)
+			}
+		}
+	case "W":
+		// clear all watched
+		count := len(m.watchedPIDs)
+		m.watchedPIDs = make(map[int]bool)
+		if count > 0 {
+			m.statusMessage = fmt.Sprintf("cleared %d watched processes", count)
+			m.statusExpiry = time.Now().Add(2 * time.Second)
+			return m, clearStatusAfter(2 * time.Second)
+		}
+
+	// kill process
+	case "K":
+		visible := m.visibleConnections()
+		if m.cursor < len(visible) {
+			conn := visible[m.cursor]
+			if conn.PID > 0 {
+				m.killTarget = &conn
+				m.showKillConfirm = true
+			}
+		}
+
+	// toggle address resolution
+	case "n":
+		m.resolveAddrs = !m.resolveAddrs
+		if m.resolveAddrs {
+			m.statusMessage = "address resolution: on"
+		} else {
+			m.statusMessage = "address resolution: off"
+		}
+		m.statusExpiry = time.Now().Add(2 * time.Second)
+		m.saveState()
+		return m, clearStatusAfter(2 * time.Second)
+
+	// toggle port resolution
+	case "N":
+		m.resolvePorts = !m.resolvePorts
+		if m.resolvePorts {
+			m.statusMessage = "port resolution: on"
+		} else {
+			m.statusMessage = "port resolution: off"
+		}
+		m.statusExpiry = time.Now().Add(2 * time.Second)
+		m.saveState()
+		return m, clearStatusAfter(2 * time.Second)
 	}
 
 	return m, nil

internal/tui/messages.go

@@ -1,7 +1,10 @@
 package tui
 
 import (
-	"snitch/internal/collector"
+	"fmt"
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/resolver"
+	"syscall"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
@@ -17,6 +20,15 @@ type errMsg struct {
 	err error
 }
 
+type killResultMsg struct {
+	pid     int
+	process string
+	success bool
+	err     error
+}
+
+type clearStatusMsg struct{}
+
 func (m model) tick() tea.Cmd {
 	return tea.Tick(m.interval, func(t time.Time) tea.Msg {
 		return tickMsg(t)
@@ -24,12 +36,58 @@ func (m model) tick() tea.Cmd {
 }
 
 func (m model) fetchData() tea.Cmd {
+	resolveAddrs := m.resolveAddrs
 	return func() tea.Msg {
 		conns, err := collector.GetConnections()
 		if err != nil {
 			return errMsg{err}
 		}
+		// pre-warm dns cache in parallel if resolution is enabled
+		if resolveAddrs {
+			addrs := make([]string, 0, len(conns)*2)
+			for _, c := range conns {
+				addrs = append(addrs, c.Laddr, c.Raddr)
+			}
+			resolver.ResolveAddrsParallel(addrs)
+		}
 		return dataMsg{connections: conns}
 	}
 }
 
+func killProcess(pid int, process string) tea.Cmd {
+	return func() tea.Msg {
+		if pid <= 0 {
+			return killResultMsg{
+				pid:     pid,
+				process: process,
+				success: false,
+				err:     fmt.Errorf("invalid pid"),
+			}
+		}
+
+		// send SIGTERM first (graceful shutdown)
+		err := syscall.Kill(pid, syscall.SIGTERM)
+		if err != nil {
+			return killResultMsg{
+				pid:     pid,
+				process: process,
+				success: false,
+				err:     err,
+			}
+		}
+
+		return killResultMsg{
+			pid:     pid,
+			process: process,
+			success: true,
+			err:     nil,
+		}
+	}
+}
+
+func clearStatusAfter(d time.Duration) tea.Cmd {
+	return tea.Tick(d, func(t time.Time) tea.Msg {
+		return clearStatusMsg{}
+	})
+}
+

internal/tui/model.go

@@ -1,11 +1,14 @@
 package tui
 
 import (
-	"snitch/internal/collector"
-	"snitch/internal/theme"
+	"fmt"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
+
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/state"
+	"github.com/karol-broda/snitch/internal/theme"
 )
 
 type model struct {
@@ -27,6 +30,10 @@ type model struct {
 	sortField   collector.SortField
 	sortReverse bool
 
+	// display options
+	resolveAddrs bool // when true, resolve IP addresses to hostnames
+	resolvePorts bool // when true, resolve port numbers to service names
+
 	// ui state
 	theme       *theme.Theme
 	showHelp    bool
@@ -35,6 +42,20 @@ type model struct {
 	interval    time.Duration
 	lastRefresh time.Time
 	err         error
+
+	// watched processes
+	watchedPIDs map[int]bool
+
+	// kill confirmation
+	showKillConfirm bool
+	killTarget      *collector.Connection
+
+	// status message (temporary feedback)
+	statusMessage string
+	statusExpiry  time.Time
+
+	// state persistence
+	rememberState bool
 }
 
 type Options struct {
@@ -46,6 +67,10 @@ type Options struct {
 	Established   bool
 	Other         bool
 	FilterSet     bool // true if user specified any filter flags
+	ResolveAddrs  bool // when true, resolve IP addresses to hostnames
+	ResolvePorts  bool // when true, resolve port numbers to service names
+	NoCache       bool // when true, disable DNS caching
+	RememberState bool // when true, persist view options between sessions
 }
 
 func New(opts Options) model {
@@ -60,8 +85,27 @@ func New(opts Options) model {
 	showListening := true
 	showEstablished := true
 	showOther := true
+	sortField := collector.SortByLport
+	sortReverse := false
+	resolveAddrs := opts.ResolveAddrs
+	resolvePorts := opts.ResolvePorts
 
-	// if user specified filters, use those instead
+	// load saved state if enabled and no CLI filter flags were specified
+	if opts.RememberState && !opts.FilterSet {
+		if saved := state.Load(); saved != nil {
+			showTCP = saved.ShowTCP
+			showUDP = saved.ShowUDP
+			showListening = saved.ShowListening
+			showEstablished = saved.ShowEstablished
+			showOther = saved.ShowOther
+			sortField = saved.SortField
+			sortReverse = saved.SortReverse
+			resolveAddrs = saved.ResolveAddrs
+			resolvePorts = saved.ResolvePorts
+		}
+	}
+
+	// if user specified filters, use those instead (CLI flags take precedence)
 	if opts.FilterSet {
 		showTCP = opts.TCP
 		showUDP = opts.UDP
@@ -89,10 +133,15 @@ func New(opts Options) model {
 		showListening:   showListening,
 		showEstablished: showEstablished,
 		showOther:       showOther,
-		sortField:       collector.SortByLport,
+		sortField:       sortField,
+		sortReverse:     sortReverse,
+		resolveAddrs:    resolveAddrs,
+		resolvePorts:    resolvePorts,
 		theme:           theme.GetTheme(opts.Theme),
 		interval:        interval,
 		lastRefresh:     time.Now(),
+		watchedPIDs:     make(map[int]bool),
+		rememberState:   opts.RememberState,
 	}
 }
 
@@ -127,6 +176,21 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case errMsg:
 		m.err = msg.err
 		return m, nil
+
+	case killResultMsg:
+		if msg.success {
+			m.statusMessage = fmt.Sprintf("killed %s (pid %d)", msg.process, msg.pid)
+		} else {
+			m.statusMessage = fmt.Sprintf("failed to kill pid %d: %v", msg.pid, msg.err)
+		}
+		m.statusExpiry = time.Now().Add(3 * time.Second)
+		return m, tea.Batch(m.fetchData(), clearStatusAfter(3*time.Second))
+
+	case clearStatusMsg:
+		if time.Now().After(m.statusExpiry) {
+			m.statusMessage = ""
+		}
+		return m, nil
 	}
 
 	return m, nil
@@ -142,7 +206,15 @@ func (m model) View() string {
 	if m.showDetail && m.selected != nil {
 		return m.renderDetail()
 	}
-	return m.renderMain()
+
+	main := m.renderMain()
+
+	// overlay kill confirmation modal on top of main view
+	if m.showKillConfirm && m.killTarget != nil {
+		return m.overlayModal(main, m.renderKillModal())
+	}
+
+	return main
 }
 
 func (m *model) applySorting() {
@@ -167,7 +239,8 @@ func (m *model) clampCursor() {
 }
 
 func (m model) visibleConnections() []collector.Connection {
-	var result []collector.Connection
+	var watched []collector.Connection
+	var unwatched []collector.Connection
 
 	for _, c := range m.connections {
 		if !m.matchesFilters(c) {
@@ -176,10 +249,15 @@ func (m model) visibleConnections() []collector.Connection {
 		if m.searchQuery != "" && !m.matchesSearch(c) {
 			continue
 		}
-		result = append(result, c)
+		if m.isWatched(c.PID) {
+			watched = append(watched, c)
+		} else {
+			unwatched = append(unwatched, c)
+		}
 	}
 
-	return result
+	// watched connections appear first
+	return append(watched, unwatched...)
 }
 
 func (m model) matchesFilters(c collector.Connection) bool {
@@ -218,3 +296,47 @@ func (m model) matchesSearch(c collector.Connection) bool {
 		containsIgnoreCase(c.Proto, m.searchQuery) ||
 		containsIgnoreCase(c.State, m.searchQuery)
 }
+
+func (m model) isWatched(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	return m.watchedPIDs[pid]
+}
+
+func (m *model) toggleWatch(pid int) {
+	if pid <= 0 {
+		return
+	}
+	if m.watchedPIDs[pid] {
+		delete(m.watchedPIDs, pid)
+	} else {
+		m.watchedPIDs[pid] = true
+	}
+}
+
+func (m model) watchedCount() int {
+	return len(m.watchedPIDs)
+}
+
+// currentState returns the current view options as a TUIState for persistence
+func (m model) currentState() state.TUIState {
+	return state.TUIState{
+		ShowTCP:         m.showTCP,
+		ShowUDP:         m.showUDP,
+		ShowListening:   m.showListening,
+		ShowEstablished: m.showEstablished,
+		ShowOther:       m.showOther,
+		SortField:       m.sortField,
+		SortReverse:     m.sortReverse,
+		ResolveAddrs:    m.resolveAddrs,
+		ResolvePorts:    m.resolvePorts,
+	}
+}
+
+// saveState persists current view options in the background
+func (m model) saveState() {
+	if m.rememberState {
+		state.SaveAsync(m.currentState())
+	}
+}

internal/tui/model_test.go

@@ -0,0 +1,432 @@
+package tui
+
+import (
+	"github.com/karol-broda/snitch/internal/collector"
+	"testing"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/x/exp/teatest"
+)
+
+func TestTUI_InitialState(t *testing.T) {
+	m := New(Options{
+		Theme:    "dark",
+		Interval: time.Second,
+	})
+
+	if m.showTCP != true {
+		t.Error("expected showTCP to be true by default")
+	}
+	if m.showUDP != true {
+		t.Error("expected showUDP to be true by default")
+	}
+	if m.showListening != true {
+		t.Error("expected showListening to be true by default")
+	}
+	if m.showEstablished != true {
+		t.Error("expected showEstablished to be true by default")
+	}
+}
+
+func TestTUI_FilterOptions(t *testing.T) {
+	m := New(Options{
+		Theme:     "dark",
+		Interval:  time.Second,
+		TCP:       true,
+		UDP:       false,
+		FilterSet: true,
+	})
+
+	if m.showTCP != true {
+		t.Error("expected showTCP to be true")
+	}
+	if m.showUDP != false {
+		t.Error("expected showUDP to be false")
+	}
+}
+
+func TestTUI_MatchesFilters(t *testing.T) {
+	m := New(Options{
+		Theme:       "dark",
+		Interval:    time.Second,
+		TCP:         true,
+		UDP:         false,
+		Listening:   true,
+		Established: false,
+		FilterSet:   true,
+	})
+
+	tests := []struct {
+		name     string
+		conn     collector.Connection
+		expected bool
+	}{
+		{
+			name:     "tcp listen matches",
+			conn:     collector.Connection{Proto: "tcp", State: "LISTEN"},
+			expected: true,
+		},
+		{
+			name:     "tcp6 listen matches",
+			conn:     collector.Connection{Proto: "tcp6", State: "LISTEN"},
+			expected: true,
+		},
+		{
+			name:     "udp listen does not match",
+			conn:     collector.Connection{Proto: "udp", State: "LISTEN"},
+			expected: false,
+		},
+		{
+			name:     "tcp established does not match",
+			conn:     collector.Connection{Proto: "tcp", State: "ESTABLISHED"},
+			expected: false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := m.matchesFilters(tc.conn)
+			if result != tc.expected {
+				t.Errorf("matchesFilters() = %v, want %v", result, tc.expected)
+			}
+		})
+	}
+}
+
+func TestTUI_MatchesSearch(t *testing.T) {
+	m := New(Options{Theme: "dark"})
+	m.searchQuery = "firefox"
+
+	tests := []struct {
+		name     string
+		conn     collector.Connection
+		expected bool
+	}{
+		{
+			name:     "process name matches",
+			conn:     collector.Connection{Process: "firefox"},
+			expected: true,
+		},
+		{
+			name:     "process name case insensitive",
+			conn:     collector.Connection{Process: "Firefox"},
+			expected: true,
+		},
+		{
+			name:     "no match",
+			conn:     collector.Connection{Process: "chrome"},
+			expected: false,
+		},
+		{
+			name:     "matches in address",
+			conn:     collector.Connection{Raddr: "firefox.com"},
+			expected: true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := m.matchesSearch(tc.conn)
+			if result != tc.expected {
+				t.Errorf("matchesSearch() = %v, want %v", result, tc.expected)
+			}
+		})
+	}
+}
+
+func TestTUI_KeyBindings(t *testing.T) {
+	tm := teatest.NewTestModel(t, New(Options{Theme: "dark", Interval: time.Hour}))
+
+	// test quit with 'q'
+	tm.Send(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'q'}})
+
+	tm.WaitFinished(t, teatest.WithFinalTimeout(time.Second*3))
+}
+
+func TestTUI_ToggleFilters(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+
+	// initial state: all filters on
+	if m.showTCP != true || m.showUDP != true {
+		t.Fatal("expected all protocol filters on initially")
+	}
+
+	// toggle TCP with 't'
+	newModel, _ := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'t'}})
+	m = newModel.(model)
+
+	if m.showTCP != false {
+		t.Error("expected showTCP to be false after toggle")
+	}
+
+	// toggle UDP with 'u'
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'u'}})
+	m = newModel.(model)
+
+	if m.showUDP != false {
+		t.Error("expected showUDP to be false after toggle")
+	}
+
+	// toggle listening with 'l'
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'l'}})
+	m = newModel.(model)
+
+	if m.showListening != false {
+		t.Error("expected showListening to be false after toggle")
+	}
+
+	// toggle established with 'e'
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'e'}})
+	m = newModel.(model)
+
+	if m.showEstablished != false {
+		t.Error("expected showEstablished to be false after toggle")
+	}
+}
+
+func TestTUI_HelpToggle(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+
+	if m.showHelp != false {
+		t.Fatal("expected showHelp to be false initially")
+	}
+
+	// toggle help with '?'
+	newModel, _ := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'?'}})
+	m = newModel.(model)
+
+	if m.showHelp != true {
+		t.Error("expected showHelp to be true after toggle")
+	}
+
+	// toggle help off
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'?'}})
+	m = newModel.(model)
+
+	if m.showHelp != false {
+		t.Error("expected showHelp to be false after second toggle")
+	}
+}
+
+func TestTUI_CursorNavigation(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+
+	// add some test data
+	m.connections = []collector.Connection{
+		{PID: 1, Process: "proc1", Proto: "tcp", State: "LISTEN"},
+		{PID: 2, Process: "proc2", Proto: "tcp", State: "LISTEN"},
+		{PID: 3, Process: "proc3", Proto: "tcp", State: "LISTEN"},
+	}
+
+	if m.cursor != 0 {
+		t.Fatal("expected cursor at 0 initially")
+	}
+
+	// move down with 'j'
+	newModel, _ := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'j'}})
+	m = newModel.(model)
+
+	if m.cursor != 1 {
+		t.Errorf("expected cursor at 1 after down, got %d", m.cursor)
+	}
+
+	// move down again
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'j'}})
+	m = newModel.(model)
+
+	if m.cursor != 2 {
+		t.Errorf("expected cursor at 2 after second down, got %d", m.cursor)
+	}
+
+	// move up with 'k'
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'k'}})
+	m = newModel.(model)
+
+	if m.cursor != 1 {
+		t.Errorf("expected cursor at 1 after up, got %d", m.cursor)
+	}
+
+	// go to top with 'g'
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'g'}})
+	m = newModel.(model)
+
+	if m.cursor != 0 {
+		t.Errorf("expected cursor at 0 after 'g', got %d", m.cursor)
+	}
+
+	// go to bottom with 'G'
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'G'}})
+	m = newModel.(model)
+
+	if m.cursor != 2 {
+		t.Errorf("expected cursor at 2 after 'G', got %d", m.cursor)
+	}
+}
+
+func TestTUI_WindowResize(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+
+	newModel, _ := m.Update(tea.WindowSizeMsg{Width: 120, Height: 40})
+	m = newModel.(model)
+
+	if m.width != 120 {
+		t.Errorf("expected width 120, got %d", m.width)
+	}
+	if m.height != 40 {
+		t.Errorf("expected height 40, got %d", m.height)
+	}
+}
+
+func TestTUI_ViewRenders(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+	m.width = 120
+	m.height = 40
+
+	m.connections = []collector.Connection{
+		{PID: 1234, Process: "nginx", Proto: "tcp", State: "LISTEN", Laddr: "0.0.0.0", Lport: 80},
+	}
+
+	// main view should render without panic
+	view := m.View()
+	if view == "" {
+		t.Error("expected non-empty view")
+	}
+
+	// help view
+	m.showHelp = true
+	helpView := m.View()
+	if helpView == "" {
+		t.Error("expected non-empty help view")
+	}
+}
+
+func TestTUI_ResolutionOptions(t *testing.T) {
+	// test default resolution settings
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+
+	if m.resolveAddrs != false {
+		t.Error("expected resolveAddrs to be false by default (must be explicitly set)")
+	}
+	if m.resolvePorts != false {
+		t.Error("expected resolvePorts to be false by default")
+	}
+
+	// test with explicit options
+	m2 := New(Options{
+		Theme:        "dark",
+		Interval:     time.Hour,
+		ResolveAddrs: true,
+		ResolvePorts: true,
+	})
+
+	if m2.resolveAddrs != true {
+		t.Error("expected resolveAddrs to be true when set")
+	}
+	if m2.resolvePorts != true {
+		t.Error("expected resolvePorts to be true when set")
+	}
+}
+
+func TestTUI_ToggleResolution(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour, ResolveAddrs: true})
+
+	if m.resolveAddrs != true {
+		t.Fatal("expected resolveAddrs to be true initially")
+	}
+
+	// toggle address resolution with 'n'
+	newModel, _ := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'n'}})
+	m = newModel.(model)
+
+	if m.resolveAddrs != false {
+		t.Error("expected resolveAddrs to be false after toggle")
+	}
+
+	// toggle back
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'n'}})
+	m = newModel.(model)
+
+	if m.resolveAddrs != true {
+		t.Error("expected resolveAddrs to be true after second toggle")
+	}
+
+	// toggle port resolution with 'N'
+	if m.resolvePorts != false {
+		t.Fatal("expected resolvePorts to be false initially")
+	}
+
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'N'}})
+	m = newModel.(model)
+
+	if m.resolvePorts != true {
+		t.Error("expected resolvePorts to be true after toggle")
+	}
+
+	// toggle back
+	newModel, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'N'}})
+	m = newModel.(model)
+
+	if m.resolvePorts != false {
+		t.Error("expected resolvePorts to be false after second toggle")
+	}
+}
+
+func TestTUI_ResolveAddrHelper(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+	m.resolveAddrs = false
+
+	// when resolution is off, should return original address
+	addr := m.resolveAddr("192.168.1.1")
+	if addr != "192.168.1.1" {
+		t.Errorf("expected original address when resolution off, got %s", addr)
+	}
+
+	// empty and wildcard addresses should pass through unchanged
+	if m.resolveAddr("") != "" {
+		t.Error("expected empty string to pass through")
+	}
+	if m.resolveAddr("*") != "*" {
+		t.Error("expected wildcard to pass through")
+	}
+}
+
+func TestTUI_ResolvePortHelper(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+	m.resolvePorts = false
+
+	// when resolution is off, should return port number as string
+	port := m.resolvePort(80, "tcp")
+	if port != "80" {
+		t.Errorf("expected '80' when resolution off, got %s", port)
+	}
+
+	port = m.resolvePort(443, "tcp")
+	if port != "443" {
+		t.Errorf("expected '443' when resolution off, got %s", port)
+	}
+}
+
+func TestTUI_FormatRemoteHelper(t *testing.T) {
+	m := New(Options{Theme: "dark", Interval: time.Hour})
+	m.resolveAddrs = false
+	m.resolvePorts = false
+
+	// empty/wildcard addresses should return dash
+	if m.formatRemote("", 80, "tcp") != "-" {
+		t.Error("expected dash for empty address")
+	}
+	if m.formatRemote("*", 80, "tcp") != "-" {
+		t.Error("expected dash for wildcard address")
+	}
+	if m.formatRemote("192.168.1.1", 0, "tcp") != "-" {
+		t.Error("expected dash for zero port")
+	}
+
+	// valid address:port should format correctly
+	result := m.formatRemote("192.168.1.1", 443, "tcp")
+	if result != "192.168.1.1:443" {
+		t.Errorf("expected '192.168.1.1:443', got %s", result)
+	}
+}
+

internal/tui/symbols.go

@@ -0,0 +1,38 @@
+package tui
+
+// unicode symbols used throughout the TUI
+const (
+	// indicators
+	SymbolSelected   = string('\u25B8') // black right-pointing small triangle
+	SymbolWatched    = string('\u2605') // black star
+	SymbolWarning    = string('\u26A0') // warning sign
+	SymbolSuccess    = string('\u2713') // check mark
+	SymbolError      = string('\u2717') // ballot x
+	SymbolBullet     = string('\u2022') // bullet
+	SymbolArrowRight = string('\u2192') // rightwards arrow
+	SymbolArrowLeft  = string('\u2190') // leftwards arrow
+	SymbolArrowUp    = string('\u2191') // upwards arrow
+	SymbolArrowDown  = string('\u2193') // downwards arrow
+	SymbolRefresh    = string('\u21BB') // clockwise open circle arrow
+	SymbolEllipsis   = string('\u2026') // horizontal ellipsis
+	SymbolDownload   = string('\u21E9') // downwards white arrow
+
+	// box drawing rounded 
+	BoxTopLeft     = string('\u256D') // light arc down and right
+	BoxTopRight    = string('\u256E') // light arc down and left
+	BoxBottomLeft  = string('\u2570') // light arc up and right
+	BoxBottomRight = string('\u256F') // light arc up and left
+	BoxHorizontal  = string('\u2500') // light horizontal
+	BoxVertical    = string('\u2502') // light vertical
+
+	// box drawing connectors
+	BoxTeeDown  = string('\u252C') // light down and horizontal
+	BoxTeeUp    = string('\u2534') // light up and horizontal
+	BoxTeeRight = string('\u251C') // light vertical and right
+	BoxTeeLeft  = string('\u2524') // light vertical and left
+	BoxCross    = string('\u253C') // light vertical and horizontal
+
+	// misc
+	SymbolDash = string('\u2013') // en dash
+)
+

internal/tui/view.go

@@ -2,9 +2,13 @@ package tui
 
 import (
 	"fmt"
-	"snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/resolver"
+	"strconv"
 	"strings"
 	"time"
+
+	"github.com/mattn/go-runewidth"
 )
 
 func (m model) renderMain() string {
@@ -31,7 +35,7 @@ func (m model) renderTitle() string {
 	left := m.theme.Styles.Header.Render("snitch")
 
 	ago := time.Since(m.lastRefresh).Round(time.Millisecond * 100)
-	right := m.theme.Styles.Normal.Render(fmt.Sprintf("%d/%d connections  ↻ %s", len(visible), total, formatDuration(ago)))
+	right := m.theme.Styles.Normal.Render(fmt.Sprintf("%d/%d connections  %s %s", len(visible), total, SymbolRefresh, formatDuration(ago)))
 
 	w := m.safeWidth()
 	gap := w - len(stripAnsi(left)) - len(stripAnsi(right)) - 2
@@ -45,44 +49,21 @@ func (m model) renderTitle() string {
 func (m model) renderFilters() string {
 	var parts []string
 
-	if m.showTCP {
-		parts = append(parts, m.theme.Styles.Success.Render("tcp"))
-	} else {
-		parts = append(parts, m.theme.Styles.Normal.Render("tcp"))
-	}
+	parts = append(parts, m.renderFilterLabel("t", "cp", m.showTCP))
+	parts = append(parts, m.renderFilterLabel("u", "dp", m.showUDP))
 
-	if m.showUDP {
-		parts = append(parts, m.theme.Styles.Success.Render("udp"))
-	} else {
-		parts = append(parts, m.theme.Styles.Normal.Render("udp"))
-	}
+	parts = append(parts, m.theme.Styles.Border.Render(BoxVertical))
 
-	parts = append(parts, m.theme.Styles.Border.Render("│"))
-
-	if m.showListening {
-		parts = append(parts, m.theme.Styles.Success.Render("listen"))
-	} else {
-		parts = append(parts, m.theme.Styles.Normal.Render("listen"))
-	}
-
-	if m.showEstablished {
-		parts = append(parts, m.theme.Styles.Success.Render("estab"))
-	} else {
-		parts = append(parts, m.theme.Styles.Normal.Render("estab"))
-	}
-
-	if m.showOther {
-		parts = append(parts, m.theme.Styles.Success.Render("other"))
-	} else {
-		parts = append(parts, m.theme.Styles.Normal.Render("other"))
-	}
+	parts = append(parts, m.renderFilterLabel("l", "isten", m.showListening))
+	parts = append(parts, m.renderFilterLabel("e", "stab", m.showEstablished))
+	parts = append(parts, m.renderFilterLabel("o", "ther", m.showOther))
 
 	left := "  " + strings.Join(parts, "  ")
 
 	sortLabel := sortFieldLabel(m.sortField)
-	sortDir := "↑"
+	sortDir := SymbolArrowUp
 	if m.sortReverse {
-		sortDir = "↓"
+		sortDir = SymbolArrowDown
 	}
 
 	var right string
@@ -117,12 +98,24 @@ func (m model) renderTableHeader() string {
 	return m.theme.Styles.Header.Render(header) + "\n"
 }
 
+func (m model) renderFilterLabel(firstChar, rest string, active bool) string {
+	baseStyle := m.theme.Styles.Normal
+	if active {
+		baseStyle = m.theme.Styles.Success
+	}
+
+	underlinedFirst := baseStyle.Underline(true).Render(firstChar)
+	restPart := baseStyle.Render(rest)
+
+	return underlinedFirst + restPart
+}
+
 func (m model) renderSeparator() string {
 	w := m.width - 4
 	if w < 1 {
 		w = 76
 	}
-	line := "  " + strings.Repeat("─", w)
+	line := "  " + strings.Repeat(BoxHorizontal, w)
 	return m.theme.Styles.Border.Render(line) + "\n"
 }
 
@@ -132,8 +125,11 @@ func (m model) renderConnections() string {
 	pageSize := m.pageSize()
 
 	if len(visible) == 0 {
-		empty := "\n  " + m.theme.Styles.Normal.Render("no connections match filters") + "\n"
-		return empty
+		b.WriteString("  " + m.theme.Styles.Normal.Render("no connections match filters") + "\n")
+		for i := 1; i < pageSize; i++ {
+			b.WriteString("\n")
+		}
+		return b.String()
 	}
 
 	start := m.scrollOffset(pageSize, len(visible))
@@ -157,27 +153,29 @@ func (m model) renderRow(c collector.Connection, selected bool) string {
 
 	indicator := "  "
 	if selected {
-		indicator = m.theme.Styles.Success.Render("▸ ")
+		indicator = m.theme.Styles.Success.Render(SymbolSelected + " ")
+	} else if m.isWatched(c.PID) {
+		indicator = m.theme.Styles.Watched.Render(SymbolWatched + " ")
 	}
 
 	process := truncate(c.Process, cols.process)
 	if process == "" {
-		process = "–"
+		process = SymbolDash
 	}
 
-	port := fmt.Sprintf("%d", c.Lport)
+	port := truncate(m.resolvePort(c.Lport, c.Proto), cols.port)
 	proto := c.Proto
 	state := c.State
 	if state == "" {
-		state = "–"
+		state = SymbolDash
 	}
 
-	local := c.Laddr
+	local := truncate(m.resolveAddr(c.Laddr), cols.local)
 	if local == "*" || local == "" {
 		local = "*"
 	}
 
-	remote := formatRemote(c.Raddr, c.Rport)
+	remote := truncate(m.formatRemote(c.Raddr, c.Rport, c.Proto), cols.remote)
 
 	// apply styling
 	protoStyled := m.theme.Styles.GetProtoStyle(proto).Render(fmt.Sprintf("%-*s", cols.proto, proto))
@@ -189,8 +187,8 @@ func (m model) renderRow(c collector.Connection, selected bool) string {
 		cols.port, port,
 		protoStyled,
 		stateStyled,
-		cols.local, truncate(local, cols.local),
-		truncate(remote, cols.remote))
+		cols.local, local,
+		remote)
 
 	if selected {
 		return m.theme.Styles.Selected.Render(row) + "\n"
@@ -200,7 +198,33 @@ func (m model) renderRow(c collector.Connection, selected bool) string {
 }
 
 func (m model) renderStatusLine() string {
-	left := "  " + m.theme.Styles.Normal.Render("t/u proto  l/e/o state  s sort  / search  ? help  q quit")
+	// show status message if present
+	if m.statusMessage != "" {
+		return "  " + m.theme.Styles.Warning.Render(m.statusMessage)
+	}
+
+	left := "  " + m.theme.Styles.Normal.Render("t/u proto  l/e/o state  n/N dns  w watch  K kill  s sort  / search  ? help  q quit")
+
+	// show watched count if any
+	if m.watchedCount() > 0 {
+		watchedInfo := fmt.Sprintf("  watching: %d", m.watchedCount())
+		left += m.theme.Styles.Watched.Render(watchedInfo)
+	}
+
+	// show dns resolution status
+	var resolveStatus string
+	if m.resolveAddrs && m.resolvePorts {
+		resolveStatus = "all"
+	} else if m.resolveAddrs {
+		resolveStatus = "addrs"
+	} else if m.resolvePorts {
+		resolveStatus = "ports"
+	} else {
+		resolveStatus = "off"
+	}
+	if resolveStatus != "addrs" { // addrs is the default, don't show
+		left += m.theme.Styles.Normal.Render(fmt.Sprintf("  dns: %s", resolveStatus))
+	}
 
 	return left
 }
@@ -233,6 +257,17 @@ func (m model) renderHelp() string {
   s            cycle sort field
   S            reverse sort order
 
+  display
+  ───────
+  n            toggle address resolution (dns)
+  N            toggle port resolution (service names)
+
+  process management
+  ──────────────────
+  w            watch/unwatch process (highlight & track)
+  W            clear all watched processes
+  K            kill process (with confirmation)
+
   other
   ─────
   /            search
@@ -254,7 +289,12 @@ func (m model) renderDetail() string {
 
 	b.WriteString("\n")
 	b.WriteString("  " + m.theme.Styles.Header.Render("connection details") + "\n")
-	b.WriteString("  " + m.theme.Styles.Border.Render(strings.Repeat("─", 40)) + "\n\n")
+	b.WriteString("  " + m.theme.Styles.Border.Render(strings.Repeat(BoxHorizontal, 40)) + "\n\n")
+
+	localAddr := m.resolveAddr(c.Laddr)
+	localPort := m.resolvePort(c.Lport, c.Proto)
+	remoteAddr := m.resolveAddr(c.Raddr)
+	remotePort := m.resolvePort(c.Rport, c.Proto)
 
 	fields := []struct {
 		label string
@@ -265,8 +305,8 @@ func (m model) renderDetail() string {
 		{"user", c.User},
 		{"protocol", c.Proto},
 		{"state", c.State},
-		{"local", fmt.Sprintf("%s:%d", c.Laddr, c.Lport)},
-		{"remote", fmt.Sprintf("%s:%d", c.Raddr, c.Rport)},
+		{"local", fmt.Sprintf("%s:%s", localAddr, localPort)},
+		{"remote", fmt.Sprintf("%s:%s", remoteAddr, remotePort)},
 		{"interface", c.Interface},
 		{"inode", fmt.Sprintf("%d", c.Inode)},
 	}
@@ -274,7 +314,7 @@ func (m model) renderDetail() string {
 	for _, f := range fields {
 		val := f.value
 		if val == "" || val == "0" || val == ":0" {
-			val = "–"
+			val = SymbolDash
 		}
 		line := fmt.Sprintf("  %-12s  %s\n", m.theme.Styles.Header.Render(f.label), val)
 		b.WriteString(line)
@@ -286,6 +326,179 @@ func (m model) renderDetail() string {
 	return b.String()
 }
 
+func (m model) renderKillModal() string {
+	if m.killTarget == nil {
+		return ""
+	}
+
+	c := m.killTarget
+	processName := c.Process
+	if processName == "" {
+		processName = "(unknown)"
+	}
+
+	// count how many connections this process has
+	connCount := 0
+	for _, conn := range m.connections {
+		if conn.PID == c.PID {
+			connCount++
+		}
+	}
+
+	// build modal content
+	var lines []string
+	lines = append(lines, "")
+	lines = append(lines, m.theme.Styles.Error.Render("  "+SymbolWarning+"  KILL PROCESS?  "))
+	lines = append(lines, "")
+	lines = append(lines, fmt.Sprintf("  process:  %s", m.theme.Styles.Header.Render(processName)))
+	lines = append(lines, fmt.Sprintf("  pid:      %s", m.theme.Styles.Header.Render(fmt.Sprintf("%d", c.PID))))
+	lines = append(lines, fmt.Sprintf("  user:     %s", c.User))
+	lines = append(lines, fmt.Sprintf("  conns:    %d", connCount))
+	lines = append(lines, "")
+	lines = append(lines, m.theme.Styles.Warning.Render("  sends SIGTERM to process"))
+	if connCount > 1 {
+		lines = append(lines, m.theme.Styles.Warning.Render(fmt.Sprintf("  will close all %d connections", connCount)))
+	}
+	lines = append(lines, "")
+	lines = append(lines, fmt.Sprintf("  %s confirm   %s cancel",
+		m.theme.Styles.Success.Render("[y]"),
+		m.theme.Styles.Error.Render("[n]")))
+	lines = append(lines, "")
+
+	return strings.Join(lines, "\n")
+}
+
+func (m model) overlayModal(background, modal string) string {
+	bgLines := strings.Split(background, "\n")
+	modalLines := strings.Split(modal, "\n")
+
+	// find max modal line width using runewidth for proper unicode handling
+	modalWidth := 0
+	for _, line := range modalLines {
+		w := stringWidth(line)
+		if w > modalWidth {
+			modalWidth = w
+		}
+	}
+	modalWidth += 4 // padding for box
+
+	modalHeight := len(modalLines)
+	boxWidth := modalWidth + 2 // include border chars │ │
+
+	// calculate modal position (centered)
+	startRow := (m.height - modalHeight) / 2
+	if startRow < 2 {
+		startRow = 2
+	}
+	startCol := (m.width - boxWidth) / 2
+	if startCol < 0 {
+		startCol = 0
+	}
+
+	// build result
+	result := make([]string, len(bgLines))
+	copy(result, bgLines)
+
+	// ensure we have enough lines
+	for len(result) < startRow+modalHeight+2 {
+		result = append(result, strings.Repeat(" ", m.width))
+	}
+
+	// helper to build a line with modal overlay
+	buildLine := func(bgLine, modalContent string) string {
+		modalVisibleWidth := stringWidth(modalContent)
+		endCol := startCol + modalVisibleWidth
+
+		leftBg := visibleSubstring(bgLine, 0, startCol)
+		rightBg := visibleSubstring(bgLine, endCol, m.width)
+
+		// pad left side if needed
+		leftLen := stringWidth(leftBg)
+		if leftLen < startCol {
+			leftBg = leftBg + strings.Repeat(" ", startCol-leftLen)
+		}
+
+		return leftBg + modalContent + rightBg
+	}
+
+	// draw top border
+	borderRow := startRow - 1
+	if borderRow >= 0 && borderRow < len(result) {
+		border := m.theme.Styles.Border.Render(BoxTopLeft + strings.Repeat(BoxHorizontal, modalWidth) + BoxTopRight)
+		result[borderRow] = buildLine(result[borderRow], border)
+	}
+
+	// draw modal content with side borders
+	for i, line := range modalLines {
+		row := startRow + i
+		if row >= 0 && row < len(result) {
+			content := line
+			padding := modalWidth - stringWidth(line)
+			if padding > 0 {
+				content = line + strings.Repeat(" ", padding)
+			}
+			boxedLine := m.theme.Styles.Border.Render(BoxVertical) + content + m.theme.Styles.Border.Render(BoxVertical)
+			result[row] = buildLine(result[row], boxedLine)
+		}
+	}
+
+	// draw bottom border
+	bottomRow := startRow + modalHeight
+	if bottomRow >= 0 && bottomRow < len(result) {
+		border := m.theme.Styles.Border.Render(BoxBottomLeft + strings.Repeat(BoxHorizontal, modalWidth) + BoxBottomRight)
+		result[bottomRow] = buildLine(result[bottomRow], border)
+	}
+
+	return strings.Join(result, "\n")
+}
+
+// stringWidth returns the display width of a string excluding ANSI codes
+func stringWidth(s string) int {
+	return runewidth.StringWidth(stripAnsi(s))
+}
+
+// visibleSubstring extracts a substring by visible column positions, preserving ANSI codes
+func visibleSubstring(s string, start, end int) string {
+	if start >= end {
+		return ""
+	}
+
+	var result strings.Builder
+	visiblePos := 0
+	inEscape := false
+
+	for _, r := range s {
+		// detect start of ANSI escape sequence
+		if r == '\x1b' {
+			inEscape = true
+			result.WriteRune(r)
+			continue
+		}
+
+		if inEscape {
+			result.WriteRune(r)
+			// end of escape sequence is a letter
+			if (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') {
+				inEscape = false
+			}
+			continue
+		}
+
+		// regular visible character
+		w := runewidth.RuneWidth(r)
+		if visiblePos >= start && visiblePos+w <= end {
+			result.WriteRune(r)
+		}
+		visiblePos += w
+
+		if visiblePos >= end {
+			break
+		}
+	}
+
+	return result.String()
+}
+
 func (m model) scrollOffset(pageSize, total int) int {
 	if total <= pageSize {
 		return 0
@@ -312,23 +525,72 @@ type columns struct {
 }
 
 func (m model) columnWidths() columns {
-	available := m.safeWidth() - 16
-
+	// minimum widths (header lengths + padding)
 	c := columns{
-		process: 16,
-		port:    6,
-		proto:   5,
-		state:   11,
-		local:   15,
-		remote:  20,
+		process: 7,  // "PROCESS"
+		port:    4,  // "PORT"
+		proto:   5,  // "PROTO"
+		state:   5,  // "STATE"
+		local:   5,  // "LOCAL"
+		remote:  6,  // "REMOTE"
 	}
 
-	used := c.process + c.port + c.proto + c.state + c.local + c.remote
-	extra := available - used
+	// scan visible connections to find max content width for each column
+	visible := m.visibleConnections()
+	for _, conn := range visible {
+		if len(conn.Process) > c.process {
+			c.process = len(conn.Process)
+		}
 
-	if extra > 0 {
-		c.process += extra / 3
-		c.remote += extra - extra/3
+		port := m.resolvePort(conn.Lport, conn.Proto)
+		if len(port) > c.port {
+			c.port = len(port)
+		}
+
+		if len(conn.Proto) > c.proto {
+			c.proto = len(conn.Proto)
+		}
+
+		if len(conn.State) > c.state {
+			c.state = len(conn.State)
+		}
+
+		local := m.resolveAddr(conn.Laddr)
+		if len(local) > c.local {
+			c.local = len(local)
+		}
+
+		remote := m.formatRemote(conn.Raddr, conn.Rport, conn.Proto)
+		if len(remote) > c.remote {
+			c.remote = len(remote)
+		}
+	}
+
+	// calculate total and available width
+	spacing := 12 // 2 spaces between each of 6 columns
+	indicator := 2
+	margin := 2
+	available := m.safeWidth() - spacing - indicator - margin
+
+	total := c.process + c.port + c.proto + c.state + c.local + c.remote
+
+	// if content fits, we're done
+	if total <= available {
+		return c
+	}
+
+	// content exceeds available space - need to shrink columns proportionally
+	// fixed columns that shouldn't shrink much: port, proto, state
+	fixedWidth := c.port + c.proto + c.state
+	flexibleAvailable := available - fixedWidth
+
+	// distribute flexible space between process, local, remote
+	flexibleTotal := c.process + c.local + c.remote
+	if flexibleTotal > 0 && flexibleAvailable > 0 {
+		ratio := float64(flexibleAvailable) / float64(flexibleTotal)
+		c.process = max(7, int(float64(c.process)*ratio))
+		c.local = max(5, int(float64(c.local)*ratio))
+		c.remote = max(6, int(float64(c.remote)*ratio))
 	}
 
 	return c
@@ -350,3 +612,29 @@ func formatDuration(d time.Duration) string {
 	}
 	return fmt.Sprintf("%.0fm", d.Minutes())
 }
+
+func (m model) resolveAddr(addr string) string {
+	if !m.resolveAddrs {
+		return addr
+	}
+	if addr == "" || addr == "*" {
+		return addr
+	}
+	return resolver.ResolveAddr(addr)
+}
+
+func (m model) resolvePort(port int, proto string) string {
+	if !m.resolvePorts {
+		return strconv.Itoa(port)
+	}
+	return resolver.ResolvePort(port, proto)
+}
+
+func (m model) formatRemote(addr string, port int, proto string) string {
+	if addr == "" || addr == "*" || port == 0 {
+		return "-"
+	}
+	resolvedAddr := m.resolveAddr(addr)
+	resolvedPort := m.resolvePort(port, proto)
+	return fmt.Sprintf("%s:%s", resolvedAddr, resolvedPort)
+}

main.go

@@ -1,7 +1,7 @@
 package main
 
 import (
-	"snitch/cmd"
+	"github.com/karol-broda/snitch/cmd"
 )
 
 func main() {

nix/hm-module.nix

@@ -0,0 +1,177 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.programs.snitch;
+
+  themes = [
+    "ansi"
+    "catppuccin-mocha"
+    "catppuccin-macchiato"
+    "catppuccin-frappe"
+    "catppuccin-latte"
+    "gruvbox-dark"
+    "gruvbox-light"
+    "dracula"
+    "nord"
+    "tokyo-night"
+    "tokyo-night-storm"
+    "tokyo-night-light"
+    "solarized-dark"
+    "solarized-light"
+    "one-dark"
+    "mono"
+    "auto"
+  ];
+
+  defaultFields = [
+    "pid"
+    "process"
+    "user"
+    "proto"
+    "state"
+    "laddr"
+    "lport"
+    "raddr"
+    "rport"
+  ];
+
+  tomlFormat = pkgs.formats.toml { };
+
+  settingsType = lib.types.submodule {
+    freeformType = tomlFormat.type;
+
+    options = {
+      defaults = lib.mkOption {
+        type = lib.types.submodule {
+          freeformType = tomlFormat.type;
+
+          options = {
+            interval = lib.mkOption {
+              type = lib.types.str;
+              default = "1s";
+              example = "2s";
+              description = "Default refresh interval for watch/stats/trace commands.";
+            };
+
+            numeric = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Disable name/service resolution by default.";
+            };
+
+            fields = lib.mkOption {
+              type = lib.types.listOf lib.types.str;
+              default = defaultFields;
+              example = [ "pid" "process" "proto" "state" "laddr" "lport" ];
+              description = "Default fields to display.";
+            };
+
+            theme = lib.mkOption {
+              type = lib.types.enum themes;
+              default = "ansi";
+              description = ''
+                Color theme for the TUI. "ansi" inherits terminal colors.
+              '';
+            };
+
+            units = lib.mkOption {
+              type = lib.types.enum [ "auto" "si" "iec" ];
+              default = "auto";
+              description = "Default units for byte display.";
+            };
+
+            color = lib.mkOption {
+              type = lib.types.enum [ "auto" "always" "never" ];
+              default = "auto";
+              description = "Default color mode.";
+            };
+
+            resolve = lib.mkOption {
+              type = lib.types.bool;
+              default = true;
+              description = "Enable name resolution by default.";
+            };
+
+            dns_cache = lib.mkOption {
+              type = lib.types.bool;
+              default = true;
+              description = "Enable DNS caching.";
+            };
+
+            ipv4 = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Filter to IPv4 only by default.";
+            };
+
+            ipv6 = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Filter to IPv6 only by default.";
+            };
+
+            no_headers = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Omit headers in output by default.";
+            };
+
+            output_format = lib.mkOption {
+              type = lib.types.enum [ "table" "json" "csv" ];
+              default = "table";
+              description = "Default output format.";
+            };
+
+            sort_by = lib.mkOption {
+              type = lib.types.str;
+              default = "";
+              example = "pid";
+              description = "Default sort field.";
+            };
+          };
+        };
+        default = { };
+        description = "Default settings for snitch commands.";
+      };
+    };
+  };
+in
+{
+  options.programs.snitch = {
+    enable = lib.mkEnableOption "snitch, a friendlier ss/netstat for humans";
+
+    package = lib.mkPackageOption pkgs "snitch" { };
+
+    settings = lib.mkOption {
+      type = settingsType;
+      default = { };
+      example = lib.literalExpression ''
+        {
+          defaults = {
+            theme = "catppuccin-mocha";
+            interval = "2s";
+            resolve = true;
+          };
+        }
+      '';
+      description = ''
+        Configuration written to {file}`$XDG_CONFIG_HOME/snitch/snitch.toml`.
+
+        See <https://github.com/karol-broda/snitch> for available options.
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home.packages = [ cfg.package ];
+
+    xdg.configFile."snitch/snitch.toml" = lib.mkIf (cfg.settings != { }) {
+      source = tomlFormat.generate "snitch.toml" cfg.settings;
+    };
+  };
+}
+

nix/tests/hm-module-test.nix

@@ -0,0 +1,429 @@
+# home manager module tests
+#
+# run with: nix build .#checks.x86_64-linux.hm-module
+#
+# tests cover:
+# - module evaluation with various configurations
+# - type validation for all options
+# - generated TOML content verification
+# - edge cases (disabled, empty settings, full settings)
+{ pkgs, lib, hmModule }:
+
+let
+  # minimal home-manager stub for standalone module testing
+  hmLib = {
+    hm.types.dagOf = lib.types.attrsOf;
+    dag.entryAnywhere = x: x;
+  };
+
+  # evaluate the hm module with a given config
+  evalModule = testConfig:
+    lib.evalModules {
+      modules = [
+        hmModule
+        # stub home-manager's expected structure
+        {
+          options = {
+            home.packages = lib.mkOption {
+              type = lib.types.listOf lib.types.package;
+              default = [ ];
+            };
+            xdg.configFile = lib.mkOption {
+              type = lib.types.attrsOf (lib.types.submodule {
+                options = {
+                  source = lib.mkOption { type = lib.types.path; };
+                  text = lib.mkOption { type = lib.types.str; default = ""; };
+                };
+              });
+              default = { };
+            };
+          };
+        }
+        testConfig
+      ];
+      specialArgs = { inherit pkgs lib; };
+    };
+
+  # read generated TOML file content
+  readGeneratedToml = evalResult:
+    let
+      configFile = evalResult.config.xdg.configFile."snitch/snitch.toml" or null;
+    in
+    if configFile != null && configFile ? source
+    then builtins.readFile configFile.source
+    else null;
+
+  # test cases
+  tests = {
+    # test 1: module evaluates when disabled
+    moduleDisabled = {
+      name = "module-disabled";
+      config = {
+        programs.snitch.enable = false;
+      };
+      assertions = evalResult: [
+        {
+          assertion = evalResult.config.home.packages == [ ];
+          message = "packages should be empty when disabled";
+        }
+        {
+          assertion = !(evalResult.config.xdg.configFile ? "snitch/snitch.toml");
+          message = "config file should not exist when disabled";
+        }
+      ];
+    };
+
+    # test 2: module evaluates with enable only (defaults)
+    moduleEnabledDefaults = {
+      name = "module-enabled-defaults";
+      config = {
+        programs.snitch.enable = true;
+      };
+      assertions = evalResult: [
+        {
+          assertion = builtins.length evalResult.config.home.packages == 1;
+          message = "package should be installed when enabled";
+        }
+      ];
+    };
+
+    # test 3: all theme values are valid
+    themeValidation = {
+      name = "theme-validation";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.theme = "catppuccin-mocha";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = toml != null;
+            message = "TOML config should be generated";
+          }
+          {
+            assertion = lib.hasInfix "catppuccin-mocha" toml;
+            message = "theme should be set in TOML";
+          }
+        ];
+    };
+
+    # test 4: full configuration with all options
+    fullConfiguration = {
+      name = "full-configuration";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults = {
+            interval = "2s";
+            numeric = true;
+            fields = [ "pid" "process" "proto" ];
+            theme = "nord";
+            units = "si";
+            color = "always";
+            resolve = false;
+            dns_cache = false;
+            ipv4 = true;
+            ipv6 = false;
+            no_headers = true;
+            output_format = "json";
+            sort_by = "pid";
+          };
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = toml != null;
+            message = "TOML config should be generated";
+          }
+          {
+            assertion = lib.hasInfix "interval = \"2s\"" toml;
+            message = "interval should be 2s";
+          }
+          {
+            assertion = lib.hasInfix "numeric = true" toml;
+            message = "numeric should be true";
+          }
+          {
+            assertion = lib.hasInfix "theme = \"nord\"" toml;
+            message = "theme should be nord";
+          }
+          {
+            assertion = lib.hasInfix "units = \"si\"" toml;
+            message = "units should be si";
+          }
+          {
+            assertion = lib.hasInfix "color = \"always\"" toml;
+            message = "color should be always";
+          }
+          {
+            assertion = lib.hasInfix "resolve = false" toml;
+            message = "resolve should be false";
+          }
+          {
+            assertion = lib.hasInfix "output_format = \"json\"" toml;
+            message = "output_format should be json";
+          }
+          {
+            assertion = lib.hasInfix "sort_by = \"pid\"" toml;
+            message = "sort_by should be pid";
+          }
+        ];
+    };
+
+    # test 5: output format enum validation
+    outputFormatCsv = {
+      name = "output-format-csv";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.output_format = "csv";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "output_format = \"csv\"" toml;
+            message = "output_format should accept csv";
+          }
+        ];
+    };
+
+    # test 6: units enum validation
+    unitsIec = {
+      name = "units-iec";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.units = "iec";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "units = \"iec\"" toml;
+            message = "units should accept iec";
+          }
+        ];
+    };
+
+    # test 7: color never value
+    colorNever = {
+      name = "color-never";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.color = "never";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "color = \"never\"" toml;
+            message = "color should accept never";
+          }
+        ];
+    };
+
+    # test 8: freeform type allows custom keys
+    freeformCustomKeys = {
+      name = "freeform-custom-keys";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings = {
+            defaults.theme = "dracula";
+            custom_section = {
+              custom_key = "custom_value";
+            };
+          };
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "custom_key" toml;
+            message = "freeform type should allow custom keys";
+          }
+        ];
+    };
+
+    # test 9: all themes evaluate correctly
+    allThemes =
+      let
+        themes = [
+          "ansi"
+          "catppuccin-mocha"
+          "catppuccin-macchiato"
+          "catppuccin-frappe"
+          "catppuccin-latte"
+          "gruvbox-dark"
+          "gruvbox-light"
+          "dracula"
+          "nord"
+          "tokyo-night"
+          "tokyo-night-storm"
+          "tokyo-night-light"
+          "solarized-dark"
+          "solarized-light"
+          "one-dark"
+          "mono"
+          "auto"
+        ];
+      in
+      {
+        name = "all-themes";
+        # use the last theme as the test config
+        config = {
+          programs.snitch = {
+            enable = true;
+            settings.defaults.theme = "auto";
+          };
+        };
+        assertions = evalResult:
+          let
+            # verify all themes can be set by evaluating them
+            themeResults = map
+              (theme:
+                let
+                  result = evalModule {
+                    programs.snitch = {
+                      enable = true;
+                      settings.defaults.theme = theme;
+                    };
+                  };
+                  toml = readGeneratedToml result;
+                in
+                {
+                  inherit theme;
+                  success = toml != null && lib.hasInfix theme toml;
+                }
+              )
+              themes;
+            allSucceeded = lib.all (r: r.success) themeResults;
+          in
+          [
+            {
+              assertion = allSucceeded;
+              message = "all themes should evaluate correctly: ${
+                lib.concatMapStringsSep ", " 
+                  (r: "${r.theme}=${if r.success then "ok" else "fail"}") 
+                  themeResults
+              }";
+            }
+          ];
+      };
+
+    # test 10: fields list serialization
+    fieldsListSerialization = {
+      name = "fields-list-serialization";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.fields = [ "pid" "process" "proto" "state" ];
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "pid" toml && lib.hasInfix "process" toml;
+            message = "fields list should be serialized correctly";
+          }
+        ];
+    };
+  };
+
+  # run all tests and collect results
+  runTests =
+    let
+      testResults = lib.mapAttrsToList
+        (name: test:
+          let
+            evalResult = evalModule test.config;
+            assertions = test.assertions evalResult;
+            failures = lib.filter (a: !a.assertion) assertions;
+          in
+          {
+            inherit name;
+            testName = test.name;
+            passed = failures == [ ];
+            failures = map (f: f.message) failures;
+          }
+        )
+        tests;
+
+      allPassed = lib.all (r: r.passed) testResults;
+      failedTests = lib.filter (r: !r.passed) testResults;
+
+      summary = ''
+        ========================================
+        home manager module test results
+        ========================================
+        total tests: ${toString (builtins.length testResults)}
+        passed: ${toString (builtins.length (lib.filter (r: r.passed) testResults))}
+        failed: ${toString (builtins.length failedTests)}
+        ========================================
+        ${lib.concatMapStringsSep "\n" (r: 
+          if r.passed 
+          then "[yes] ${r.testName}"
+          else "[no] ${r.testName}\n  ${lib.concatStringsSep "\n  " r.failures}"
+        ) testResults}
+        ========================================
+      '';
+    in
+    {
+      inherit testResults allPassed failedTests summary;
+    };
+
+  results = runTests;
+
+in
+pkgs.runCommand "hm-module-test"
+{
+  passthru = {
+    inherit results;
+    # expose for debugging
+    inherit evalModule tests;
+  };
+}
+  (
+    if results.allPassed
+    then ''
+      echo "${results.summary}"
+      echo "all tests passed"
+      touch $out
+    ''
+    else ''
+      echo "${results.summary}"
+      echo ""
+      echo "failed tests:"
+      ${lib.concatMapStringsSep "\n" (t: ''
+        echo "  - ${t.testName}: ${lib.concatStringsSep ", " t.failures}"
+      '') results.failedTests}
+      exit 1
+    ''
+  )
+