how to contribute

How to contribute

This is the contributor guide for DroidProxy. There is no CONTRIBUTING.md in the repo, so these pages are the canonical reference for building, testing, debugging, and shipping changes.

DroidProxy is a native macOS menu bar app written in Swift 5.9 (SwiftUI + AppKit), targeting arm64 macOS 13+. The executable target is CLIProxyMenuBar and the bundle id is com.droidproxy.app. It runs two local servers:

• ThinkingProxy on 127.0.0.1:8317 — the user-facing TCP proxy. See Thinking proxy.
• A bundled CLIProxyAPI backend on 127.0.0.1:8318, managed as a child process. See Server manager.

Source of truth

The compiled app code lives under src/. Treat these as authoritative:

• /Users/nikhilanand/droidproxy/src/Sources/** — all Swift source plus bundled resources (src/Sources/Resources/).
• /Users/nikhilanand/droidproxy/src/Info.plist — bundle metadata.
• /Users/nikhilanand/droidproxy/create-app-bundle.sh — assembles and signs DroidProxy.app.

There is no longer a mirrored top-level resources/ tree; older notes referencing one are stale.

Build, test, and dev loop

Run all swift commands from /Users/nikhilanand/droidproxy/src (that is where Package.swift lives), not the repo root.

# Debug build
cd src && swift build

# Run tests
cd src && swift test

# Release .app bundle (run from repo root)
./create-app-bundle.sh

# Preferred dev loop: kill, rebuild, relaunch the signed .app
./dev-relaunch.sh

The app is LSUIElement, so swift run does not launch it — you must build the .app bundle and open it. ./dev-relaunch.sh does this for you. See Development workflow.

PR process

1. Branch off main, make changes under src/, and open a pull request against main.
2. Opening a PR that touches src/**, create-app-bundle.sh, or .github/workflows/pr-build.yml triggers pr-build.yml — a compile-only check that runs swift build -c release --arch arm64 on a macos-26 runner. A green check there means the release build will also compile (no signing or notarization runs on PRs).
3. Automated Droid review workflows comment on the PR: droid-review.yml runs on every non-draft PR, and droid.yml responds to @droid mentions in comments, reviews, issues, and PR bodies.
4. Merging src/** changes into main triggers the release pipeline. See Deployment.

Sub-pages

• Development workflow — the branch → code → build → test → PR cycle.
• Testing — the XCTest suite and what to cover.
• Debugging — logs, common failures, and the management dashboard.
• Patterns and conventions — codebase conventions to follow before editing.
• Tooling — the build system, CI workflows, and signing/notarization tools.