> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> Get alerted when your agents finish working

CliDeck sends browser notifications when an agent transitions from working to idle. This lets you step away from your computer and come back only when something needs your attention.

## How It Works

1. CliDeck tracks each agent's working/idle status (via telemetry events for Claude Code, Codex, and Gemini CLI; via I/O heuristics for Shell and custom agents)
2. When an agent transitions from working to idle, CliDeck confirms the transition
3. If the CliDeck tab is **not in focus**, a browser notification fires
4. If sound is enabled, a notification sound plays (also only when the tab is not in focus)

The notification includes:

* Session name
* Project name (if assigned)
* The latest message preview from the agent

## Setting Up

<Steps>
  <Step title="Enable notifications">
    Open **Settings** > **Notifications** and check **Notify when agent finishes working**.
  </Step>

  <Step title="Allow browser notifications">
    Click **Enable browser notifications**. Your browser will ask for permission — click **Allow**.
  </Step>

  <Step title="Optional: Enable sound">
    Check **Play sound** and pick from 7 built-in notification sounds. Use the preview button to hear each one before choosing.
  </Step>
</Steps>

## Notification Sounds

CliDeck includes 7 notification sounds:

| Sound        | Style                           |
| ------------ | ------------------------------- |
| Default Beep | Short, neutral beep             |
| Soft Beep    | Quieter, gentler tone           |
| Bold Beep    | Louder, more attention-grabbing |
| Echo Beep    | Beep with reverb                |
| Musical Beep | Melodic tone                    |
| Small Bleep  | Quick, subtle bleep             |
| Space        | Sci-fi inspired tone            |

## Minimum Working Time

To reduce noise, you can set a minimum working time before notifications fire. If an agent works for less than this threshold, no notification is sent.

Open **Settings** > **Notifications** and adjust the **Minimum working time** dropdown (5 seconds to 60 seconds).

This prevents notifications from firing when an agent does a quick check and immediately goes idle.

## Muting Individual Sessions

If a particular session is too noisy, you can mute it without disabling notifications globally:

* Right-click the session > **Mute**
* Or click the session menu button > **Mute**

Muted sessions show a mute icon in the sidebar. They still show status changes visually, just no notifications or sounds.

## When Notifications Don't Fire

Notifications only fire when:

* The CliDeck browser tab is **not in focus** (if you're already looking at it, you don't need a notification)
* The active session is **not the one that just finished** (if you're already watching that session, no notification)
* The session is **not muted**
* The agent worked for longer than the minimum working time threshold
* Browser notification permission is **granted**