Skip to content

docs: document macOS-only build constraints for Cloud Agents #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
WinfredGe wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: document macOS-only build constraints for Cloud Agents #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <file>`). 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`).