CursorMobileS

Opinionated macOS setup for Cursor Agent and GitHub — with a local browser dashboard so you can drive everything from one place.

Turn a Mac (Mac mini on the desk, or any Mac you SSH into) into a repeatable “dev box” profile: install prerequisites, wire GitHub (gh), install the Cursor Agent CLI, and register a LaunchAgent worker — without memorizing a long checklist.

On GitHub (find & share)

The repository About lists topics such as cursor-agent, macos, github-cli, launchagent, and onboarding so it shows up in GitHub search and Explore. Use Discussions for Q&A and ideas; use Issues for bugs.

Why this feels good in practice

• Fast onboarding: one ./setup, then operate from the dashboard.
• Idempotent flow: rerun safely; already-done steps are skipped.
• Per-workspace continuation: fix only what is missing for that folder.
• Secure-by-default dashboard: localhost bind (127.0.0.1) unless you explicitly enable LAN exposure.

Project trust signals

• CI runs shell syntax, shellcheck, smoke checks, and README asset validation on PR/push.
• Tagged releases (v*) publish the bundle and SHA-256 checksums automatically.
• Security policy, architecture overview, contribution guide, issue templates, and PR template are included.

---

What it looks like (your browser, local only)

This is the most important part of the project: the dashboard home and the exact click flow.
All screenshots below are real captures and keep the URL on 127.0.0.1 only.

Screen A — Home (start here)

Open ./setup, then open the printed URL.
This screen gives you the full command center: sidebar steps, quick check, and workspace list.

Screen B — Quick Check expanded

Open the Quick check fold to verify GitHub, Agent CLI, and Worker before you do anything else.

Screen C — Other Projects expanded

Open Other projects to review all discovered workspaces (not only favorites).
If a project is missing, go back to sidebar step 1 (Add folder in Finder).

Screen D — Workspace actions expanded

Open a workspace row to reveal per-project action buttons.
Use this for continue setup and project-specific execution.

Click order (simple and strict)

Order	Where to click	Why
1	Sidebar Add folder in Finder	Register roots so projects appear.
2	Sidebar Run setup script	Run full setup path (GitHub/Agent).
3	Expand Quick check	Confirm top-level integrations are healthy.
4	Open the target workspace row	Continue setup only for the target repo.
5	Refresh	Re-sync statuses and running ports.
6	Sidebar Stop dashboard server	Shut down cleanly when done.

Korean UI sample (same layout)

KO/EN toggle keeps the same layout and workflow.

Re-generate README screenshots (macOS + Google Chrome):

./scripts/capture-dashboard-screenshots.sh
./scripts/capture-readme-screenshots.sh --auto-start

Shortest path to this screen: clone the repo → chmod +x setup && ./setup → open the printed URL.

flowchart LR
  S1["1 · Folders\n~/.cursor-setup/workspaces.txt\nor Add folder"] --> S2["2 · Setup\nRun setup script\nTerminal"]
  S2 --> S3["3 · Dashboard\nhttp://127.0.0.1:port"]

Loading

Reading the first page quickly

• Sidebar step 1: workspace root registration (workspaces.txt source).
• Sidebar step 2: full setup entrypoint in Terminal.
• Quick check: health summary for GitHub/Agent/Worker.
• Workspace row fold: per-project action menu and details.
• Refresh: status/port rescan without restarting.

---

Table of contents

• What it looks like (your browser, local only)
• Who this is for
• Concept: how the pieces fit together
• The local dashboard (what you see on screen)
• Quick start
• Single-file bundle (double-click)
• Workspace discovery
• Per-project dev commands & ports
• Command-line usage
• Environment variables
• Quality and release process
• Security & privacy
• Security policy
• Architecture
• Contributing
• Changelog
• Requirements
• License

---

Who this is for

• You run Cursor Agent on a Mac and want LaunchAgent + logs in predictable locations.
• You use GitHub and want gh auth, remotes, and repo hygiene without repeating manual steps.
• You like a local web UI (no cloud account for the dashboard itself) that lists projects and opens Terminal where the script continues only what is still missing.

---

Concept: how the pieces fit together

The default entrypoint starts a small Python HTTP server on your Mac and binds to 127.0.0.1 by default.
When you click actions, Terminal runs the same setup script for a chosen folder; the script is idempotent-ish: it skips steps that already look done.
If you need cross-device access on a trusted network, opt in with CURSOR_DASH_LAN=1.

flowchart TB
  subgraph User["You"]
    B[Browser]
    T[Terminal.app]
  end

  subgraph OptionalLAN["Optional LAN client"]
    OB[Other device browser]
  end

  subgraph Local["Your Mac — local only"]
    D[Dashboard HTTP server]
    S[setup script]
    L[~/.cursor-setup config]
    LA[LaunchAgents plist]
  end

  subgraph Remote["Optional / external"]
    GH[GitHub API]
    CR[Cursor install / agent]
  end

  B -->|http://127.0.0.1:port| D
  OB -.->|LAN opt-in only| D
  D -->|opens| T
  T --> S
  S --> L
  S --> GH
  S --> CR
  S --> LA

Loading

Typical flow:

sequenceDiagram
  participant U as User
  participant Dash as Local dashboard
  participant Term as Terminal
  participant Setup as setup / bundle

  U->>Dash: Open URL (printed on run)
  Dash->>U: Status cards + workspace list
  U->>Dash: Click “continue setup” for a folder
  Dash->>Term: Open Terminal with that folder
  Term->>Setup: Run setup for workspace
  Setup->>Setup: Git / gh / agent as needed

Loading

---

The local dashboard (what you see on screen)

The UI is intentionally GitHub Desktop–inspired: a sidebar, a main column of “cards”, and a scrollable list of workspaces (folders). Everything is generated as static HTML refreshed by the embedded server — no separate frontend build step.

Global status cards (top area)

Area	What it tells you
GitHub	Whether gh is logged in (and your username when the CLI allows it).
Cursor Agent	Whether ~/.local/bin/agent is installed.
Cursor worker (global)	LaunchAgent com.cursor.agent.worker — plist present, running or stopped, and which working directory it is bound to.

Status dots are a quick read: healthy / warning / not configured.

Workspace rows (project list)

Each row is one discovered folder. You will usually see:

• Folder name and full path (monospace).
• Git branch and origin remote URL (or a hint if not a Git repo).
• A one-line Git status summary when applicable.
• Worker line — whether the global Cursor worker is aligned with this folder, running, stopped, or pointed elsewhere.

Actions (labels depend on locale) let you open the folder in Finder, copy paths, open a local dev URL when a port is known, and continue setup in Terminal for only the missing steps.

Sidebar & settings

• Search / filter workspaces when the list grows.
• Language: Korean or English for dashboard strings (toggle + cookie). Default is English; set CURSOR_DASH_LANG=ko before launch for Korean-first.
• Optional branding via CURSOR_DASH_BRAND.
• Repo rename (GitHub): uses gh repo rename and expects github.com as origin.

---

Quick start

1. Clone this repository on your Mac.

   git clone <your-fork-or-upstream-url>
   cd CursorMobileS

2. Run (default = local dashboard — the UI in the screenshot above):

   chmod +x setup
   ./setup

3. Open the URL printed in the terminal (usually http://127.0.0.1:port) — the same address appears under Step 3 in the sidebar.

4. Follow the sidebar order: folders → setup script → use the dashboard. To configure one project, find it in the list and use Continue setup (or equivalent) so Terminal runs only what is still missing for that folder.

Optional (trusted LAN only):

CURSOR_DASH_LAN=1 ./setup

Full terminal wizard (no dashboard):

./setup --full-wizard

Non-interactive defaults are used unless you pass --interactive.

---

Single-file bundle (double-click)

To ship one file (for example via GitHub Releases):

./scripts/build-bundle.sh

This writes dist/MacMini-Cursor-Setup.command. Double-click in Finder, or:

chmod +x dist/MacMini-Cursor-Setup.command
./dist/MacMini-Cursor-Setup.command

On first open of a downloaded script, use Finder → right-click → Open to satisfy Gatekeeper.

---

Workspace discovery

Folders appear on the dashboard from:

1. ~/.cursor-setup/workspaces.txt — one path per line (# comments allowed). See templates/workspaces.example.txt.
2. ~/Dev/* — each immediate child directory.
3. Git roots under ~/Dev — up to depth 8 (with ignores for node_modules, vendor, etc.).

Duplicate paths are deduplicated.

---

Per-project dev commands & ports

Optional file: ~/.cursor-setup/workspace-services.jsonl — one JSON object per line, keyed by workspace path. Lets the dashboard show “open dev server” style links when a port is known.

Example and field meanings: templates/workspace-services.jsonl.example.

• exec: run a .command or script via bash (good for project-local starters).
• shell: a one-liner shell command (e.g. npm run dev).
• port (or devPort, listen, listenPort): port number for quick links.

The dashboard can also help register entries; they are merged into this JSONL file.

---

Command-line usage

Mode	Command
Default	./setup — local dashboard
Full wizard	./setup --full-wizard
One workspace (no dashboard)	./setup --workspace /path/to/project
GUI prompts (osascript)	./setup --gui
Terminal-only wizard	./setup --cli
Print status	./setup --status [folder]
Dry run	./setup --dry-run
Help	./setup --help

---

Environment variables

Variable	Purpose
CURSOR_DASH_LANG	en or ko — dashboard language (default en).
CURSOR_DASH_HOST	Bind address for the HTTP server (default 127.0.0.1).
CURSOR_DASH_LAN	Set 1 to expose dashboard on LAN (0.0.0.0) when CURSOR_DASH_HOST is not set.
CURSOR_DASH_PORT	Preferred port (default 58741 if free; otherwise an ephemeral port).
CURSOR_DASH_BRAND	Custom title string in the dashboard header.
CURSOR_SETUP_DEFAULT_WORKSPACE	Default folder for status and some flows.
CURSOR_SETUP_FAST_PROMPTS	1 (default) skips many terminal prompts; 0 with --interactive asks more.

---

Quality and release process

• CI (.github/workflows/ci.yml): bash -n, shellcheck, smoke checks, and README asset checks.
• Release (.github/workflows/release.yml): on v* tags, builds dist/MacMini-Cursor-Setup.command and publishes SHA256SUMS.txt.
• Bundle integrity rule: if you change setup, scripts/lib/*, or templates, run ./scripts/build-bundle.sh before commit.

Quick local validation:

./scripts/ci-smoke.sh

---

Security & privacy

• The dashboard server binds to localhost by default (127.0.0.1) to reduce accidental LAN exposure.
• To intentionally open it on LAN, use CURSOR_DASH_LAN=1 ./setup (or set CURSOR_DASH_HOST=0.0.0.0) on a trusted network only.
• Dashboard POST actions apply a same-origin check and standard browser security headers (CSP / frame deny / nosniff).
• Secrets (env files, tokens) must stay out of git — see .gitignore.
• Before git push, run ./scripts/git-safe-verify.sh to catch tracked private keys and other sensitive paths.
• Scripts may run curl | bash for the official Cursor install script when you opt in — review Cursor’s install documentation if you need to comply with corporate policy.
• gh requires you to authenticate with GitHub; nothing in this repo replaces GitHub’s OAuth or token flows.

---

Requirements

• macOS (the entrypoint checks for Darwin).
• Python 3 for the default dashboard server.
• Git; Homebrew recommended for gh.
• Network access when installing tools or talking to GitHub / Cursor.

---

License

This project is licensed under the MIT License.

---

Acknowledgements

Built for workflows around Cursor and GitHub CLI. Product names belong to their respective owners.