# Copilonidal

**Your tailbone hurts while Copilot works. It relaxes when Copilot is ready.**

A Chrome toolbar button that shows whether GitHub Copilot CLI is working, with optional desktop notifications. It works on macOS, Ubuntu and Windows.

> *pilonidal* (adj.): at the tailbone. Pilonidal disease comes from long hours in the seat. In World War II it was called "jeep driver's disease".

- Website: <https://copilonidal.tpojka.com>
- Source: <https://github.com/Tpojka/copilonidal>

---

## Three states, one glance

| Icon | State | Meaning |
| :-: | --- | --- |
| 🔴 | **Working** | Copilot CLI is working on a task in at least one session |
| 🟢 | **Ready** | Copilot has finished, or is waiting for your permission or an answer |
| ⚪ | **Not connected** | The local helper isn't running. Run the installer |

Hover over the icon to see how many sessions are working.

## What you get

- **Live toolbar status:** the icon changes the moment Copilot starts or finishes, with no polling delay.
- **Every session:** the tailbone hurts while *any* Copilot CLI session is working.
- **OS notifications:** optional alerts when Copilot finishes or needs your permission, with or without sound.
- **Three platforms:** macOS, Ubuntu/Linux and Windows. The installer detects which one you're on.
- **Stays out of the way:** its hooks live in a file of their own in `~/.copilot/hooks`. Your other hooks and settings are never touched.
- **Fully local:** nothing leaves your machine. The status goes from Copilot CLI hooks to Chrome over native messaging.

## Install

Requires Python 3.9 or newer, Google Chrome and GitHub Copilot CLI.

**macOS**

```sh
git clone https://github.com/Tpojka/copilonidal.git
cd copilonidal
./install.sh
```

**Ubuntu**

```sh
sudo apt install python3 libnotify-bin   # notify-send, for the notifier
git clone https://github.com/Tpojka/copilonidal.git
cd copilonidal
./install.sh
```

**Windows**

```bat
winget install Python.Python.3.12
git clone https://github.com/Tpojka/copilonidal.git
cd copilonidal
install.cmd
```

The installer asks:

```
  1) Chrome extension
  2) Chrome extension + OS notifier
  3) Nothing (exit)
Choose 1, 2 or 3: 2
Play a sound with notifications? [Y/n]:
```

Then load the extension (once):

1. Open `chrome://extensions` and turn on **Developer mode**.
2. Click **Load unpacked** and pick the `extension` folder the installer printed.
3. Pin **Copilonidal** to the toolbar.
4. Restart any running Copilot CLI sessions so they load the hooks.

## OS notifier

You get a notification when Copilot finishes a turn or needs your permission. The title includes the project name.

Change the settings any time from the repository. They take effect with the next notification, with no restart:

```sh
python3 -m copilonidal.install set sound off           # silent notifications
python3 -m copilonidal.install set sound on
python3 -m copilonidal.install set notifications off   # no notifications at all
python3 -m copilonidal.install set notifications on
```

On Windows, use `py -3` instead of `python3`.

Or use your OS settings:

| OS | Where |
| --- | --- |
| macOS | System Settings → Notifications → **Script Editor** |
| Ubuntu (GNOME) | Settings → Sound → **System Sounds**, or Notifications → Do Not Disturb |
| Windows | Settings → System → Notifications → **Windows PowerShell** |

## How it works

```
Copilot CLI ──hook──► copilonidal.pyz hook ──► sessions/<id>   (busy | ready)
                                 └──────────► desktop notification (optional)

Chrome ──starts──► copilonidal.pyz host
                      watches sessions/, pushes status on change
                                  │  native messaging
                                  ▼
                   extension swaps the icon
```

It covers **GitHub Copilot CLI**, and Copilot's agent in VS Code with gaps: VS Code has no event for "needs you" notifications. It doesn't cover the Copilot cloud agent or Microsoft Copilot.

---

Copilonidal 1.0.0 · [MIT](https://github.com/Tpojka/copilonidal/blob/main/LICENSE) © 2026 Goran Grbic · An independent project, not affiliated with GitHub or Microsoft.