copilot-key

English · Deutsch

Make the Copilot key on the Minisforum AI X1 Pro actually useful — on Linux, with a radial menu, a window toggle and a sound set of its own.

• Press once → bring the primary action's window to the front, or minimise it if it is already focused. If nothing is running, the menu opens instead.
• Press twice quickly → always open the menu.
• Press again while the menu is open → close it.
• Every state change has its own audio cue.
• The menu is set up without a configuration file: pick the apps from a list, in a window of its own or right inside the wheel.
• Skins decide what the wheel looks like — three ship with it, more are a small text file away.

The menu is a fullscreen overlay: it dims the desktop and unrolls in a circle from the centre. Drive it with 1–9, the arrow keys, the scroll wheel or the mouse; Esc or a click outside dismisses it. The icons are plain Cairo vector drawings — no icon theme, no third-party artwork.

Everything the program says follows your locale: German on a German system, English everywhere else (see Language).

Built for Linux Mint 22.3 (Cinnamon, X11, Ubuntu 24.04 base). The menu is verified against GTK 3; the key chain should be confirmed once on the target machine with detect-key.sh.

---

Installation

git clone https://github.com/SoulInfernoDE/copilot-key-linux
cd copilot-key-linux
./install.sh

Run it as your normal user — the script calls sudo itself where root is actually needed. It will:

1. Check dependencies (wmctrl, xdotool, python3-gi, python3-gi-cairo, pulseaudio-utils)
2. Install keyd — from the package sources, otherwise built from source into ~/Downloads/keyd with prefix /usr/local
3. Install the programs to /usr/local/bin and the sounds and skins to /usr/local/share/copilot-key
4. Copy config/keyd-copilot.conf to /etc/keyd/copilot.conf and restart keyd
5. Register the Cinnamon shortcut Ctrl+Alt+Shift+F12 → copilot-key

One machine, several people

The installation is shared, the menu is not. Every user gets their own ~/.config/copilot-key/config.toml — created from the defaults the first time they press the key — and their own shortcut, registered by a login hook in /etc/xdg/autostart. Nobody has to run an installer twice, and nobody edits anybody else's menu.

Prefer to keep it inside your own home? ./install.sh --user puts everything under ~/.local exactly as before.

To remove it: ./uninstall.sh (it clears both, and leaves other users' configurations alone).

After pulling an update, simply run ./install.sh again — your existing configuration is left untouched.

---

How the key gets through

The Copilot key does not send a key code of its own. It sends the chord LeftMeta + LeftShift + F23, which most desktop environments refuse to accept as a shortcut — hence the two-stage chain:

Copilot key  →  keyd (evdev, ahead of X11/Wayland)  →  Ctrl+Alt+Shift+F12  →  desktop shortcut  →  copilot-key

keyd works below the window system, so the same setup applies to X11 and Wayland alike.

If your key sends something else,

./detect-key.sh

shows what it really emits (via keyd monitor, falling back to evtest, then xev). The common alternatives are already present as commented-out lines in config/keyd-copilot.conf — swap the line, then sudo keyd reload.

---

Configuration

The menu comes with an editor, so nothing has to be typed into a file:

Open it from the menu itself (the gear entry), from your start menu ("Copilot key menu"), or from a terminal:

copilot-key configure

Entries are added, reordered and removed on the left. Choose an app… lists every application installed on the machine and fills in name, description, command and window in one go — that is the whole job for most entries. The wheel on the right shows what the menu will look like, and Test the menu opens the real one with the current state, saved or not. Everything under Advanced is optional.

Under Behaviour sit the sounds, the volume, the double-press window, the menu heading, the menu style, whether the buttons carry the applications' own icons instead of the drawn ones, and whether the editor window follows your desktop's light or dark theme.

Or without leaving the wheel

The sparkle in the middle of the menu is a button. It reveals two small tools: the gear opens the editor window, the pencil turns the wheel itself into the editor.

• Drag a button around the wheel to reorder it; the others move out of the way while you do.
• Click a button and a search bar slides in above the wheel. Type, pick an application with ↑/↓ and Enter, and it lands on the button you clicked — which glows until it has one.
• + — which slides into the centre while you edit — adds another button, ✕ on a button removes it.
• The search also takes a command: type waydroid session stop and it offers to run it in the background or in a terminal, with the program's own icon if it has one. Shell syntax works as it does in a terminal (~, &&, pipes). An address such as github.com/… becomes "open in the browser". A command is only offered when its program exists — otherwise the list says which one is missing.
• The picture badge on a button changes its symbol: the same search, now offering the drawn symbols and the icon of every installed application. Clicking the pulsing button itself puts its original icon back — for a website that is its favicon. It is fetched only then, on your click and straight from the site (no icon service in between), and kept in ~/.config/copilot-key/icons/, so it works offline from then on.
• Esc leaves the editor, Esc again closes the menu.

There is no save button: every change is written the moment you make it.

The editor writes the very same file you can also edit yourself: ~/.config/copilot-key/config.toml. Changes take effect on the next key press; nothing needs restarting. Saving keeps one backup as config.toml.bak.

[general]
sounds = true
volume = 0.7
double_press_ms = 450
single_press = "toggle_or_menu"   # or "toggle" / "menu"
menu_title = "Was darf es sein?"
close_on_focus_loss = true
menu_style = "radial"             # or "list" for a plain vertical list
dim_opacity = 0.62                # how far the desktop behind is dimmed

[[actions]]
id = "claude-desktop"
label = "Claude Desktop"
subtitle = "Bring the window to the front, or start it"
command = "@claude-desktop"
icon = "window"
window_class = "claude"
primary = true

The order of the [[actions]] is the order in the menu and maps to the number keys 1–9. Set close_on_focus_loss = false if the menu disappears too early on an unusual desktop.

Placeholder in command	Effect
@claude-desktop	looks for an installed Claude desktop app, falls back to claude.ai in the browser
@terminal <cmd>	runs <cmd> in a new terminal window (the terminal stays open afterwards)
@browser <url>	opens <url> in the default application
@configure	opens the graphical menu editor
@edit-config	opens this file in the default editor

Anything else is executed as an ordinary command line. window_class is a substring of the window's WM_CLASS; find yours with wmctrl -lx.

Available icon values: window, terminal, globe, gear, chat, folder, power, sparkle. Without one, the icon is guessed from id and label, defaulting to sparkle.

A note on "Claude Desktop": there is no official desktop app for Linux. The common unofficial packages are detected (claude-desktop, claude-desktop-app, claude-desktop-bin); if none is installed, the action opens claude.ai in the browser instead. The @terminal claude action, on the other hand, starts the official Claude Code CLI.

---

Troubleshooting

./doctor.sh

checks the installation, the sound files, the audio server, the available players, the graphics libraries, keyd and the desktop shortcut — and plays a test cue at the end. No sound? The usual suspects:

• pulseaudio-utils missing → sudo apt install pulseaudio-utils
• Sounds not installed → run ./install.sh again
• One player refusing the file (pw-play rejects Ogg Vorbis in some builds): COPILOT_KEY_DEBUG=1 ~/.local/bin/copilot-sound menu-open 0.9 shows which player took it and which turned it down

If you get a plain list instead of the radial menu, python3-gi-cairo is missing (sudo apt install python3-gi-cairo).

---

Language

Menu texts, script output and the installed configuration template follow $LC_ALL, $LC_MESSAGES or $LANG. German is translated; everything else falls back to English. To force a language:

COPILOT_KEY_LANG=en ~/.local/bin/copilot-key menu

Adding one is small: add a dict with the same keys to STRINGS in bin/copilot-key, add a T_<CODE> array plus a case branch in lib/i18n.sh, and optionally a config/config.<code>.toml with translated labels. Missing keys fall back to English, so a partial translation works too. Pull requests are welcome.

The menu labels themselves come from your own config file, so you can rename them to anything you like regardless of locale.

---

Skins

menu_skin in [general] picks the look of the wheel. Three ship with the project:

Skin	Look
terracotta	the built-in one: flat discs, warm accent
aurora	modern multi-coloured 3D spheres with a highlight
mint	rounded squares, soft gradient, Linux Mint green

A skin is one small TOML file — colours, a button shape, a shading style. The editor's Skin tab lists everything it finds, previews it live and opens your own skin folder (~/.config/copilot-key/skins/), where a copy shadows the one that ships with the project.

Writing one takes a few lines and no code: docs/skins.md has the format, every key and the pitfalls.

---

Sounds

Eight cues from one sound family — soft glass bells on a pentatonic scale over D, short, quiet (peak −18 dBFS) and with a gentle attack, so nothing clicks or demands attention:

Cue	When	Character
menu-open	the menu opens	two rising notes, questioning
menu-dismiss	dismissed with Esc	the same falling and damped
launch	an action starts	rising arpeggio, affirmative
toggle-show	window comes forward	two bright notes rising a pure third
toggle-hide	window is minimised	its counterpart: two soft notes falling a third
error	action not available	low two-tone, deliberately not harsh
drag-lift	a button is picked up	short upward pluck
drag-drop	it settles again	a plop, damped at once

Listen to them:

~/.local/bin/copilot-key test-sounds

The files are synthesised from scratch — pure additive synthesis with numpy, no samples, no recordings, no third-party audio of any kind. The generator is included and reproduces them exactly:

python3 tools/generate_sounds.py sounds

Sound themes

Those glass bells are one of three themes:

Theme	Sound	Comes with the skin
default — Glass	soft glass bells	Terracotta
crystal — Crystal	bright chimes an octave higher	Aurora 3D
felt — Felt	soft wooden mallets, low and muted	Mint

sound_theme = "auto" — the default — plays whatever the skin brings along; naming a theme keeps it whichever skin you pick. The editor's Sounds tab lists the themes, plays every cue on request, and lets you replace a single one with a file of your own or mute it. Such a file is copied into ~/.config/copilot-key/sounds/, so tidying up Downloads breaks nothing.

A theme of your own is a folder of audio files — it need not be complete, whatever it leaves out comes from the theme it inherits from. docs/sound-themes.md has the details.

---

Other desktops

The installer registers the shortcut automatically on Cinnamon only. Elsewhere, bind Ctrl+Alt+Shift+F12 to ~/.local/bin/copilot-key by hand:

• GNOME — Settings → Keyboard → Keyboard Shortcuts → Custom Shortcuts
• KDE Plasma — System Settings → Shortcuts → Custom Shortcuts
• XFCE — Settings → Keyboard → Application Shortcuts

Under Wayland the menu and the sounds work; toggling windows needs wmctrl/xdotool and therefore X11 or XWayland. Dimming the background requires a running compositor (the default under Cinnamon); without one the overlay simply covers the screen opaquely.

---

Project layout

bin/copilot-key          launcher: toggle logic, menu, cue playback
bin/copilot-sound        cue playback (paplay / pw-play / ffplay / mpv / aplay)
bin/copilot-config       graphical editor for the menu, with app search
skins/                   the three shipped skins
docs/skins.md            how to write your own skin
docs/sound-themes.md     how to make your own sound theme
lib/i18n.sh              string catalogue for the shell scripts
config/config.toml       configuration template (English, printed by the editor)
config/config.de.toml    configuration template (German, printed by the editor)
config/keyd-copilot.conf keyd rule for the Copilot chord
config/copilot-key-config.desktop  start menu entry for the editor
config/copilot-key-autostart.desktop  per-user setup at login
sounds/                  eight CC0 cues; crystal/ and felt/ are two more themes
tools/generate_sounds.py sound generator
detect-key.sh            shows what the key actually sends
doctor.sh                checks installation, audio chain and shortcut
docs/menu.png            screenshot of the radial menu
docs/editor.png          screenshot of the editor
docs/edit-mode.png       screenshot of the wheel in edit mode
install.sh / uninstall.sh

---

License

Code: MIT (see LICENSE). Sounds: CC0 1.0 (see sounds/LICENSE).

This project is not affiliated with Anthropic, Microsoft or Minisforum. "Claude", "Copilot" and "Minisforum" are trademarks of their respective owners and are used here descriptively only.