OpenCode Clippy

A nostalgic Microsoft Office Clippy desktop widget that hooks into OpenCode and reacts to your coding events with classic animations, proactive tips, and Lottie effects.

"It looks like you're writing some code. Can I help?"

Features

• 43 Clippy animations from the original sprite sheet — Greeting, Thinking, Writing, Searching, Alert, Congratulate, and more
• Proactive tips in classic "It looks like you're trying to..." style — pattern-matches your coding activity and offers contextual suggestions
• Lottie effects — sparkles on success, confetti on congratulate, alert pulses, thinking dots, wave lines
• Classic Windows 98 tooltip — authentic #FFFFE1 yellow speech bubble with sharp corners, #808080 drop shadow, Tahoma font, and triangular tail
• Task completion detection — Clippy celebrates when OpenCode finishes a task (session.idle)
• 20 idle animations — Clippy looks around, waves, gets artsy, checks things, and fidgets while you think
• Cross-platform — macOS, Windows, and Linux (Unix sockets on macOS/Linux, named pipes on Windows)
• System tray — tray icon with show/hide toggle, runs in background
• Single instance — only one Clippy widget runs at a time
• Resilient IPC — heartbeat, auto-reconnect, launch-order independent (start either side first)

How It Works

The project has two parts:

1. Desktop Widget — an Electron app that renders Clippy with sprite animations, speech bubbles, and Lottie effects
2. OpenCode Plugin — a gateway that listens to OpenCode events and forwards them to the widget via IPC (Unix socket / named pipe)

They communicate over a local socket — no network, no ports, no firewall issues. Start them in any order; they auto-reconnect.

                    Unix Socket / Named Pipe
                    ~/.opencode-clippy/clippy.sock
                              
OpenCode ──► Plugin (clippy.ts) ──────────────► Electron Widget
             events + tips engine               sprite canvas + speech bubble + lottie

Installation

Plugin (OpenCode integration)

Add to your ~/.config/opencode/opencode.json:

{
  "plugin": [
    "opencode-clippy"
  ]
}

That's it — the plugin is installed from npm. Restart OpenCode to activate.

Desktop Widget

Download the latest release for your platform from GitHub Releases:

| Platform | Architecture | Download | |---|---|---| | macOS | Apple Silicon (arm64) | .dmg | | Windows | x86-64 | .exe | | Linux | arm64 | .AppImage / .deb |

Or build from source:

git clone https://github.com/huangcheng/opencode-clippy.git
cd opencode-clippy
pnpm install
pnpm build
pnpm start

Usage

1. Start the Clippy desktop widget (from the downloaded app or pnpm start)
2. Start OpenCode in any project directory
3. Clippy reacts to your coding — they auto-connect in any launch order

Development

# Watch mode (rebuild on changes)
pnpm dev

# Run the widget standalone
pnpm start

# Run the test harness (visual animation tester)
pnpm --filter @opencode-clippy/desktop exec vite dev
# then open http://localhost:5173/test-harness.html

# Package for distribution
pnpm package          # current platform
pnpm package:mac      # macOS .dmg
pnpm package:win      # Windows .exe
pnpm package:linux    # Linux .AppImage/.deb

Event Mappings

| OpenCode Event | Clippy Animation | Speech Bubble | |---|---|---| | Task complete (session.idle) | Congratulate | "All done! Ready for more." | | AI responding (message.updated) | Thinking | "Working on it..." | | AI streaming (message.part.updated) | Thinking | "Thinking..." | | Code changed (session.diff) | Writing | "Changes detected!" | | Reading files (tool.execute.before read) | Searching | "Reading files..." | | Editing files (tool.execute.before edit) | Writing | "Making changes..." | | Running commands (tool.execute.before bash) | GetTechy | "Running command..." | | Tool success (tool.execute.after) | Congratulate | "Done!" | | Tool error (tool.execute.after error) | Alert | "Oops, something went wrong!" | | Permission needed (permission.asked) | GetAttention | "I need your permission!" | | Permission granted (permission.replied) | Congratulate | "Thanks!" | | Permission denied (permission.replied denied) | LookDown | "Okay, I won't do that." | | Session start (session.created) | Greeting | "Hey! Let's write some code!" | | Session end (session.deleted) | GoodBye | "See you next time!" | | File saved (file.edited) | Save | "File saved!" |

Proactive Tips

Clippy watches your coding patterns and offers help, just like the original:

| Pattern | Clippy Says | |---|---| | 3+ errors in 60 seconds | "It looks like you're running into errors!" | | Reading test files | "It looks like you're working on tests!" | | Editing config files (.env, .json, .yaml) | "It looks like you're editing configuration!" | | First edit in a session | "It looks like you're about to make your first change!" |

Tips have a 5-minute cooldown per pattern to avoid nagging.

Architecture

opencode-clippy/
├── packages/
│   ├── plugin/
│   │   └── src/clippy.ts         # OpenCode plugin — event gateway
│   ├── desktop/
│   │   ├── src/widget/
│   │   │   ├── main/main.ts      # Electron main — window, tray, IPC server
│   │   │   ├── preload/preload.ts# Context bridge for IPC → renderer
│   │   │   └── renderer/
│   │   │       ├── index.html     # Widget layout (transparent, frameless)
│   │   │       ├── renderer.ts    # Main renderer — wires everything together
│   │   │       ├── animation-engine.ts # Canvas sprite renderer with priority queue
│   │   │       ├── event-mapping.ts    # OpenCode event → animation/tip mapping
│   │   │       ├── speech-bubble.ts    # Windows 98 tooltip (classic yellow)
│   │   │       └── lottie-effects.ts   # Lottie overlay (sparkles, confetti, etc.)
│   │   ├── assets/               # Sprite sheet, lottie effects, tray icon
│   │   └── vite.config.ts
│   └── shared/
│       └── src/tips-engine.ts    # Proactive tips pattern matching
└── pnpm-workspace.yaml

IPC Protocol

Plugin → Widget communication uses newline-delimited JSON over Unix socket (~/.opencode-clippy/clippy.sock) or named pipe (\\.\pipe\opencode-clippy on Windows).

Event message:

{"type": "event", "event": "message.part.updated"}

Tip message:

{"type": "tip", "title": "It looks like you're running into errors!", "body": "Would you like me to suggest checking the error logs?", "animation": "GetAttention"}

Heartbeat:

{"type": "ping"}

Credits

• Original Clippy character designed by Kevan Atteberry for Microsoft Office 97
• felixrieseberg/clippy — Clippy sprite sheet assets (map.png, animations.json) and animation frame data
• panta82/opencode-notificator — Reference implementation for OpenCode plugin event handling (session.idle detection, session ID tracking)
• OpenCode — AI coding assistant whose plugin system makes this possible (docs)
• Lottie animations rendered with lottie-web by Airbnb
• Desktop widget built with Electron
• Built with the assistance of Claude Code by Anthropic

License

MIT