PrivateAI Agent is your AI personal assistant that actually gets things done. It's a cross-platform desktop application that combines the power of modern large language models with computer automation to help you accomplish tasks efficiently.

Real productivity. Not just conversation.

• 🖥️ Desktop-First: Native Electron app with beautiful React UI
• 🧠 AI-Powered: Intelligent suggestions and task automation
• 🔒 Privacy-Focused: Runs locally on your machine
• 🌍 Cross-Platform: Works on Windows, macOS, and Linux
• ⚡ Fast & Responsive: Real-time overlay and chat interface

• 💬 Intelligent Chat Interface - Natural language interaction with AI
• 🔮 Smart Suggestions - Context-aware AI suggestions in overlay window
• 🔐 Secure Authentication - Local user management with JWT tokens
• ⚡ Real-time Communication - WebSocket support for instant responses

• 🧠 Multiple AI Providers - OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Ollama, Gemini
• 🎭 Specialized Agents - Planner, Classifier, Suggestor, Title, and Computer Use agents
• 👁️ Multimodal Support - Text and vision capabilities
• 🔧 Configurable Models - Easy model switching per agent type

• 📱 Native Desktop App - Built with Electron for cross-platform compatibility
• 🎨 Modern UI - Beautiful React-based interface with dark theme
• 🔄 Overlay Window - Non-intrusive suggestions overlay
• 🌍 Cross-Platform - Works on Windows, macOS, and Linux

• ⚡ FastAPI Backend - High-performance Python API server
• 📊 SQLite Database - Lightweight local data storage
• 🔧 Modular Design - Separate frontend, backend, and AI agent components
• 🐍 Python Automation - System integration and UI extraction capabilities

privateai-agent/
├── backend/                    # FastAPI backend server
│   ├── routers/               # API endpoints
│   ├── schemas/               # Pydantic models
│   ├── .env.example          # Backend environment template
│   └── requirements.txt      # Python dependencies
├── desktop/                   # Electron desktop application
│   ├── privateai-agent-app/  # React frontend UI
│   │   ├── src/              # React components and views
│   │   ├── public/           # Static assets and logos
│   │   └── .env.example      # Frontend environment template
│   ├── aiagent/              # Python AI automation scripts
│   │   ├── main.py           # AI agent daemon
│   │   ├── suggestor.py      # Suggestion generation
│   │   ├── ui_extraction.py  # System UI analysis
│   │   └── requirements.txt  # AI agent dependencies
│   ├── electron/             # Electron utilities
│   └── main.js               # Electron main process
└── README.md

Before running PrivateAI Agent, make sure the following dependencies are installed on your machine:

• Python: python.org/downloads
• Node.js: nodejs.org/download

• ✅ Core Features: Windows, macOS, and Linux
• ⚠️ Background Automation: Windows-only (WSL-based browser control)
• ✅ Desktop App: Full cross-platform support

🚀 Simple 3-step setup - Get PrivateAI Agent running in minutes!

# Navigate to backend directory
cd backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

Edit .env file and add your AI API key:

# Database (SQLite - no setup required!)
DB_CONNECTION_STRING=sqlite:///./privateai_agent.db

# JWT Configuration
JWT_ISS=PrivateAIAgentBackend
JWT_SECRET=your-secret-key-here

# AI Provider (choose one)
OPENAI_API_KEY=your-openai-api-key-here
# ANTHROPIC_API_KEY=your-anthropic-key-here

# Model Configuration (OpenAI example)
CLASSIFIER_AGENT_MODEL_TYPE=openai
CLASSIFIER_AGENT_MODEL_ID=gpt-4

SUGGESTOR_AGENT_MODEL_TYPE=openai
SUGGESTOR_AGENT_MODEL_ID=gpt-3.5-turbo

Start the backend server:

uvicorn main:app --reload --port 8000
### 2️⃣ Desktop App Setup

**In a new terminal window:**

```bash
# Navigate to desktop directory
cd desktop

# Install Electron dependencies
npm install

# Install React app dependencies
cd privateai-agent-app
npm install

# Copy frontend environment template
cp .env.example .env

Edit privateai-agent-app/.env file:

# Backend API Configuration
REACT_APP_PROTOCOL=http
REACT_APP_WEBSOCKET_PROTOCOL=ws
REACT_APP_DNS=127.0.0.1:8000
REACT_APP_API_KEY=

Setup AI Agent Scripts:

# Navigate back to desktop directory
cd ..

# Setup Python environment for AI agent
cd aiagent
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Install AI agent dependencies
pip install -r requirements.txt

Start the desktop application:

# From the desktop directory
npm start

🎉 That's it! PrivateAI Agent will launch with:

• Backend server running on http://localhost:8000
• React frontend on http://localhost:6763
• Electron desktop app window
• AI-powered overlay and suggestions

Once PrivateAI Agent is running, you can:

• Open the main window to chat with your AI assistant
• Ask questions, request help, or give tasks
• View conversation history and manage settings

• Press the overlay hotkey to open the suggestion window
• Get context-aware AI suggestions based on your current screen
• Click suggestions to paste them into your active application
• Overlay works across all applications and websites

• AI Models: Switch between different AI providers in settings
• Authentication: Create local accounts or use Google OAuth
• Customization: Adjust overlay behavior and appearance

PrivateAI Agent uses specialized AI agents for different tasks:

• 🎯 Classifier Agent - Categorizes and routes user requests
• 📝 Title Agent - Generates conversation titles and summaries
• 💡 Suggestor Agent - Creates context-aware suggestions for overlay
• 📋 Planner Agent - Breaks down complex tasks into steps
• 🖥️ Computer Use Agent - Handles system automation tasks

• OpenAI (GPT-4, GPT-3.5-turbo)
• Anthropic (Claude models)
• Azure OpenAI (Enterprise OpenAI)
• AWS Bedrock (Multiple model providers)
• Ollama (Local model hosting)
• Google Gemini (Google's AI models)

Backend won't start:

• Ensure Python 3.9+ is installed
• Check that your AI API key is valid in .env
• Verify SQLite database permissions

Desktop app won't launch:

• Ensure Node.js 18+ is installed
• Run npm install in both desktop/ and desktop/privateai-agent-app/
• Check that backend is running on port 8000

Overlay not showing suggestions:

• Verify backend is running and accessible
• Check frontend .env has correct REACT_APP_DNS=127.0.0.1:8000
• Ensure AI API key is working (check backend logs)

macOS Permissions:

• Grant Accessibility permissions to the Electron app
• Allow screen recording if using screenshot features

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and test thoroughly
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

• Follow existing code style and patterns
• Add tests for new features
• Update documentation as needed
• Test on multiple platforms when possible

MIT License - See LICENSE file for details.

This project is open source and free to use, modify, and distribute. Commercial use is explicitly permitted.

• PrivateAI™ and PrivateAI Agent™ are trademarks of WEB3 FOUNDATION LLC
• PGPT Token is the official cryptocurrency of PrivateAI - View on CoinMarketCap
• Logos and branding assets remain property of WEB3 FOUNDATION LLC and may not be removed or modified
• Commercial derivatives are permitted but must retain PrivateAI attribution and branding
• Token-based monetization and proprietary features may be added by PrivateAI
• Legal Terms: https://www.privateai.com/legal

"PrivateAI" means WEB3 FOUNDATION LLC, a Limited Liability Company incorporated under the laws of the Cook Islands

⚠️ Disclaimer: This tool can control your computer (mouse, keyboard, etc.). Use responsibly and test in safe environments first!

• 🌍 Website: https://www.privateai.com/
• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Start a discussion
• ❓ Questions: Check existing issues or create a new one

Special thanks to @khaledshadid for the original vision, inspiration, and dedication to helping the open source community. This project builds upon their foundational work and commitment to making AI automation accessible to everyone.

Made with ❤️ by the PrivateAI Agent community