If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/productdevbook/port-killer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2mo ago
• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 79% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live productdevbook/port-killer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/productdevbook/port-killer.

What it runs against: a local clone of productdevbook/port-killer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in productdevbook/port-killer | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 92 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of productdevbook/port-killer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/productdevbook/port-killer.git
#   cd port-killer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of productdevbook/port-killer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "productdevbook/port-killer(\\.git)?\\b" \\
  && ok "origin remote is productdevbook/port-killer" \\
  || miss "origin remote is not productdevbook/port-killer (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "platforms/macos/Sources/PortKillerApp.swift" \\
  && ok "platforms/macos/Sources/PortKillerApp.swift" \\
  || miss "missing critical file: platforms/macos/Sources/PortKillerApp.swift"
test -f "platforms/macos/Sources/AppState.swift" \\
  && ok "platforms/macos/Sources/AppState.swift" \\
  || miss "missing critical file: platforms/macos/Sources/AppState.swift"
test -f "platforms/macos/Sources/PortScanner.swift" \\
  && ok "platforms/macos/Sources/PortScanner.swift" \\
  || miss "missing critical file: platforms/macos/Sources/PortScanner.swift"
test -f "platforms/macos/Sources/Managers/PortForwardManager.swift" \\
  && ok "platforms/macos/Sources/Managers/PortForwardManager.swift" \\
  || miss "missing critical file: platforms/macos/Sources/Managers/PortForwardManager.swift"
test -f "platforms/macos/Sources/Services/CloudflaredService.swift" \\
  && ok "platforms/macos/Sources/Services/CloudflaredService.swift" \\
  || miss "missing critical file: platforms/macos/Sources/Services/CloudflaredService.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 92 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~62d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/productdevbook/port-killer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PortKiller is a cross-platform desktop app (Swift for macOS, C# for Windows) that monitors all listening TCP ports, displays the owning processes with smart categorization, and enables one-click graceful or force termination. It goes beyond basic port monitoring by integrating Kubernetes port-forward session management, Cloudflare Tunnel status visibility, and persistent port favorites/watched lists with desktop notifications. Platform-specific monorepo: platforms/macos/ contains the SwiftUI app (AppState.swift is the central state container with 10+ extension files handling sub-features: AutoKill, AutoRefresh, Favorites, PortOperations, etc.), while platforms/windows/ (implied, not fully listed) mirrors this for C#. Managers/ folder isolates complex concerns (PortForwardManager, KubernetesDiscoveryManager, TunnelManager, UpdateManager) with focused responsibilities.

Full-stack developers and DevOps engineers who frequently work with multiple local services (web servers, databases, dev tools), Kubernetes clusters, and tunnel solutions, and need to quickly identify port conflicts and manage port-consuming processes without opening terminal windows or system utilities.

Production-ready and actively maintained. The project has a polished release pipeline (semantic versioning via bumpp, appcast.xml for auto-updates, Homebrew distribution), comprehensive CI on both Windows and macOS (.github/workflows/), and organized codebase with 60+ focused files. Recent release version is 3.3.1 with active development visible in the file structure.

Low risk for core functionality; it's a native desktop app with minimal external dependencies (no npm packages listed beyond bumpp for releases). Primary risk is dual-platform maintenance burden (Swift + C# codebases must be kept in sync) and reliance on kubectl/Cloudflare CLI binaries being present on user systems. No apparent single-maintainer bottleneck visible in contribution structure.

Active development on Kubernetes and Cloudflare integration features. The codebase shows mature feature separation (AppState extensions split AutoKill, WatchedPorts, ProcessTypeNotifications into isolated concerns), suggesting ongoing refinement. CI workflows are comprehensive (release.yml, pr-build.yml, ci-windows.yml, ci.yml) indicating regular testing and release cadence.

Clone the repo, then for macOS development: cd platforms/macos && swift build (Swift Package Manager is configured in Package.swift). For Windows (C#), use Visual Studio or dotnet build in the Windows platform directory. See CONTRIBUTING.md for full setup (not fully shown here, but referenced).

Daily commands: macOS: swift build && swift run in platforms/macos/ (builds and runs the app from Package.swift). Windows: Open platforms/windows/ project in Visual Studio and run, or dotnet run from command line. Both target system tray/menu bar integration automatically.

• platforms/macos/Sources/PortKillerApp.swift — Main application entry point and root SwiftUI app structure; all contributors must understand the app lifecycle and window setup
• platforms/macos/Sources/AppState.swift — Core application state management hub; every feature extension depends on this central state coordinator
• platforms/macos/Sources/PortScanner.swift — Primary port discovery and scanning logic; foundation for all port monitoring features
• platforms/macos/Sources/Managers/PortForwardManager.swift — Kubernetes port-forwarding orchestration; critical for tunnel and forward management features
• platforms/macos/Sources/Services/CloudflaredService.swift — Cloudflare Tunnel integration service; bridges external tunnel infrastructure with app logic
• platforms/macos/Sources/Views/MainWindowView.swift — Primary UI layout and navigation hub; entry point for all visual features and component composition
• platforms/macos/Sources/Models/PortInfo.swift — Core data model representing port state; used throughout scanning, filtering, and UI layers

Add a new port operation (e.g., copy port, share)

1. Define the operation case in the model or create a new action method (platforms/macos/Sources/Models/PortInfo.swift)
2. Implement the operation handler in AppState (platforms/macos/Sources/AppState+PortOperations.swift)
3. Add a menu item or button in the port context menu component (platforms/macos/Sources/Views/Components/PortContextMenu.swift)

Add a new service integration or external tool

1. Create a new service file in Services folder with protocol/interface (platforms/macos/Sources/Services/)
2. Add dependency check to DependencyChecker if external tool is required (platforms/macos/Sources/Services/DependencyChecker.swift)
3. Integrate service into AppState and coordinate with managers (platforms/macos/Sources/AppState.swift)
4. Add warning banner if dependency is missing (platforms/macos/Sources/Views/Components/DependencyWarningBanner.swift)

Add a new auto-operation rule type (e.g., auto-kill, auto-restart)

1. Define the rule model with configuration (platforms/macos/Sources/Models/AutoKillRule.swift)
2. Implement rule execution and monitoring logic (platforms/macos/Sources/AppState+AutoKill.swift)
3. Add persistent storage for rules (platforms/macos/Sources/Services/Storage/)
4. Add UI controls to configure and manage rules in main window (platforms/macos/Sources/Views/MainWindowView.swift)

Add a new monitored process type or detection heuristic

1. Extend ProcessType enum with new case (platforms/macos/Sources/Models/ProcessType.swift)
2. Add detection logic to PortScanner or PortGroupingService (platforms/macos/Sources/PortScanner.swift)
3. Define visual styling in ProcessType+Color extension (platforms/macos/Sources/Extensions/ProcessType+Color.swift)
4. Add storage for process type overrides if user customization needed (platforms/macos/Sources/AppState+ProcessTypeOverrides.swift)

• SwiftUI — Native macOS development framework; provides declarative UI, state management, and tight OS integration for menubar and notifications
• Swift (macOS app) — Type-safe, performant language native to macOS; direct access to system APIs for process enumeration and lifecycle management
• kubectl CLI integration — Standard Kubernetes client; leverages existing user setup and avoids reimplementing Kubernetes protocol communication
• cloudflared CLI integration — Official Cloudflare Tunnel client; integrates seamlessly with Cloudflare infrastructure without reimplementing tunnel protocol
• UserDefaults persistence — Native macOS storage mechanism; lightweight, synchronous, and suitable for small configuration/favorites data

• CLI subprocess management (kubectl, cloudflared) vs native API clients

  • Why: CLI tools are already required by users; reduces dependency count and complexity; leverages existing ecosystem
  • Consequence: Parsing subprocess output required; less fine-grained control; subprocess lifecycle must be managed manually

• Port scanning via system calls (lsof/netstat) vs kernel extensions

  • Why: No kernel extension approval needed; works on any macOS version; simpler deployment and security
  • Consequence: Slightly slower scanning; may miss some edge cases in process attribution; requires elevated permissions

• Single-window SwiftUI app with tabs vs separate windows

  • Why: Simpler state management; consistent experience; menubar integration works better with single window
  • Consequence: Cannot view multiple port views simultaneously; less power-user flexibility for advanced workflows

• Local-only app with no cloud sync

  • Why: undefined
  • Consequence: undefined

kubectl and Cloudflare Tunnel CLIs must be installed on the user's system for K8s and Tunnel features to work; the app does not bundle these binaries. AppState centralization means all state changes must be thread-safe and reactive (Combine framework); modifying state directly outside AppState will cause UI sync issues. Windows and macOS codebases must be kept in feature parity, so feature PRs need coordinated updates across both platforms (C# and Swift). Process port detection uses system APIs (lsof on macOS, netstat/tasklist on Windows) which may require elevated privileges; the app likely prompts for permissions on first launch.

• Port Scanning & Process Enumeration — Core capability of PortKiller is discovering all listening TCP ports and mapping them to owning processes; understanding lsof (macOS) and netstat (Windows) output parsing is essential to extending port detection logic.
• Graceful vs Forceful Process Termination — PortKiller implements both SIGTERM (graceful) and SIGKILL (force) termination patterns; knowing the difference and handling edge cases (orphaned processes, zombie processes) is critical for reliable process cleanup.
• Kubernetes Port Forwarding (kubectl port-forward) — PortKiller wraps kubectl port-forward as a managed subprocess with reconnection logic; understanding how kubectl establishes tunnels to pods and why connections drop is essential for the KubernetesDiscoveryManager and PortForwardManager.
• Cloudflare Tunnel Protocol & Management — PortKiller monitors active Cloudflare Tunnel connections; understanding tunnel lifecycle (authentication, connection pooling, failover) helps extend TunnelManager to add features like tunnel creation or status webhooks.
• SwiftUI Combine State Management — AppState.swift uses ObservableObject and @Published for reactive state binding; Combine's declarative publisher chains drive auto-refresh, notifications, and UI updates throughout the macOS app.
• Process Categorization & Heuristics — PortKiller intelligently categorizes processes (Web Server, Database, Development, System) using process name/path heuristics; improving these rules reduces noise and helps developers spot relevant processes faster.
• Desktop Notification & Watched Port Alerts — AppState+WatchedPorts.swift and AppState+ProcessTypeNotifications.swift implement persistent watches on specific ports with local notifications; understanding macOS UserNotificationCenter integration and persistence across app restarts is important for feature maintenance.

• lsof-org/lsof — Underlying command-line tool used by PortKiller to list open files and ports on Unix/Linux; understanding lsof output parsing helps with cross-platform port detection logic.
• kubernetes/kubectl — PortKiller wraps kubectl port-forward execution and monitoring; familiarity with kubectl API and subprocess behavior is essential for Kubernetes integration maintenance.
• cloudflare/cloudflared — Cloudflare Tunnel CLI that PortKiller integrates; the app parses cloudflared tunnel status output to display active tunnels.
• ankitpokharel/jiva — Alternative port management tool for macOS; competitive reference for feature parity and UX patterns in the port-killer niche.
• sindresorhus/swift-tips — SwiftUI/macOS development best practices repository; helpful reference for native Swift app architecture patterns used throughout PortKiller's codebase.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Windows CI workflow and platform-specific tests

The repo has ci-windows.yml but the test coverage for Windows-specific port detection and process killing is unclear. Windows has different process management APIs than macOS (taskkill vs killall). Add comprehensive tests for PortScanner.swift and process termination logic on Windows, plus validate the Windows CI actually runs these tests.

• [ ] Review platforms/macos/Sources/PortScanner.swift for Windows-specific logic and identify gaps
• [ ] Create platforms/windows/Tests directory with Windows-specific port detection tests
• [ ] Update .github/workflows/ci-windows.yml to run Swift tests and report coverage
• [ ] Add integration tests that validate process killing works on Windows 10+ systems
• [ ] Document Windows-specific behavior in CONTRIBUTING.md

Add unit tests for AppState extension modules and state management

The AppState is split into 9 separate extensions (AppState+AutoKill.swift, AppState+Favorites.swift, etc.) but there are no visible test files in the repo. This is critical for preventing regressions when managing complex state like Kubernetes port forwards, tunnel connections, and auto-kill rules.

• [ ] Create platforms/macos/Tests/AppState/ directory structure
• [ ] Add AppStateAutoKillTests.swift to test AutoKillRule creation, deletion, and triggering logic
• [ ] Add AppStatePortOperationsTests.swift to test port monitoring and kill operations
• [ ] Add AppStateFavoritesTests.swift and AppStateWatchedPortsTests.swift for persistence
• [ ] Add AppStateKeyboardShortcutsTests.swift to validate shortcut handling
• [ ] Update .github/workflows/ci.yml to run swift test and report coverage metrics

Document and add integration tests for Kubernetes and Cloudflare Tunnel features

The repo contains sophisticated KubernetesDiscoveryManager.swift, PortForwardManager.swift, and TunnelManager.swift, but there's no integration test documentation or mock-based tests. New contributors can't easily understand how to test these features or verify changes work correctly.

• [ ] Create platforms/macos/Tests/Managers/ with mock Kubernetes API and Cloudflare configs
• [ ] Add KubernetesDiscoveryManagerTests.swift with mocked kubectl output for port-forward discovery
• [ ] Add PortForwardManagerTests.swift testing execution, monitoring, and conflict resolution
• [ ] Add TunnelManagerTests.swift with mocked cloudflared process and TunnelLogEntry parsing
• [ ] Add TESTING.md in CONTRIBUTING.md explaining how to run integration tests locally
• [ ] Include example kubeconfig fixtures in platforms/macos/Tests/Fixtures/

• Add unit tests for AppState+PortOperations.swift: The port killing logic (graceful + force termination) is mission-critical but no test files are visible in the file list for AppState extensions; a junior can write comprehensive tests for process termination flows.
• Extend ProcessType+Color.swift with category icons and descriptions: The project categorizes processes (Web Server, Database, Development, System) but the color extension is minimal; adding icon mappings and accessibility descriptions would improve UX and is a self-contained UI enhancement.
• Document Kubernetes discovery flow in README or inline code comments: KubernetesDiscoveryManager.swift exists but the README doesn't explain how users enable or configure K8s integration; a contributor can add step-by-step docs and code comments for this feature.

The PortKiller codebase demonstrates a reasonable security foundation for a macOS/Windows system utility. Primary concerns involve privilege escalation risks from process termination, credential management for Kubernetes and Cloudflare integrations, and dependency vulnerability scanning. The application handles sensitive operations (killing processes, managing cloud tunnels) but lacks explicit evidence

• Medium · Outdated bumpp Dependency — package.json - dependencies.bumpp. The package.json specifies bumpp version ^10.3.2. This is a release management tool with caret versioning that allows minor and patch updates automatically. Consider verifying this dependency is from a trusted source and monitor for security updates. Fix: Use npm audit to check for known vulnerabilities in bumpp and its transitive dependencies. Consider using exact version pinning (remove ^) for production builds to ensure reproducible deployments.
• Medium · Missing npm Lock File Verification — Repository root - dependency management. While bun.lock exists, there's no indication of npm package lock file (package-lock.json or yarn.lock). The bun.lock file may not be committed or properly validated in CI/CD, potentially allowing supply chain attacks. Fix: Ensure bun.lock is committed to version control and verified in CI/CD pipelines. If using npm, also maintain package-lock.json. Implement lockfile validation in pre-commit hooks.
• Medium · Potential Privilege Escalation via Process Killing — platforms/macos/Sources/AppState+PortOperations.swift, platforms/macos/Sources/PortKillerApp.swift. The application provides functionality to kill processes across the system (PortKillerApp.swift, AppState+PortOperations.swift). Without proper permission validation and logging, this could lead to unauthorized termination of critical system or other users' processes. Fix: Implement strict permission checks before killing processes. Log all process termination attempts with timestamps and user context. Consider restricting to only user-owned processes by default. Add confirmation dialogs for critical processes.
• Medium · Kubernetes Credentials Management Risk — platforms/macos/Sources/Managers/KubernetesDiscoveryManager.swift, platforms/macos/Sources/Managers/PortForwardManager.swift. The KubernetesDiscoveryManager and PortForwardManager components interact with Kubernetes clusters. Kubeconfig files containing credentials may be exposed if not handled securely. Fix: Ensure kubeconfig credentials are never logged or displayed in plaintext. Use secure credential storage (macOS Keychain). Validate Kubernetes API endpoints are HTTPS. Implement certificate pinning for Kubernetes API communication.
• Medium · Cloudflare Tunnel Configuration Security — platforms/macos/Sources/Managers/TunnelManager.swift, platforms/macos/Sources/Services/CloudflaredService.swift, platforms/macos/Sources/Models/CloudflareTunnel.swift. TunnelManager and CloudflaredService handle Cloudflare tunnel configurations. Tunnel tokens and authentication credentials could be exposed if stored insecurely or logged inappropriately. Fix: Store tunnel credentials in secure storage (macOS Keychain/Windows Credential Manager). Never log or display tunnel tokens. Use environment variables for sensitive configuration. Implement credential rotation mechanisms.
• Low · Dependency Source Verification — .github/workflows/ (ci.yml, ci-windows.yml, release.yml). The codebase relies on external package managers (npm/bun) for dependency installation. No evidence of software composition analysis (SCA) or dependency scanning in CI/CD workflows. Fix: Integrate dependency scanning tools (npm audit, Snyk, or OWASP Dependency-Check) into CI/CD pipelines. Configure GitHub dependabot for automated vulnerability alerts. Review high-severity findings before releases.
• Low · Code Signing and Release Security — platforms/macos/Resources/Info.plist, .github/workflows/release.yml. The application appears to be distributed as macOS and Windows binaries via GitHub Releases. No visible code signing configuration for Windows, and macOS signing details are not documented. Fix: Implement code signing for both macOS (Developer ID) and Windows (EV certificate). Publish signed manifests and checksums. Use secure artifact storage for releases. Document the signing process.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.