Skip to content

A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.

Package and release the Linux build

Salomão Davy06c57eadc0cb
diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
new file mode 100644
index 00000000..c12d6298
--- /dev/null
+++ b/.github/workflows/linux.yml
@@ -0,0 +1,139 @@
+name: Linux
+
+# Builds the Linux app (AppImage, .deb, .rpm) from the same Tauri project as
+# Windows and publishes the packages. Triggered by tags like `linux-v0.1.0`;
+# the macOS and Windows workflows are untouched.
+
+on:
+ push:
+ tags:
+ - 'linux-v*'
+ workflow_dispatch:
+
+permissions:
+ contents: write
+
+env:
+ PUBLISH: 'true'
+
+jobs:
+ build:
+ # The oldest supported Ubuntu: an AppImage only runs on systems whose glibc
+ # is at least as new as the one it was built against.
+ runs-on: ubuntu-22.04
+ defaults:
+ run:
+ working-directory: windows
+
+ steps:
+ - uses: actions/checkout@v4
+
+ # webkit2gtk, gtk-layer-shell and appindicator to build against; patchelf
+ # and the GStreamer plugins for the AppImage, which carries its own
+ # GStreamer so the sounds play (WAV needs wavparse, in -good).
+ - name: Install system libraries
+ working-directory: .
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y \
+ 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
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: npm
+ cache-dependency-path: windows/package-lock.json
+
+ - name: Cache cargo
+ uses: actions/cache@v4
+ with:
+ path: |
+ ~/.cargo/registry
+ ~/.cargo/git
+ windows/target
+ key: linux-cargo-${{ hashFiles('windows/Cargo.lock') }}
+ restore-keys: linux-cargo-
+
+ - name: Install dependencies
+ run: npm ci
+
+ # Same check as the Windows workflow: three files carry the version.
+ - name: Check the tag and every version agree
+ if: startsWith(github.ref, 'refs/tags/linux-v')
+ run: |
+ tag="${GITHUB_REF_NAME#linux-v}"
+ conf=$(node -p "require('./src-tauri/tauri.conf.json').version")
+ pkg=$(node -p "require('./package.json').version")
+ cargo=$(sed -nE 's/^version\s*=\s*"(.+)"/\1/p' Cargo.toml | head -1)
+ echo "tag=$tag tauri.conf=$conf package.json=$pkg Cargo.toml=$cargo"
+ bad=""
+ [ "$tag" = "$conf" ] || bad="$bad tauri.conf.json says $conf;"
+ [ "$tag" = "$pkg" ] || bad="$bad package.json says $pkg;"
+ [ "$tag" = "$cargo" ] || bad="$bad Cargo.toml says $cargo;"
+ if [ -n "$bad" ]; then echo "tag says $tag but$bad"; exit 1; fi
+
+ - name: Test
+ run: cargo test --workspace
+
+ # linuxdeploy is itself an AppImage; runners have no FUSE, so it unpacks
+ # itself instead of mounting.
+ - name: Build and pack
+ id: pack
+ env:
+ APPIMAGE_EXTRACT_AND_RUN: '1'
+ run: |
+ npm run pack
+ echo "version=$(node -p "require('./src-tauri/tauri.conf.json').version")" >> "$GITHUB_OUTPUT"
+ ls -la release
+
+ - uses: actions/upload-artifact@v4
+ with:
+ name: Coucou-Linux
+ path: |
+ windows/release/Coucou-Linux-${{ steps.pack.outputs.version }}-*
+
+ - name: Publish the release
+ if: env.PUBLISH == 'true' && startsWith(github.ref, 'refs/tags/linux-v')
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ v="${{ steps.pack.outputs.version }}"
+ notes="Coucou for Linux $v — Mochi at the top of your screen.
+
+ - **AppImage** (any distribution): \`chmod +x Coucou-Linux-$v-x86_64.AppImage\` and run it.
+ - **Debian / Ubuntu**: \`sudo apt install ./Coucou-Linux-$v-amd64.deb\`
+ - **Fedora / openSUSE**: \`sudo dnf install ./Coucou-Linux-$v-x86_64.rpm\`
+
+ The island sits on the top edge on compositors with layer-shell (COSMIC,
+ KDE Plasma, Hyprland, Sway…). On GNOME it opens as a regular window."
+ # --latest=false: the macOS \`v*\` releases own the Latest slot, which
+ # the site's Download for Mac button points at.
+ gh release create "$GITHUB_REF_NAME" \
+ "release/Coucou-Linux-$v-x86_64.AppImage" \
+ "release/Coucou-Linux-$v-amd64.deb" \
+ "release/Coucou-Linux-$v-x86_64.rpm" \
+ --title "Coucou for Linux $v" \
+ --notes "$notes" \
+ --latest=false
+
+ - name: Update the rolling linux-latest release
+ if: env.PUBLISH == 'true' && startsWith(github.ref, 'refs/tags/linux-v')
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ v="${{ steps.pack.outputs.version }}"
+ if gh release view linux-latest >/dev/null 2>&1; then
+ # The tag has to follow the release, as for windows-latest.
+ git tag -f linux-latest "$GITHUB_SHA"
+ git push -f origin linux-latest
+ gh release edit linux-latest --title "Coucou for Linux (latest)" --notes "Always the newest Linux build — currently $v."
+ gh release upload linux-latest "release/Coucou-Linux-x86_64.AppImage" --clobber
+ else
+ gh release create linux-latest \
+ "release/Coucou-Linux-x86_64.AppImage" \
+ --title "Coucou for Linux (latest)" \
+ --notes "Always the newest Linux build — currently $v." \
+ --latest=false
+ fi
diff --git a/README.md b/README.md
index cf83dd40..d5d9979e 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,13 @@
# Coucou
-**A tiny friend that lives in your Mac's notch — or at the top of your screen on Windows — and keeps an eye on your AI coding agent sessions.**
+**A tiny friend that lives in your Mac's notch — or at the top of your screen on Windows and Linux — and keeps an eye on your AI coding agent sessions.**
Approve permissions, watch your agents work, drop a file, chat with Claude — all without leaving what you're doing.
![macOS 15+](https://img.shields.io/badge/macOS-15%2B-black?logo=apple)
![Windows 10/11](https://img.shields.io/badge/Windows-10%2F11-0078D4?logo=windows&logoColor=white)
+![Linux](https://img.shields.io/badge/Linux-AppImage%20%7C%20deb%20%7C%20rpm-FCC624?logo=linux&logoColor=black)
![Swift 6](https://img.shields.io/badge/Swift-6-F05138?logo=swift&logoColor=white)
![SwiftUI](https://img.shields.io/badge/SwiftUI-native-0A84FF)
![Tauri 2](https://img.shields.io/badge/Tauri-2-FFC131?logo=tauri&logoColor=black)
@@ -40,9 +41,9 @@ Meet **Mochi**: a soft little squircle with big eyes that pops out of your notch
- 🪟 **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.
- 🎭 **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).
+- 🫥 **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 or Windows Credential Manager. The app only talks to the services you plug in.
+- 🔒 **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.
<table>
<tr>
@@ -74,6 +75,18 @@ There is no notch on a PC, so the island slides out of the top edge of the scree
instead of hiding inside one. See [`windows/README.md`](windows/README.md) for the
rest of the differences.
+### Linux
+
+Grab a package from [Releases](https://github.com/Louis-CFM/coucou/releases):
+
+- **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`
+
+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`](windows/README.md#linux).
+
### Build from source
**macOS** — requirements: macOS 15+, Xcode 16+, [XcodeGen](https://github.com/yonaskolb/XcodeGen).
@@ -95,20 +108,32 @@ npm install
npm run pack # installer lands in windows/release/
```
+**Linux** — requirements: [Rust](https://rustup.rs), Node 20+, and the WebKitGTK,
+gtk-layer-shell and appindicator development packages (Debian/Ubuntu names below).
+
+```bash
+sudo apt install libwebkit2gtk-4.1-dev libgtk-layer-shell-dev \
+ libayatana-appindicator3-dev librsvg2-dev libssl-dev patchelf
+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) → **Settings…**
+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 |
+| **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, all optional |
+| 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.**
@@ -144,6 +169,13 @@ The macOS app is native Swift 6 / SwiftUI / AppKit with **zero third-party depen
- 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`](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](CONTRIBUTING.md).
diff --git a/windows/README.md b/windows/README.md
index de57792c..a380db04 100644
--- a/windows/README.md
+++ b/windows/README.md
@@ -146,3 +146,36 @@ problems. It stays on your machine.
attach it as context, and jumping to a specific terminal window — "Open
terminal" opens the working folder in VS Code when `code` is on your `PATH`.
- Cal.com shows the next bookings as a list rather than the Mac's calendar.
+
+## Linux
+
+The same app builds for Linux: everything that differs lives in
+`src-tauri/src/platform/`, and the relay's transport in `hook/src/unix.rs`.
+
+```bash
+sudo apt install libwebkit2gtk-4.1-dev libgtk-layer-shell-dev \
+ libayatana-appindicator3-dev librsvg2-dev libssl-dev patchelf
+npm install
+npm run tauri dev # live-reloading development build
+npm run pack # AppImage, .deb and .rpm in windows/release/
+```
+
+What changes on Linux:
+
+- **The island** is a gtk-layer-shell overlay anchored to the top edge, over any
+ top panel, on compositors that support it: COSMIC, KDE Plasma, Hyprland, Sway
+ and other wlroots compositors. GNOME has no layer-shell, so there the island
+ is a regular window. `COUCOU_LAYER_SHELL=0` forces that mode anywhere.
+- **Click-through** is the window's input region, kept equal to the island
+ shape, so the compositor sends every other click to what is underneath.
+- **Mochi's eyes** follow the pointer only while it is over the island: Wayland
+ gives no app the cursor position anywhere else.
+- **Claude Code hooks** go through `~/.local/share/coucou/bin/coucou-hook` and a
+ Unix socket at `$XDG_RUNTIME_DIR/coucou.sock`. Both ends check that the other
+ runs as the same user.
+- **Keys** live in the Secret Service (GNOME Keyring, KWallet).
+- **Files**: preferences in `~/.config/coucou/`, the log at
+ `~/.local/share/coucou/coucou.log`.
+- What the Windows build leaves out, this one does too: sending a file by
+ email, dragging Mochi onto a window, and jumping to a specific terminal
+ window — "Open terminal" opens the folder in VS Code.
diff --git a/windows/scripts/pack.mjs b/windows/scripts/pack.mjs
index 743f1e10..f3cb00ac 100644
--- a/windows/scripts/pack.mjs
+++ b/windows/scripts/pack.mjs
@@ -1,41 +1,79 @@
-// Copies the installer Tauri buries in target/release/bundle/nsis/ into
-// windows/release/, with the name it ships under. Used by `npm run pack` and by
-// the release workflow, so both produce exactly the same file names.
+// Copies the packages Tauri buries in target/release/bundle/ into
+// windows/release/, with the names they ship under. Used by `npm run pack` and
+// by the release workflows, so both produce exactly the same file names.
import { readFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const bundleDir = join(root, "target", "release", "bundle", "nsis");
+const bundleRoot = join(root, "target", "release", "bundle");
const outDir = join(root, "release");
const { version } = JSON.parse(readFileSync(join(root, "src-tauri", "tauri.conf.json"), "utf8"));
-let installers = [];
-try {
- installers = readdirSync(bundleDir).filter((f) => f.endsWith("-setup.exe"));
-} catch {
- console.error(`No installer in ${bundleDir} — run \`npm run tauri build\` first.`);
- process.exit(1);
-}
-if (installers.length === 0) {
- console.error(`No installer in ${bundleDir} — run \`npm run tauri build\` first.`);
+// What each platform ships: where Tauri puts it, how to recognise it, and the
+// names it is published under (the rolling name, when there is one, always
+// points at the latest release).
+const arch = process.arch === "arm64" ? "aarch64" : "x86_64";
+const debArch = process.arch === "arm64" ? "arm64" : "amd64";
+const PACKAGES = {
+ win32: [
+ {
+ dir: "nsis",
+ suffix: "-setup.exe",
+ names: [`Coucou-Windows-${version}-setup.exe`, "Coucou-Windows-setup.exe"],
+ },
+ ],
+ linux: [
+ {
+ dir: "appimage",
+ suffix: ".AppImage",
+ names: [`Coucou-Linux-${version}-${arch}.AppImage`, `Coucou-Linux-${arch}.AppImage`],
+ },
+ { dir: "deb", suffix: ".deb", names: [`Coucou-Linux-${version}-${debArch}.deb`] },
+ { dir: "rpm", suffix: ".rpm", names: [`Coucou-Linux-${version}-${arch}.rpm`] },
+ ],
+};
+
+const packages = PACKAGES[process.platform];
+if (!packages) {
+ console.error(`Nothing to pack on ${process.platform}.`);
process.exit(1);
}
-// Newest wins, in case an older build is still lying around.
-const built = installers
- .map((f) => join(bundleDir, f))
- .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+/** The newest file in `dir` ending with `suffix`, in case an older build is still lying around. */
+function newest(dir, suffix) {
+ let files = [];
+ try {
+ files = readdirSync(dir).filter((f) => f.endsWith(suffix));
+ } catch {
+ return null;
+ }
+ if (files.length === 0) return null;
+ return files
+ .map((f) => join(dir, f))
+ .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+}
mkdirSync(outDir, { recursive: true });
-const versioned = join(outDir, `Coucou-Windows-${version}-setup.exe`);
-const rolling = join(outDir, "Coucou-Windows-setup.exe");
-copyFileSync(built, versioned);
-copyFileSync(built, rolling);
-
-const mb = (statSync(versioned).size / 1024 / 1024).toFixed(2);
-console.log(`\n Installer ready — ${mb} MB\n`);
-console.log(` ${versioned}`);
-console.log(` ${rolling}\n`);
+const written = [];
+for (const { dir, suffix, names } of packages) {
+ const built = newest(join(bundleRoot, dir), suffix);
+ if (!built) {
+ console.error(`No *${suffix} in ${join(bundleRoot, dir)} — run \`npm run tauri build\` first.`);
+ process.exit(1);
+ }
+ for (const name of names) {
+ const dest = join(outDir, name);
+ copyFileSync(built, dest);
+ written.push(dest);
+ }
+}
+
+console.log("\n Packages ready\n");
+for (const f of written) {
+ const mb = (statSync(f).size / 1024 / 1024).toFixed(2);
+ console.log(` ${f} (${mb} MB)`);
+}
+console.log();
diff --git a/windows/src-tauri/tauri.linux.conf.json b/windows/src-tauri/tauri.linux.conf.json
index c2c1c226..8afd0ba7 100644
--- a/windows/src-tauri/tauri.linux.conf.json
+++ b/windows/src-tauri/tauri.linux.conf.json
@@ -1,9 +1,29 @@
{
"$schema": "https://schema.tauri.app/config/2",
"bundle": {
+ "targets": [
+ "appimage",
+ "deb",
+ "rpm"
+ ],
"resources": {
"../target/release/coucou-hook.exe": null,
"../target/release/coucou-hook": "coucou-hook"
+ },
+ "linux": {
+ "appimage": {
+ "bundleMediaFramework": true
+ },
+ "deb": {
+ "depends": [
+ "libgtk-layer-shell0"
+ ]
+ },
+ "rpm": {
+ "depends": [
+ "gtk-layer-shell"
+ ]
+ }
}
},
"app": {