1. Getting Started

This guide helps you get Clippy running for the first time, whether you want to use it as a local AI companion, a desktop command assistant, or a configurable interface for multiple model providers.

Prerequisites

• Node.js (>=20)
• npm or pnpm
• Operating system: Windows/macOS/Linux

What You Can Configure

• AI provider and default model
• System prompt and response behavior
• Voice and text-to-speech output
• Memory approval, relationship stats, and long-term profile data
• Desktop tools, web tools, and notification integrations

Development

git clone https://github.com/JonusNattapong/Clippy.git
cd Clippy
npm ci
cp .env.example .env
npm run start

After launch, use the Settings panel to select your model provider. If no API key is configured, you can still prepare the app shell and switch to Ollama later.

---

2. Installation

Download prebuilt releases from the project's GitHub Releases page. If you prefer building from source, clone the repository and run the development scripts locally.

Installation Flow

1. Fetch the installer or zip package for your operating system
2. Extract files if needed and run the packaged app
3. Complete first-run setup and choose your AI provider
4. Open Settings to fine-tune memory, theme, TTS, and provider defaults

Environment Variables

• GEMINI_API_KEY - Google Gemini
• OPENAI_API_KEY - OpenAI
• ANTHROPIC_API_KEY - Anthropic Claude
• OPENROUTER_API_KEY - OpenRouter
• KILO_API_KEY - Kilo AI
• TAVILY_API_KEY - Tavily Search API (for Web Skills)
• OLLAMA_HOST - Ollama URL (default: http://localhost:11434)

You do not need every variable. Use only the providers you care about. Ollama does not require an API key, which makes it the easiest route for privacy-focused local usage.

---

3. Quick Start

If you want the shortest path from install to useful interaction, start here. This section is designed for testing the app quickly before you fully customize it.

Development Mode

npm ci
cp .env.example .env
npm run start

First Commands To Try

• Hello Clippy to confirm the model is responding
• /sysinfo to test desktop tools
• /ps 10 to list active processes
• /clipboard to confirm system integration
• /search latest AI news if Tavily is configured

Once these basics work, move into settings and configure TTS, memory, prompts, identity, and any notification features you want enabled.

---

4. API / IPC

Clippy is split between a Renderer process for the UI and a Main process for Electron-native capabilities. IPC bridges those two layers so the interface can request tools, state updates, chat streaming, and system actions.

Desktop Commands

Available via / in chat:

• /run <cmd> - Run PowerShell command (Safe mode prevents destructive commands)
• /ls [path] or /list - List directory contents
• /read <file> or /cat - Read file content
• /search <query> or /find - Search files locally
• /sysinfo - System information
• /ps [limit] - List active processes
• /screenshot [name] - Take desktop screenshot
• /clipboard - Read clipboard

Web Commands

• /search <query> or /google - Web search via Tavily
• /fetch <url> or /curl or /wget - Scrape webpage content

Message Parsing Directives

Clippy's AI can output special syntax to trigger internal actions invisibly. These directives let the model update memory, adjust mood, or call tools without exposing raw implementation details to the user.

• [MEMORY_UPDATE:...] - Save to local Vector Store
• [TOOL_CALL:...] - Execute Modular Skills/Plugins
• [STATS_UPDATE:...] - Modify Bond and Happiness variables
• [Wave], [Think] - Play spritesheet animation

Permissions System

Clippy features a granular permissions system to control what actions are allowed. Configure in Settings > Permissions.

Permission Levels

• None - No commands allowed
• Read Only - Only read operations
• Limited - Read + limited write (default)
• Full - All operations with confirmation
• Unrestricted - All operations without confirmation

Permission Categories

• File Reading (Low risk)
• File Writing (Medium risk)
• File Deletion (High risk)
• Process Management (High risk)
• System Commands (Low risk)
• Network Operations (Medium risk)
• Registry Operations (Critical risk)
• Application Control (Low risk)
• Screenshots (Low risk)
• Clipboard (Low risk)

This architecture makes Clippy feel more interactive than a plain chat app: it can respond, remember, act, and adapt, all within the same conversation loop.

---

5. FAQ / Troubleshooting

App doesn't start: Check Node version and run npm ci then npm run start.

API key not working: Make sure your API key is correct. Check the .env file or Settings in the app.

Ollama not connecting: Ensure Ollama is running with ollama serve and that your host matches the app setting.

TTS not speaking: Verify your voice settings in the app and test with a shorter response first.

Desktop commands are blocked: Safe mode intentionally blocks destructive actions. Switch modes carefully in Advanced settings.

Where is user data stored? Windows: %APPDATA%\Clippy\, macOS: ~/Library/Application Support/Clippy/

Notifications not sending: Double-check your provider keys, toggles, and any allowlist or chat ID configuration if you enabled notification integrations.

---

6. Version History

v0.5.1

• Auto cover image generation for GitHub Releases
• Improved provider and streaming system
• Streaming support for desktop and web commands
• Progress messages during command execution
• Skills/Plugin system with registry and status checking
• In-page documentation windows (iframe) instead of popups
• TTS/Voice improvements with voice-to-text confirmation
• IPC/Preload updates for Ollama and Skill status checking
• Kilo AI provider support

v0.4.4

• Modular Skills/Plugins system
• Multi-language UI support (English and Thai localization)
• Desktop AI commands (/run, /screenshot, /ps, /sysinfo)
• Web Search & Fetch via Tavily API
• Ollama support for 100% offline Local Models
• Multiple Cloud AI providers (Gemini, OpenAI, Anthropic, OpenRouter)
• Emotion/Style-aware responses with internal Mood Engine
• Local memory using persistent Vector Store
• Responsive Edge-TTS voice generation
• Windows 98 themed UI with translucent features

Future iterations can continue expanding integrations, skills, documentation, model routing, local automation, and quality-of-life improvements around onboarding and memory controls.