Unlock unparalleled productivity with an AI assistant that intuitively understands and executes commands on your macOS.
The modern macOS user constantly juggles applications, manages intricate workflows, and performs repetitive tasks that break focus and diminish overall efficiency. Existing automation tools often require complex scripting or lack the contextual intelligence to truly understand user intent, leaving a significant gap in autonomous, intelligent system interaction.
holmes-ai bridges this gap by providing an intelligent, autonomous command layer for your Mac. Leveraging advanced AI, it interprets your high-level directives, understands the current system state, and executes complex sequences of actions across your applications and operating system with minimal human intervention. This empowers users to reclaim valuable time, reduce cognitive load, and achieve a state of seamless, AI-augmented productivity.
✨ Natural Language Interface: Command your Mac using plain English, eliminating the need for complex scripting or memorized commands. 🧠 Contextual Awareness: holmes-ai understands your active applications, open documents, and system status to provide highly relevant and accurate automation. 🚀 Autonomous Task Execution: Delegate multi-step workflows, from email management to creative suite operations, and watch holmes-ai execute them flawlessly. 🔗 Seamless System Integration: Deeply integrates with macOS APIs and common applications, ensuring broad compatibility and powerful control. 🔒 Secure & Private Operations: Designed with privacy in mind, processing sensitive information locally or through secure, user-controlled channels. 📈 Adaptive Learning: Continuously refines its understanding of your preferences and common tasks, improving efficiency over time.
holmes-ai is engineered for robust performance and extensibility, built upon a modular architecture.
| Technology | Purpose | Key Benefit |
|---|---|---|
| Python | Core logic, AI orchestration, system APIs | Versatility, extensive AI/ML ecosystem, rapid development |
| OpenAI API | Large Language Model (LLM) integration | Advanced natural language understanding and generation |
| AppleScript | macOS application control and automation | Native interaction with macOS applications |
| AppKit/PyObjC | Direct macOS framework interaction | Deep system control and UI automation |
| FastAPI | Local API for agent communication (optional) | High performance, asynchronous, easy to build APIs |
| SQLite | Local state management, preference storage | Lightweight, serverless, robust data persistence |
📁 holmes-ai/
├── 📄 LICENSE
├── 📄 README.md
├── 📁 src/
│ ├── 📁 core/
│ │ ├── 📄 agent.py # Main AI agent logic
│ │ ├── 📄 orchestrator.py # Task sequencing and execution
│ │ ├── 📄 memory.py # Contextual memory management
│ ├── 📁 adapters/
│ │ ├── 📄 applescript_adapter.py # Interface for AppleScript commands
│ │ ├── 📄 system_api.py # macOS system-level interactions (e.g., UI automation)
│ │ ├── 📄 application_integrations/ # Specific integrations for common apps
│ ├── 📁 llm/
│ │ ├── 📄 provider.py # LLM interaction layer
│ │ ├── 📄 prompts.py # Prompt templates and management
│ ├── 📁 ui/ # Optional desktop or web UI components
│ │ ├── 📄 main.py # UI application entry point (e.g., PyQt/Electron)
│ │ ├── 📄 assets/
│ ├── 📄 main.py # Application entry point
├── 📁 config/
│ ├── 📄 settings.json # Default and user-specific configurations
├── 📄 requirements.txt # Python dependencies
├── 📄 .env.example # Example environment variables
Ensure you have the following installed on your macOS system:
- Python 3.9+: For running the core application.
- pip: Python package installer (usually comes with Python).
- Git: For cloning the repository.
- Xcode Command Line Tools: Required for some Python packages that interact with macOS frameworks. Install with
xcode-select --install.
Follow these steps to get holmes-ai up and running on your local machine:
-
Clone the Repository:
git clone https://github.com/holmes-ai/holmes-ai.git cd holmes-ai -
Set Up a Virtual Environment: It's recommended to use a virtual environment to manage dependencies.
python3 -m venv venv source venv/bin/activate(On Windows, activate with:
.\venv\Scripts\activate) -
Install Dependencies:
pip install -r requirements.txt
-
Configure Environment Variables: Copy the example environment file and fill in your details.
cp .env.example .env
Open the newly created
.envfile and provide any required API keys (e.g.,OPENAI_API_KEY) or specific configuration parameters. -
Run holmes-ai:
python main.py
Follow any on-screen prompts or consult the
docs/directory (if present) for specific usage instructions.
We welcome contributions from the community to enhance holmes-ai! If you're interested in improving the project, please follow these guidelines:
- Fork the repository.
- Clone your forked repository to your local machine.
- Create a new branch for your feature or bug fix:
git checkout -b feature/your-feature-nameorgit checkout -b bugfix/issue-description. - Make your changes, ensuring they adhere to the project's coding standards.
- Test your changes thoroughly.
- Commit your changes with a clear and concise message:
git commit -m "feat: Add new feature for X"orgit commit -m "fix: Resolve Y issue". - Push your branch to your forked repository:
git push origin feature/your-feature-name. - Open a Pull Request against the
mainbranch of the original holmes-ai repository. Provide a detailed description of your changes.
This project is licensed under the MIT License.
The MIT License is a permissive free software license, meaning you are free to:
- Use the software for any purpose.
- Modify the software to suit your needs.
- Distribute the software.
- Sell the software.
The only significant conditions are that you must include the original copyright and license notice in any copy of the software/source, and the software is provided "as is" without warranty.
For the full text of the license, please refer to the LICENSE file in this repository.