{"id":21713525,"url":"https://github.com/adeelahmad/macpilot","last_synced_at":"2025-10-10T19:34:46.897Z","repository":{"id":264706919,"uuid":"894153700","full_name":"adeelahmad/MacPilot","owner":"adeelahmad","description":"🤖 AI-powered macOS automation framework - Control your Mac with natural language using GPT models. No code needed, just English instructions!","archived":false,"fork":false,"pushed_at":"2024-11-26T10:22:20.000Z","size":1575,"stargazers_count":62,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-10T19:34:46.222Z","etag":null,"topics":["agent","agi","ai","artificial-intelligence","automation","gpt","llama","llm","local-ai","macos","natural-language-processing","productivity","python","workflow-automation","workflow-automations"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adeelahmad.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-25T21:10:21.000Z","updated_at":"2025-10-04T04:20:02.000Z","dependencies_parsed_at":"2025-10-07T08:32:55.204Z","dependency_job_id":"0285c68c-0822-4d6b-b1cc-89c84ddba7c1","html_url":"https://github.com/adeelahmad/MacPilot","commit_stats":null,"previous_names":["adeelahmad/macpilot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/adeelahmad/MacPilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2FMacPilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2FMacPilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2FMacPilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2FMacPilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adeelahmad","download_url":"https://codeload.github.com/adeelahmad/MacPilot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2FMacPilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005030,"owners_count":26083827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agi","ai","artificial-intelligence","automation","gpt","llama","llm","local-ai","macos","natural-language-processing","productivity","python","workflow-automation","workflow-automations"],"created_at":"2024-11-26T00:17:18.715Z","updated_at":"2025-10-10T19:34:46.862Z","avatar_url":"https://github.com/adeelahmad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 MacPilot - Advanced macOS UI Automation Framework\n\n\u003cdiv align=\"center\"\u003e\n\n[![GitHub stars](https://img.shields.io/github/stars/adeelahmad/macpilot?style=social)](https://github.com/adeelahmad/macpilot/stargazers)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)\n[![Platform](https://img.shields.io/badge/platform-macOS-lightgrey)](https://www.apple.com/macos)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n**Native macOS UI Automation with GPT-Powered Intelligence**\n\n[Key Features](#-key-features) •\n[Architecture](#%EF%B8%8F-architecture) •\n[Installation](#-installation) •\n[Usage](#-usage) •\n[Roadmap](#-roadmap) •\n[Contributing](#-contributing)\n\n\u003c/div\u003e\n\n## 🌟 What is MacPilot?\n\nMacPilot is a state-of-the-art macOS UI automation framework that combines native Apple technologies with GPT intelligence to enable human-like interaction with your Mac. Write instructions in plain English, and let MacPilot handle the automation.\n\n### Perfect For:\n- 🔄 **Process Automation** - Automate repetitive UI tasks\n- 🧪 **UI Testing** - Test macOS applications\n- 🤖 **Desktop RPA** - Build robotic process automation\n- 🔍 **Screen Analysis** - Extract data from UI elements\n- 🧭 **Workflow Automation** - Create complex UI workflows\n\n## ✨ Key Features\n\n### 🧠 Core Intelligence\n- **GPT Integration** - Natural language instruction processing\n- **Vision Framework** - Advanced UI element detection\n- **State Awareness** - Real-time system state tracking\n- **Pattern Recognition** - Learned UI interaction patterns\n- **Self-healing** - Automated error recovery\n\n### 🎯 Native Integration\n- **Apple Vision** - Native OCR and element detection\n- **AppleScript** - Deep OS integration\n- **Accessibility APIs** - Comprehensive UI control\n- **Cocoa/AppKit** - Native macOS frameworks\n- **Core Graphics** - Low-level screen capture\n\n### 🛠 Developer Experience\n- **Async Architecture** - Built on modern async Python\n- **Type Safety** - Full Pydantic validation\n- **Actor System** - Modular action execution\n- **State Management** - Comprehensive UI state tracking\n- **Pattern System** - Reusable interaction patterns\n\n### 🔄 Application Control\n- **Chrome Control** - Deep browser automation\n- **Finder Operations** - File system automation\n- **System Control** - OS-level operations\n- **Menu Navigation** - Application menu control\n- **Window Management** - Window state control\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TD\n    A[Natural Language Instructions] --\u003e B[GPT Analysis Layer]\n    B --\u003e C[Action Planning]\n    C --\u003e D[Actor System]\n    D --\u003e E[UI Interaction Layer]\n    E --\u003e F[State Management]\n    F --\u003e B\n```\n\n### Core Components:\n1. **Instruction Processing** - GPT-powered instruction analysis\n2. **State Management** - UI state tracking and validation\n3. **Actor System** - Modular action execution\n4. **Pattern System** - Reusable interaction patterns\n5. **Vision System** - UI element detection and OCR\n6. **Recovery System** - Automated error handling\n\n## 🚀 Installation\n\n```bash\n# Install from PyPI\npip install macpilot\n\n# Or install from source\ngit clone https://github.com/adeelahmad/macpilot.git\ncd macpilot\npip install -e .\n```\n\n## 📝 Usage\n\n### Basic Example\n```python\nfrom macpilot import MacPilot\n\nasync def main():\n    pilot = MacPilot()\n\n    # Simple automation\n    await pilot.execute(\"Open Chrome and search for 'Python tutorials'\")\n\n    # Complex workflows\n    await pilot.execute(\"\"\"\n        1. Find all PDFs in Downloads\n        2. Create a folder named 'Documents'\n        3. Move PDFs older than 30 days\n        4. Create a summary spreadsheet\n    \"\"\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### Pattern Example\n```python\nfrom macpilot.patterns import register_pattern\n\n@register_pattern(\"login_flow\")\nasync def handle_login(username: str, password: str):\n    return [\n        {\"action\": \"click\", \"target\": \"username_field\"},\n        {\"action\": \"type\", \"text\": username},\n        {\"action\": \"click\", \"target\": \"password_field\"},\n        {\"action\": \"type\", \"text\": password},\n        {\"action\": \"click\", \"target\": \"login_button\"}\n    ]\n```\n\n## 📋 Todo \u0026 Roadmap\n\n### High Priority\n- [ ] User Interface\n  - [ ] CLI tool for automation scripts\n  - [ ] Web dashboard for monitoring\n  - [ ] Visual workflow builder\n\n- [ ] Core Features\n  - [ ] Local LLM support\n  - [ ] Improved error recovery\n  - [ ] Performance optimizations\n\n### Medium Priority\n- [ ] Documentation\n  - [ ] API reference\n  - [ ] Pattern library\n  - [ ] Example gallery\n\n- [ ] Testing\n  - [ ] Increase test coverage\n  - [ ] Integration tests\n  - [ ] Performance benchmarks\n\n### Low Priority\n- [ ] Additional Features\n  - [ ] Safari automation support\n  - [ ] Network request monitoring\n  - [ ] Advanced screen recording\n  - [ ] Workflow marketplace\n\n## 🤝 Contributing\n\nContributions are welcome! Areas we're focusing on:\n\n- 📝 Documentation improvements\n- 🧪 Testing and bug fixes\n- 🎯 New application actors\n- 🔄 Pattern implementations\n- 🐛 Performance optimizations\n\nCheck our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📜 License\n\nMacPilot is MIT licensed. See [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- Apple for macOS APIs\n- OpenAI for GPT models\n- Python community\n\n\u003cdiv align=\"center\"\u003e\n\nMade with ❤️ by the MacPilot Team\n\n[🌐 Website](https://macpilot.dev) •\n[📖 Documentation](https://docs.macpilot.dev) •\n[💬 Discord](https://discord.gg/macpilot)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadeelahmad%2Fmacpilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadeelahmad%2Fmacpilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadeelahmad%2Fmacpilot/lists"}