Ghost OS
Give MCP agents structured control of native macOS apps and reusable learned workflows.
- Source repo
- ghostwright/ghost-os
- Stars
- ★ 1.7k
- Last updated
- 6mo ago
- License
- MIT
- Primary language
- Swift
- FA score
- 0/100 · Major gaps
At a glance
- Works with
- Platform-specificClaude Code
- You'll need
- Typical use
- A macOS developer using Claude Code who needs an agent to fill Gmail fields and send a report email.
- Main limitation
- Its core runtime is macOS 14+, so it is not a drop-in cross-platform desktop automation option.
- Source review
- 0/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
Ghost OS is a Swift MCP server that gives AI clients computer-use capabilities on a local Mac through stdio. It reads the macOS accessibility tree for structured application and UI-element data, with an optional local ShowUI-2B vision model for cases where accessibility data is insufficient. Its 29 tools cover UI inspection, mouse and keyboard actions, window control, screenshots, visual grounding, and recipe management. It can also observe a user performing a task through a CGEvent tap and return an accessibility-enriched action sequence for a parameterized, replayable JSON recipe. The documented deployment boundary is macOS 14+ and the documented clients include Claude Code, Cursor, VS Code, and other MCP clients.
An MCP client can call ghost_context for the current app, window, URL, focused element, and interactive elements, and use ghost_state, ghost_find, ghost_read, ghost_inspect, or ghost_element_at to inspect the UI. It operates apps with ghost_click, ghost_type, ghost_press, ghost_hotkey, ghost_hover, ghost_long_press, ghost_drag, ghost_scroll, ghost_focus, and ghost_window, while ghost_wait waits for UI changes. When the AX tree cannot adequately describe a web or dynamic interface, ghost_ground and ghost_parse_screen use the local ShowUI-2B model for visual grounding. Workflows can be installed with ghost_recipe_save, examined with ghost_recipe_show, run with parameter substitution through ghost_run, and removed with ghost_recipe_delete. Learning mode uses ghost_learn_start to observe user actions, ghost_learn_stop to return the enriched sequence, and ghost_learn_status to report recording state.
- A macOS developer using Claude Code who needs an agent to fill Gmail fields and send a report email.
- A researcher who repeatedly searches arXiv and downloads papers, and wants to save the completed process as a parameterized recipe.
- An operations user moving between Slack, Finder, and other native Mac applications as part of a recurring desktop workflow.
- A team lead who wants to review the JSON steps of a proven desktop workflow before sharing it with colleagues.
- A user automating a dynamic web app whose target control is not sufficiently exposed through the accessibility tree and needs local visual grounding.
How do you install or deploy this agent?
Ghost OS supports macOS 14+. Install and configure it with Homebrew:
brew install ghostwright/ghost-os/ghost-os
ghost setupAccording to the documentation, ghost setup configures permissions, MCP, recipes, and the vision model. To build from source:
git clone https://github.com/ghostwright/ghost-os.git
cd ghost-os
swift build
.build/debug/ghost setupSource builds require Swift 6.2+. No account or API key requirement is documented. Accessibility and Screen Recording permissions are required; learning mode additionally requires Input Monitoring.
How do you use this agent?
After ghost setup, use the Ghost OS MCP server from an MCP-capable client. Start with ghost_context to inspect the active UI. For example, run an installed recipe with ghost_run recipe:"gmail-send" params:{"recipient":"[email protected]","subject":"Hello","body":"World"}. To learn a workflow, call ghost_learn_start task_description:"send email in Gmail", perform the task manually, call ghost_learn_stop, then save the returned workflow with ghost_recipe_save. Run ghost doctor to check permissions, MCP configuration, recipes, AX-tree access, and vision components.
What are this agent's strengths and limitations?
- Uses the macOS accessibility tree for structured UI data rather than relying solely on screenshots, with a local ShowUI-2B fallback for visual grounding.
- Stores workflows as inspectable JSON recipes and runs them with parameter substitution through
ghost_run. - Covers native-app control, including windows, keyboard and pointer actions, UI reading, and recipe execution rather than browser-only automation.
- Exposes its capabilities through MCP over stdio and explicitly documents Claude Code alongside other MCP clients.
- Its core runtime is macOS 14+, so it is not a drop-in cross-platform desktop automation option.
- Adoption requires Accessibility and Screen Recording permissions; workflow learning also requires Input Monitoring.
- Interfaces with weak accessibility data depend on the local ShowUI-2B vision fallback; the diagnostic example lists the model at 3.0 GB.
- The documented recipe-synthesis example uses Claude, while equivalent configuration and results for other models are not documented.
How does this agent compare with similar options?
The repository compares Ghost OS with Anthropic Computer Use, OpenAI Operator, and OpenClaw. It positions Ghost OS around an accessibility tree plus a local VLM, native macOS app control, and JSON workflow recipes; its table describes Anthropic Computer Use and OpenAI Operator as screenshot-based and OpenClaw as browser-DOM-based.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Ghost OS This agent | 0 · Major gaps | ★ 1.7k | 6mo ago | Swift | Claude Code |
| Open Computer Use (MCP desktop service) | 44 · Major gaps | ★ 2.1k | 7d ago | Swift | Codex · Claude Code |
| Clawd Cursor | 74 · Some gaps | ★ 403 | today | TypeScript | Codex · Claude Code |
| macOS Harness | 55 · Major gaps | ★ 886 | 1mo ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence is limited to README and LICENSE; no code, configuration, or security documentation provided. Least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, and source attribution cannot be verified. All criteria scored 0 due to insufficient evidence.
No code or tests to assess self-consistency, dependency availability, or failure messages. Claims in README (e.g., '100% reliable') are unverifiable. All criteria scored 0.
README describes target audience and scenarios but lacks specifics. Capability boundaries, trigger precision, and environment fit are not clearly defined in code or documentation. All criteria scored 0.
README provides installation instructions and examples but lacks architecture details, known limitations, version history, and maintenance responsibility. License exists but is unverified. All criteria scored 0.
README claims value but lacks verifiable evidence of output usability, marginal value, or cost-benefit. All criteria scored 0.
All claims come from README with no independent sources or traceable evidence. Facts and inferences are not separated. All criteria scored 0.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- Based solely on README and LICENSE; code quality, security, and functionality cannot be verified.
- No code or tests provided; all claims are unverified.
- Publisher identity is unverified; do not infer reliability or safety.
FAQ
Does Ghost OS require a paid account or API key?
What applications can it control?
Which macOS permissions are needed?
What happens when an accessibility tree does not expose the target UI?
ghost_ground or ghost_parse_screen for local ShowUI-2B visual grounding. ghost doctor reports the vision component status.Can a workflow be reviewed before it runs?
ghost_recipe_show displays their full steps and configuration before ghost_run executes them.