A native macOS Wi-Fi analyzer that shows what's actually on the air — without sending a packet anywhere.
I discovered that macOS-native technologies (e.g. CoreWLAN) can analyze Wi-Fi information, but there were no readily available software solutions that seemed suitable for casual use on macOS.
- Scan nearby Wi-Fi networks on 2.4 GHz, 5 GHz, and 6 GHz
- RSSI, BSSID, channel, bandwidth, and IE-derived security per network
- Manual scan and auto-scan at a 3–10 second interval (single-flight, no overlap)
- Short-term RSSI history and channel-occupancy curves via Swift Charts
- Filter by SSID, BSSID, band, and security
- CSV export
- Privacy-mode redaction for screenshots and screen sharing
- Fixture mode for development without real hardware
Note
This software is primarily written by AI agents (Codex and others).
Warning
BeaconTrace is alpha-stage software. Behavior, file formats, and CLI flags may change without notice. Not recommended for production use.
Important
Because of its strongly experimental nature, this project does not currently accept pull requests or issues.
- macOS 15 (Sequoia) or later
- Xcode 16+ installed at
/Applications/Xcode.app(the script falls back to this automatically) - A Mac with a working Wi-Fi interface (or use fixture mode)
git clone https://github.com/takuan-osho/BeaconTrace.git
cd BeaconTrace
./script/build_and_run.shThe script builds the Swift package, stages dist/BeaconTrace.app, writes the bundle Info.plist with the Location Services usage strings, stops any running BeaconTrace process, and launches the fresh bundle.
On first launch, macOS will ask for Location permission. BeaconTrace needs it solely so that CoreWLAN can return SSIDs and BSSIDs — no location is logged or transmitted.
./script/build_and_run.sh # normal launch
./script/build_and_run.sh --fixture # launch with synthetic networks (no real Wi-Fi needed)
./script/build_and_run.sh --logs # launch and stream process logs
./script/build_and_run.sh --telemetry # launch and stream OSLog subsystem logs
./script/build_and_run.sh --debug # attach lldb
./script/build_and_run.sh --verify # launch and confirm the process is aliveUse the Export CSV toolbar button to save the current (filtered) table as CSV. Sensitive identifiers can be redacted. Files are written to a location you choose; nothing is uploaded.
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift testTests are written with Swift Testing. The local Command Line Tools developer directory cannot build this package reliably, which is why a full Xcode install is required.
Sources/
BeaconTraceCore/ # Pure logic: models, IE parsers, channel plan, analysis
BeaconTrace/ # App: SwiftUI views, stores, services, scheduler
Tests/
BeaconTraceTests/ # Swift Testing suites
script/ # build_and_run.sh and verification helpers
docs/ # TDL documents: analysis, requirements, ADRs, tasks
Note: This layout reflects the current structure and is likely to evolve as the project grows.
SwiftUI Views ──▶ ScanStore (@Observable, @MainActor)
│
├─▶ LocationPermissionService
└─▶ ScanScheduler (actor)
│
└─▶ CoreWLANScanner ─▶ InformationElementParser
─▶ ChannelPlan
Note: This diagram captures the current architecture and is likely to evolve as the project grows.
The full architecture, including layer responsibilities and decision rationale, lives in docs/adr/. The overall documentation structure is described in docs/README.md.
As noted at the top of this README, this project does not currently accept external pull requests or issues while it remains an experimental, AI-agent-driven codebase. This may change in the future; until then, please feel free to fork and explore on your own.
BeaconTrace stands on the shoulders of work done by many others:
- Apple for CoreWLAN, CoreLocation, SwiftUI, Swift Charts, and Swift Testing — the entire app is a thin shell over these frameworks.
- The IEEE 802.11 working group and the public documentation around RSN, WPA, and RSNX Information Elements, which make evidence-based security display possible at all.
- Prior-art Wi-Fi analyzers that established the visual vocabulary this project borrows from.
- OpenAI's Codex and its app.
- The maintainers of the Traceable Development Lifecycle (TDL) practice.
- Agent skills and AGENT.md
- OpenAI's Build macOS Apps Plugin
- sosumi.ai
- twostraws/SwiftAgents
- My AGENTS.md is derived from it.
- twostraws/SwiftUI-Agent-Skill
- twostraws/Swift-Concurrency-Agent-Skill
- twostraws/Swift-Testing-Agent-Skill
In particular, the following software and article by acidlemon were invaluable references during implementation, and I am deeply grateful for them:
BeaconTrace is licensed under the GNU Affero General Public License v3.0.