{PurrAI}

Your adorable AI companion living in your machine

Features • Installation • Usage • Configuration • Tech Stack

PurrAI is a lightweight, cross-platform desktop application that brings the power of AI to your fingertips. With a cute black kitten mascot living in your system's, you can instantly access AI assistance for any task - from answering questions to analyzing images and documents.

Built with modern web technologies and packaged as a native application, PurrAI runs seamlessly on Linux, Windows, and macOS while maintaining a minimal footprint.

• 🔑 Multi-Provider Support - Configure multiple AI providers (OpenAI, Anthropic, Ollama, etc.)
• 💬 Intelligent Chat Interface - Natural conversation with AI powered by PrismPHP
• 🎙️ Audio detection - Speak by voice, use it completely locally with LaravelWhisper or online service.
• 📎 Document Attachment - Upload and analyze documents of any type (past, drag and drop, etc.)
• 📝 Text Analysis - Analyze text from any source.
• 🖼️ Image Analysis - Paste images for AI processing
• 🖥️ System access - Search or list files and ask about them (or use dangerous commands like delete, move, rename - if you give the right permissions in the "Danger" area in Settings)
• 💾 Conversation History - All chats saved locally in SQLite with search
• 🌓 Dark/Light Mode - Beautiful interface that adapts to your system theme
• 🔒 Privacy-Focused - Local Ollama models and LaravelWhisper (for audio) run in your system without exposing your data
• 🌐 i18n Support - Available in multiple languages (en, pt, es,)

• PHP 8.4+
• Composer
• Node.js 18+ & npm 10+
• SQLite

# Clone the repository
git clone https://github.com/b7s/purr-ai.git

cd purrai

# Install PHP dependencies
composer install

# Install JavaScript dependencies
npm install

# Copy environment file
cp .env.example .env

# Publishing the Electron project
php artisan native:install --publish

After run native:install, add "afterInstall" to your nativephp/electron/electron-builder.mjs (if "deb" not exists, add it after "linux"):

   linux: {
   /*...*/
   },
   deb: {
      afterInstall: join(
         process.env.APP_PATH,
         "scripts",
         "fix-permission-linux-app-after-install.tpl",
      ),
   },

It will attempt to correct permission issues when installing the builded app in "/opt".

Attention: Whenever you update the project (composer update), the files in "nativephp" will be overwritten and you will need to add the script again.

# Development mode
composer native:dev

# Production build
php artisan native:build

Ensure the correct privileges for Electron while performing your tests. Use the command:

bash scripts/fix-electron-sandbox.sh

Make the file executable before running it: chmod +x scripts/fix-electron-sandbox.sh. Sometimes you will need to run this command again as permissions may be lost after updating the project.

1. Click the kitten icon in your menu bar
2. Navigate to Settings (⚙️)
3. Add your AI provider API keys:
   • OpenAI
   • Anthropic Claude
   • Google Gemini
   • Or configure local Ollama
4. Audio detection if you wish

If you're installing PurrAI from a .deb package and encounter a sandbox error, run these commands after installation:

# Fix chrome-sandbox permissions
sudo chown root:root /opt/PurrAI/chrome-sandbox
sudo chmod 4755 /opt/PurrAI/chrome-sandbox

# Verify permissions (should show -rwsr-xr-x)
ls -la /opt/PurrAI/chrome-sandbox

# Launch PurrAI
purrai

Why is this needed? The Electron chrome-sandbox requires SUID permissions to run securely. Due to build system limitations, these permissions must be set manually after installation.

1. Start a conversation - Type your question in the input box
2. Attach files - Click the attachment icon to upload documents
3. Paste images - Use Ctrl+V (Cmd+V on Mac) to paste screenshots
4. View history - Click the history dropdown to browse past conversations
5. New chat - Click the new chat button to start fresh

Navigate to Settings to configure your preferred AI providers:

// Supported providers via PrismPHP
- OpenAI (GPT)
- Anthropic (Claude)
- Google (Gemini)
- Ollama (Local models)
- And more...

For privacy-focused users, configure Ollama to run AI models locally:

1. Install Ollama
2. Pull your preferred model: ollama pull llama2
3. Add Ollama endpoint in Settings
4. Select local model in chat

• Laravel 12 - Modern PHP framework
• Livewire 3 - Reactive components
• SQLite - Lightweight database
• PrismPHP - Multi-provider AI integration
• LaravelWhisper - Audio detection

• Alpine.js 3 - Minimal JavaScript framework
• Tailwind CSS 4 - Utility-first CSS with Glassmorphism style
• Iconoir - Beautiful open-source icon library (CSS)
• Blade Templates - Laravel's templating engine

• NativePHP 2 - Cross-platform desktop wrapper
• Electron - Native application runtime

composer test

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.