Development · PortPilot

Get the source#

Terminal

git clone https://github.com/sriinnu/portpilot.git
cd portpilot

CLI/TUI work requires Swift 5.9+. The macOS app targets macOS 13+ and uses Xcode 15+; XcodeGen regenerates the project from project.yml. Read AGENTS.md and mission.md before changing behavior.

Three products, one shared core#

Sources/PortPilot: SwiftUI and AppKit macOS app.
Sources/PortKillerCLI: The portpilot executable, using swift-argument-parser.
Sources/PortPilotTUI: The portpilot-tui executable.
Sources/PortManagerLib: Shared discovery, process control, cron and proxy logic.
Sources/TerminalTUI: The reusable terminal UI engine.

Build without installing#

Terminal

swift build --product portpilot
swift build --product portpilot-tui
swift test

SwiftPM may resolve dependencies on an initial build. With dependencies already cached, the repository’s offline-oriented checks are:

Terminal

swift test --disable-automatic-resolution --skip-update
swift build --product portpilot --disable-automatic-resolution --skip-update

These flags are not a network sandbox. Stop if a dependency needs fetching in a restricted environment.

Check the macOS app target#

Build check

xcodebuild -project PortPilot.xcodeproj -scheme PortPilot \
  -configuration Debug -destination 'platform=macOS' \
  -disableAutomaticPackageResolution \
  -onlyUsePackageVersionsFromResolvedFile -skipPackageUpdates \
  CODE_SIGNING_ALLOWED=NO build

This checks compilation without producing a signed release. Do not launch a test app automatically: restored Guard settings can affect real processes. The Xcode CLI scheme is PortPilotCLI; the SwiftPM product is portpilot.

Contribute a small, inspectable change#

Preserve existing work. Use synthetic connections, temporary directories and disposable loopback fixtures. Keep source/test checks distinct from installed-app acceptance. Include the change, its reason, and the checks actually performed.

Report a bug or discuss an idea ↗ · Browse pull requests ↗