From f5f6c941e58e8a6e10ab89d027cc37d5860c8d54 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 20 Jul 2026 13:27:42 +0000 Subject: [PATCH] docs: add AGENTS.md noting macOS-only build constraints for Cloud Agents Co-authored-by: Yunfeng --- AGENTS.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d91a8f0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# AGENTS.md + +## Cursor Cloud specific instructions + +PopBar is a **native macOS 15+ menu-bar GUI application** written in pure Swift/AppKit. +It has **no backend, no database, no package manager, and no cross-platform component**. + +### Critical: cannot build/run/test on the Linux Cloud Agent VM + +Cursor Cloud Agents run on Linux (Ubuntu x86_64). This app **cannot be built, run, or +functionally tested here** — this is a platform incompatibility, not a fixable env issue: + +- Every UI/logic source file imports Apple-only frameworks: `Cocoa`/AppKit, `SwiftUI`, + `Translation`, `JavaScriptCore`, `ServiceManagement` (`SMAppService`), `CryptoKit`. + On Linux these fail with `error: no such module 'Cocoa'`. +- The build target is `arm64-apple-macosx15.0` (see `build.sh`); a Linux Swift toolchain + reports `unable to load standard library for target 'arm64-apple-macosx15.0'` (no macOS SDK). +- It is a GUI menu-bar app (`LSUIElement`) that needs a macOS window server plus + **Accessibility (TCC) permission** to read text selections — none of which exist headless/on Linux. + +### How it is actually built/run (macOS only) + +- Build + install + launch: `./build.sh` (compiles `Sources/*.swift` with `swiftc`, assembles the + `.app`, code-signs, installs to `/Applications`, launches). Requires macOS 15+ and Xcode Command + Line Tools only (no Xcode/SPM/CocoaPods). See `README.md` for permission setup and extension details. + +### Tests / lint / CI + +- There are **no automated tests, no lint config (e.g. no SwiftLint), and no CI** in this repo. + There is nothing to run for lint/test here. + +### Working on Swift source from Linux (optional, limited) + +- Only `Sources/HTMLToMarkdown.swift` and `Sources/SelectionPayload.swift` are `Foundation`-only and + can be type-checked with a Linux Swift toolchain (`swiftc -typecheck `). All other files + import Apple frameworks and will not compile off macOS. Because of this, the startup update script + is intentionally a no-op — installing the ~1 GB Linux Swift toolchain on every VM start is not + worth it for two Foundation-only files. Install it manually only if you specifically need it + (e.g. via `swiftly`).