ghost-os

<p align="center"> <img src="logo-animated.gif" width="140" alt="Ghost OS"> </p> <h1 align="center">Ghost OS</h1> <p align="center"><em>Full computer-use for AI agents.</em></p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a> <img src="https://img.shields.io/badge/platform-macOS%2014%2B-black.svg" alt="macOS 14+"> <img src="https://img.shields.io/badge/swift-6.2-orange.svg" alt="Swift 6.2"> <img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP Compatible"> </p>

---

Your AI agent can write code, run tests, search files. But it can't click a button, send an email, or fill out a form. It lives inside a chat box.

Ghost OS changes that. One install, and any AI agent can see and operate every app on your Mac.

What's New   <img src="https://img.shields.io/badge/v2.2.1-March%202026-brightgreen.svg" alt="v2.2.1">

Self-learning recipes. Show Ghost OS how to do something once, and it remembers forever.

• ghost_learn_start -- Begin watching the user perform a task
• ghost_learn_stop -- Stop and return the enriched action sequence
• ghost_learn_status -- Check recording progress

The user performs the task manually (clicking, typing, switching apps). Ghost OS observes every action through a CGEvent tap enriched with accessibility tree context. Claude synthesizes the raw observation into a parameterized, replayable recipe.

No screenshots needed. No vision model. Just the accessibility tree and your keyboard/mouse.

User:    "Watch me send an email."
Agent:   ghost_learn_start task_description:"send email in Gmail"
         ...user performs the task...
Agent:   ghost_learn_stop
         -> 8 actions with full AX context
         -> Synthesizes recipe with 3 parameters: recipient, subject, body
         -> ghost_recipe_save
User:    "Send an email to bob about the Q4 report"
Agent:   ghost_run recipe:"gmail-send-learned" params:{...}

Requires Input Monitoring permission (System Settings > Privacy & Security > Input Monitoring). Run ghost setup to configure.

<details> <summary>Previous: v2.1.2</summary>

4 new tools. ghost_annotate, ghost_hover, ghost_long_press, ghost_drag. Pinned vision sidecar dependencies, fixed vision model download, Chinese/CJK input support (thanks @junshi5218).

</details>

Thank you to the 500+ people who have starred this project. You are why we keep building. If you want to contribute directly, we would love that. See CONTRIBUTING.md.

You:     "Send an email to sarah@company.com about the Q4 report"
Agent:   ghost_run recipe:"gmail-send" params:{recipient, subject, body}
         → Compose opens, fields fill, email sends. Done.

Setup

Recipes in Action

Send emails and download papers. Any app. Any workflow.

Beyond the Browser

Slack me...