Louis-CFM/coucou

---

Why

Some studios showed off gorgeous notch companions… and never let anyone use them. Coucou is the open version. Every line of code, every animation, every sound — free to use, read, fork and remix.

Meet Mochi: a soft little squircle with big eyes that pops out of your notch, waves hello, follows your cursor with its eyes, gets annoyed when you poke it (and dizzy if you insist), and tells you the moment Claude Code needs you.

Features

• 🤖 Claude Code, Cursor, Codex, Gemini CLI, Antigravity and other agents, live — see every session in your notch: what it reads, edits and runs, step by step. Tag a hook payload with coucou_agent to give any agent its own pill (see docs/AGENTS.md). Finished? Mochi does a happy little jump.
• ✅ Approve from the notch — Claude Code and Codex permission requests show up with Allow / Deny (and Always for Claude Code), in VS Code, Cursor's terminal, or Codex. One click, back to work.
• 🧑‍💻 Jump to the right terminal — open the exact terminal window of a session (macOS).
• 💬 Chat with Claude, or with Gemini and OpenAI models using your own keys (Gemini and OpenAI: macOS) — click the model name above the chat box to switch provider and pick a model; the list comes from each API account.
• 📋 Declare the tools you use — open Settings → Active pills and pick your main workspace tool (VS Code, Cursor, Codex or Antigravity), then toggle up to 4 more: Gemini CLI, Anthropic, Google AI, OpenAI and service integrations (macOS).
• 📎 Drop a file on the notch — Mochi turns into a box and swallows it, then ask a question about it or send it by email (email: macOS, Mail.app).
• 🪟 Drag Mochi onto any window — attach that window as context for Claude (macOS).
• 🔌 Integrations — Stripe payments, n8n workflows, GitHub, Vercel deployments, Resend emails, Notion, Cal.com. Each one gets its own little colored Mochi.
• 🎵 Apple Music pill (macOS, GitHub build) — add the Apple Music pill in Settings → Active pills to see what's playing and control playback from the notch; Mochi dances while it plays.
• 🎭 A real character — idle breathing, blinks, eyes on a sphere that follow your mouse, emotes, 28 handcrafted sounds, a greeting on launch.
• 🫥 Invisible when idle — hides away when nothing is running, peeks out when you hover the notch (the top edge of the screen on Windows and Linux).
• 🖥️ Any Mac, notch or not — on an iMac, a Mac mini, or a MacBook with its lid closed on an external display, Mochi sits in a small bar at the top of the screen.
• 🔒 Private by design — no telemetry, no account. Keys live in your macOS Keychain, Windows Credential Manager or Linux Secret Service (GNOME Keyring, KWallet). The app only talks to the services you plug in.

Install

Download for macOS

1. Grab the latest Coucou.zip from Releases. 2. Unzip and move Coucou.app to /Applications. 3. Launch it, and click Open when macOS asks you to confirm. Updating from 0.1.0? macOS may ask you, once for each key you saved, to let Coucou use it: enter your Mac password and click Always Allow.

Windows

The Windows installer is temporarily unavailable. Microsoft Defender wrongly flags the unsigned installer as malware; a false-positive report is under review at Microsoft and the installer will come back once it is cleared and signed. Until then you can build it from source.

There is no notch on a PC, so the island slides out of the top edge of the screen instead of hiding inside one. See windows/README.md for the rest of the differences.

Linux

The first Linux build is out as a beta: download it from Coucou for Linux 0.1.1 (beta), x86_64 only for now. Later versions will be in Releases under linux-v* tags.

• AppImage (any distribution): chmod +x Coucou-Linux-*.AppImage, then run it.
• Debian / Ubuntu: sudo apt install ./Coucou-Linux-*.deb
• Fedora / openSUSE: sudo dnf install ./Coucou-Linux-*.rpm

Check a download with sha256sum -c SHA256SUMS --ignore-missing. Gemini CLI, Antigravity and the Google AI and OpenAI chat are macOS only for now.

The island sits on the top edge on compositors with layer-shell — COSMIC, KDE Plasma, Hyprland, Sway and other wlroots compositors. GNOME has no layer-shell, so there it opens as a regular window. See windows/README.md.

Build from source

macOS — requirements: macOS 15+, Xcode 16+, XcodeGen.

brew install xcodegen
git clone https://github.com/Louis-CFM/coucou.git
cd coucou/NotchBuddy
xcodegen
open NotchBuddy.xcodeproj   # then ⌘R

Windows — requirements: Rust, Node 20+, MSVC build tools.

git clone https://github.com/Louis-CFM/coucou.git
cd coucou/windows
npm install
npm run pack                # installer lands in windows/release/

Linux — requirements: Rust, Node 20+, and the WebKitGTK, gtk-layer-shell and appindicator development packages (Debian/Ubuntu names below).

sudo apt install build-essential pkg-config \
  libwebkit2gtk-4.1-dev libgtk-layer-shell-dev libayatana-appindicator3-dev \
  librsvg2-dev libssl-dev libdbus-1-dev patchelf \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good
git clone https://github.com/Louis-CFM/coucou.git
cd coucou/windows
npm install
npm run pack                # AppImage, .deb and .rpm land in windows/release/

Setup

Click the Coucou icon in the menu bar (macOS) or in the system tray (Windows, Linux) → Settings…

| What | Why | Where the key goes | |---|---|---| | Claude Code hooks | live sessions and approvals | Install hooks — Coucou backs up ~/.claude/settings.json, merges its hooks and shows you the diff before writing anything | | Gemini CLI hooks (macOS) | Gemini CLI sessions in the island | Install hooks in Settings → Gemini CLI — backs up ~/.gemini/settings.json | | Antigravity (agy) hooks (macOS) | agy sessions in the island | Install hooks in Settings → Antigravity — backs up ~/.gemini/config/hooks.json | | Anthropic API key | chat and questions about files | Settings → Anthropic API · Keychain / Windows Credential Manager / Secret Service | | Google AI API key (macOS) | chat with Google AI (Gemini) | Settings → Chat — other providers · Keychain | | OpenAI API key (macOS) | chat with OpenAI | Settings → Chat — other providers · Keychain | | Active pills (macOS) | choose which tools and agents appear in the island | Settings → Active pills | | Stripe, n8n, GitHub, Vercel, Resend, Notion, Cal.com | the service pills | Keychain / Windows Credential Manager / Secret Service, all optional |

If Coucou isn't running, the hook exits immediately: Claude Code is never blocked.

Things to try

| Do this | Mochi does that | |---|---| | Hover the notch (top edge on Windows and Linux) | peeks out and says hi 👋 | | Click it | opens | | Hover Mochi | blinks, eyes grow | | Click Mochi | squish + annoyed | | Click 3 times fast | 😵‍💫 dizzy for a few seconds | | Drag a file onto the island | turns into a box and swallows it | | Drag Mochi onto a window (macOS) | attaches it as context | | Click the model name above the chat box (macOS) | switch AI provider or model |

How it works

macOS

• Island: a borderless NSPanel hugging the notch, driven by a small state machine (hidden → petit → home).
• Character: drawn in SwiftUI Canvas + TimelineView at 60 fps — squircle body, eyes projected on a sphere, spring animations. No Rive, no Lottie, no images.
• Claude Code: a tiny nb-hook script receives hook events and forwards them over a Unix socket to the app. For approvals it waits for your click, then answers the hook.
• Integrations: lightweight pollers, paused when nothing is watching.
• Declared pills: PillCatalog.swift is the single source of truth — every pill (coding tools, agents, AI providers, services) is declared there with its ID, color and category.
• Sounds: 28 short WAVs played through preloaded AVAudioPlayers.

The macOS app is native Swift 6 / SwiftUI / AppKit with zero third-party dependencies.

Windows

• A Tauri 2 app (Rust + TypeScript): the island is a transparent, always-on-top window that never steals focus, Mochi is drawn in Canvas 2D with the same shapes, timings and sounds as on the Mac.
• Claude Code hooks go through a tiny coucou-hook.exe and a named pipe; keys live in Windows Credential Manager.
• Details and differences in windows/README.md.

Linux

• The same Tauri app as Windows. On Wayland the island is a gtk-layer-shell

overlay anchored to the top edge, and click-through is its input region.

• Claude Code hooks go through the same coucou-hook, over a Unix socket in

$XDG_RUNTIME_DIR; keys live in the Secret Service.

Contributing

Issues and PRs are very welcome — new integrations, new emotes, new sounds, bug fixes. See CONTRIBUTING.md.

Credits

Built by Louis Raillé with Claude Code. Inspired by the notch-companion concepts shared by design studios — this project is independent and not affiliated with any of them.

License

• Code: MIT — use it, fork it, learn from it, just keep the copyright notice.
• Name, Mochi character, icon, sounds and media: © Louis Raillé, all rights reserved — see LICENSE-ASSETS.md. Shipping your own fork? Give it your own name and character.