### Create Windows Installer (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Command to build an NSIS installer for Windows. This command generates a setup executable for the x64 architecture, offering a custom install directory option.

```bash
pnpm build:win
```

--------------------------------

### Verify Development Prerequisites

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Commands to verify the installation of Node.js, pnpm, and Git, along with instructions for installing necessary native build tools on macOS.

```bash
node --version
pnpm --version
git --version
xcode-select --install
```

--------------------------------

### Initialize and Run ClaudeWatch

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Standard workflow for cloning the repository, installing project dependencies, and launching the application in development mode.

```bash
git clone <repo-url> ClaudeWatch
cd ClaudeWatch
pnpm install
pnpm dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Installs all required Node.js packages and triggers the post-install hook to compile native modules for the Electron environment.

```bash
pnpm install
```

--------------------------------

### Create Linux Installer (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Command to build a self-contained AppImage installer for Linux. This command creates an AppImage file that does not require system dependencies and is categorized as a 'Utility'.

```bash
pnpm build:linux
```

--------------------------------

### Create macOS Installer (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Command to build a universal DMG installer for macOS. This command generates a DMG file suitable for distribution, including support for both Intel and Apple Silicon architectures. It requires macOS entitlements for proper signing.

```bash
pnpm build:mac
```

--------------------------------

### Development and Lifecycle Scripts

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

A collection of shell commands used to manage the development lifecycle, including starting the dev server, running tests, linting, and building production installers for various platforms.

```bash
pnpm dev
pnpm build
pnpm preview
pnpm test
pnpm test:watch
pnpm typecheck
pnpm lint
pnpm format
pnpm build:mac
pnpm build:win
pnpm build:linux
npm run release:patch
npm run release:minor
npm run release:major
```

--------------------------------

### Preload Bridge API

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Exposes the `window.api` object in the preload script, providing methods to interact with the main process via IPC. This includes functions for getting and setting settings, managing history, opening windows, and handling updates.

```APIDOC
## Preload Bridge API

### Description
The preload script (`src/preload/index.ts`) exposes `window.api` via `contextBridge`, allowing the renderer process to communicate with the main process using IPC.

### Methods

- **`getInstances()`**: Invokes `ipcRenderer.invoke('instances:get')` to retrieve Claude instance information.
- **`getSettings()`**: Invokes `ipcRenderer.invoke('settings:get')` to retrieve application settings.
- **`setSettings(settings)`**: Invokes `ipcRenderer.invoke('settings:set', settings)` to save application settings.
- **`getHistory()`**: Invokes `ipcRenderer.invoke('history:get')` to retrieve the command history.
- **`clearHistory()`**: Invokes `ipcRenderer.invoke('history:clear')` to clear the command history.
- **`openDashboard()`**: Invokes `ipcRenderer.invoke('app:open-dashboard')` to open the application dashboard.
- **`quit()`**: Invokes `ipcRenderer.invoke('app:quit')` to quit the application.
- **`openTerminal(path, terminalType?)`**: Invokes `ipcRenderer.invoke('terminal:open', path, terminalType)` to open a new terminal.
- **`onInstancesUpdate(callback)`**: Registers a listener for the `instances:update` IPC event. The `callback` function will be executed when updates are received.
- **`checkForUpdates()`**: Invokes `ipcRenderer.invoke('updater:check')` to check for available updates.
- **`downloadUpdate()`**: Invokes `ipcRenderer.invoke('updater:download')` to download the latest update.
- **`installUpdate()`**: Invokes `ipcRenderer.invoke('updater:install')` to install the downloaded update.
- **`onUpdaterStatus(callback)`**: Registers a listener for the `updater:status` IPC event. The `callback` function will be executed when the update status changes.
```

--------------------------------

### Resolve macOS build failures

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Commands to resolve common build failures on macOS by ensuring Xcode CLI tools are installed and cleaning the project environment.

```bash
# Install Xcode CLI tools
xcode-select --install

# Clear node_modules and reinstall
rm -rf node_modules out dist
pnpm install
```

--------------------------------

### Pre-Build Checklist (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

A sequence of commands to execute before building the application for production. This checklist includes type checking, running all tests, linting, building the application, previewing the production build locally, and finally packaging for the target platform.

```bash
# 1. Verify types
pnpm typecheck

# 2. Run all tests
pnpm test

# 3. Lint
pnpm lint

# 4. Build
pnpm build

# 5. Preview locally (test production build without packaging)
pnpm preview

# 6. Package for your platform
pnpm build:mac   # or build:win or build:linux
```

--------------------------------

### Build Application (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Command to build the Electron application for production. This command invokes 'electron-vite build', which compiles the main process, preload script, and renderer assets into the 'out/' directory.

```bash
pnpm build
```

--------------------------------

### Manual Release Commands (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Commands for manually building and publishing releases to GitHub Releases. This involves bumping the version, building the application, and then using electron-builder with the GH_TOKEN to package and upload artifacts for macOS and Windows.

```bash
# 1. Bump version
npm version patch

# 2. Build
npm run build

# 3. Package and publish to GitHub Releases
GH_TOKEN=<your-token> npx electron-builder --mac --publish always
GH_TOKEN=<your-token> npx electron-builder --win --publish always
```

--------------------------------

### Build Configuration (YAML)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Configuration file for electron-builder, specifying application ID, product name, and directories for build resources and output. This YAML file defines key settings for the packaging process.

```yaml
appId: com.zkidz.claudewatch
productName: ClaudeWatch
directories:
  buildResources: build # Icons, entitlements, etc.
  output: dist # Built installers go here
```

--------------------------------

### Bundle Sound Files with Electron Builder (YAML)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Configures `electron-builder.yml` to include the `sounds` directory from the `resources` folder into the application's build. This ensures that custom sound files, such as `task-complete.aiff`, are correctly bundled and accessible in the production environment.

```yaml
# electron-builder.yml — add under mac.extraFiles
- from: resources/sounds
  to: sounds
```

--------------------------------

### Adding a New Platform

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Instructions for adding support for a new operating system platform by implementing the `PlatformDetector` interface.

```APIDOC
## Adding a New Platform

### Description
To add support for a new operating system platform, follow these steps to implement the `PlatformDetector` interface and register it within the application.

### Steps

1.  **Create Platform File**: Create a new TypeScript file for the platform in `src/main/platform/`, named `<platform>.ts` (e.g., `src/main/platform/linux.ts`).

2.  **Implement `PlatformDetector` Interface**: Define and implement the `PlatformDetector` interface within the new file. This interface requires the following methods:
    ```typescript
    interface PlatformDetector {
      getClaudeProcesses(): Promise<RawProcessInfo[]>
      getWorkingDirectory(pid: number): Promise<string>
    }
    ```
    - `getClaudeProcesses()`: Should return a promise that resolves to an array of `RawProcessInfo` objects for all detected Claude processes.
    - `getWorkingDirectory(pid: number)`: Should return a promise that resolves to the working directory path for the given process ID.

3.  **Register Platform Detector**: Update the `getPlatformDetector()` function in `src/main/process-monitor.ts` to include the newly created platform detector. This typically involves adding a conditional check for the platform name and returning the corresponding detector instance.
```

--------------------------------

### Quick Release Commands (Bash)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Commands to quickly release a new version of the application by bumping the version, creating a Git tag, and pushing to the remote repository. This process automatically triggers the CI/CD pipeline for building and publishing.

```bash
# Bump version, create git tag, push — triggers CI build + GitHub Release
npm run release:patch   # 1.0.0 → 1.0.1
npm run release:minor   # 1.0.0 → 1.1.0
npm run release:major   # 1.0.0 → 2.0.0
```

--------------------------------

### Platform Detection - macOS

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Details the process discovery and working directory retrieval methods for macOS, utilizing `ps` and `lsof` commands.

```APIDOC
## Platform Detection - macOS (`src/main/platform/darwin.ts`)

### Description
This section describes how Claude processes are discovered and their working directories are identified on macOS.

### Process Discovery
Uses the `ps` command to list running processes and filters the output based on specific criteria to identify Claude CLI processes.

**Command:**
```bash
ps -eo pid,stat,%cpu,%mem,etime,tty,command
```

**Filtering:**
- Excludes Claude.app GUI and Electron helper processes.
- Matches processes starting with `/claude\s/` (including bare `claude` command or full path ending in `claude`).

### Working Directory
Uses the `lsof` command to determine the current working directory of a given process ID (PID).

**Command:**
```bash
lsof -a -p <pid> -d cwd -Fn
```

**Extraction:**
Extracts the working directory path from the `lsof` output.
```

--------------------------------

### Platform Detection - Windows

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Details the process discovery and working directory retrieval methods for Windows, utilizing `tasklist` and `wmic` commands.

```APIDOC
## Platform Detection - Windows (`src/main/platform/win32.ts`)

### Description
This section describes how Claude processes are discovered and their working directories are identified on Windows.

### Process Discovery
Uses the `tasklist` command to find running `claude.exe` processes and then `wmic` to get their command line and executable path.

**Commands:**
1. List `claude.exe` processes:
   ```bash
   tasklist /FI "IMAGENAME eq claude.exe" /FO CSV /NH
   ```
2. Get process details (command line, executable path) for a given PID:
   ```bash
   wmic process where ProcessId=<pid> get CommandLine,ExecutablePath
   ```

### Working Directory
Extracts the working directory from the executable path obtained via `wmic`.
```

--------------------------------

### Platform Detection Commands

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

System-level commands used to identify running Claude CLI processes and their working directories on macOS and Windows platforms.

```bash
# macOS process discovery
ps -eo pid,stat,%cpu,%mem,etime,tty,command

# macOS working directory extraction
lsof -a -p <pid> -d cwd -Fn

# Windows process discovery
tasklist /FI "IMAGENAME eq claude.exe" /FO CSV /NH

# Windows process details
wmic process where ProcessId=<pid> get CommandLine,ExecutablePath
```

--------------------------------

### Context Menu (Right-Click)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Details the items and structure of the context menu that appears when the system tray icon is right-clicked.

```APIDOC
## Context Menu (right-click)

### Description
This describes the content and layout of the context menu that appears when the user right-clicks on the ClaudeWatch system tray icon.

### Menu Structure

```
ClaudeWatch — 5 instances
─────────────────────────────
🟢 MyProject — 00:05:32
🟢 OtherProject — 00:12:01
🟡 IdleProject — 01:23:45
🔴 FinishedProject — 00:30:00
─────────────────────────────
Open Dashboard
Check for Updates
─────────────────────────────
Quit
```

**Sections:**
- **Header**: Displays the application name and the count of active instances.
- **Instance List**: Shows individual Claude instances with their status (e.g., active, idle, finished) and duration.
- **Actions**: Provides options to open the dashboard or check for updates.
- **Quit**: Option to exit the application.
```

--------------------------------

### Project Structure of ClaudeWatch

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

This snippet provides a hierarchical view of the ClaudeWatch project's directory and file structure. It outlines the organization of source code, build resources, documentation, and configuration files, facilitating navigation and understanding of the project's architecture.

```tree
ClaudeWatch/
├── build/                          # Build resources (icons, entitlements)
├── dist/                           # Built installers (git-ignored)
├── out/                            # Compiled output (git-ignored)
├── plans/                          # Feature plans and roadmaps
├── docs/                           # Documentation
│
├── src/
│   ├── main/                       # Electron main process
│   │   ├── index.ts                # App entry point, lifecycle
│   │   ├── process-monitor.ts      # Claude process detection
│   │   ├── session-tracker.ts      # Instance lifecycle tracking
│   │   ├── store.ts                # Persistent settings (electron-store)
│   │   ├── tray.ts                 # Tray icon + popover window
│   │   ├── notifications.ts        # Native OS notifications
│   │   ├── auto-updater.ts         # Auto-update manager (electron-updater)
│   │   ├── ipc-handlers.ts         # IPC request handlers
│   │   ├── terminal-resolver.ts    # Detect parent terminal from process tree
│   │   ├── terminal-opener.ts      # Open project in detected terminal
│   │   ├── widget-stats-writer.ts  # Write stats.json for macOS widget
│   │   ├── widget-sync.ts          # Coordinate widget data updates
│   │   ├── format-utils.ts         # Duration formatting
│   │   └── platform/
│   │       ├── darwin.ts           # macOS process detection (ps/lsof)
│   │       ├── win32.ts            # Windows process detection (tasklist/wmic)
│   │       └── exec.ts             # execFile promise wrapper
│   │
│   ├── preload/                    # Context bridge
│   │   ├── index.ts                # Exposes window.api
│   │   └── index.d.ts             # Type declarations
│   │
│   └── renderer/                   # React UI
│       ├── main.tsx                # React entry point
│       ├── App.tsx                 # Root component + popover routing
│       ├── index.html              # HTML shell
│       ├── env.d.ts                # Global type augmentation
│       ├── components/
│       │   ├── Header.tsx          # Navigation + live indicator
│       │   ├── Dashboard.tsx       # Stats + filters + instance list
│       │   ├── InstanceList.tsx    # Instance card container
│       │   ├── InstanceCard.tsx    # Expandable instance row
│       │   ├── StatusBadge.tsx     # Colored status dot + label
│       │   ├── PopoverView.tsx     # Compact tray popover UI
│       │   ├── SessionHistory.tsx  # Past sessions view
│       │   ├── Settings.tsx        # Preferences view
│       │   └── ProjectTag.tsx      # Project name display
│       ├── hooks/
│       │   ├── useInstances.ts     # Instance state + filtering
│       │   ├── useSettings.ts      # Settings state management
│       │   └── useUpdater.ts       # Auto-update state + actions
│       ├── lib/
│       │   ├── types.ts            # Shared TypeScript types
│       │   └── utils.ts            # Formatting utilities
│       ├── styles/
│       │   └── globals.css         # Tailwind base + component utilities
│       └── __tests__/
│           ├── setup.ts            # Test environment setup
│           ├── components.test.tsx  # Component tests
│           ├── useInstances.test.ts # Hook tests
│           ├── useSettings.test.ts  # Hook tests
│           └── useUpdater.test.ts   # Auto-update hook tests
│
├── .github/
│   └── workflows/
│       └── release.yml             # CI/CD: build + publish on tag push
├── electron.vite.config.ts         # Vite config (main/preload/renderer)
├── electron-builder.yml            # Build/packaging config
├── tailwind.config.ts              # Tailwind theme + design tokens
├── postcss.config.js               # PostCSS (tailwindcss + autoprefixer)
├── tsconfig.json                   # Base TypeScript config
├── tsconfig.node.json              # Main process TS config
├── tsconfig.web.json               # Renderer TS config
├── vitest.config.ts                # Test configuration
├── package.json                    # Dependencies and scripts
└── .prettierrc                     # Code formatting rules
```

--------------------------------

### System Tray and Popover Window

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Describes the system tray icon, its interactions, and the functionality of the popover window that appears on hover or click.

```APIDOC
## Tray & Popover

### Description
This section details the system tray icon and the associated popover window, which serve as the primary user interface for ClaudeWatch.

### Tray Icon

The application is primarily represented by an icon in the system tray (menu bar on macOS, system tray on Windows/Linux).

- **Tray Title**: `● <active_count>` - Displays the number of currently active Claude instances.

- **Interactions**:
  | Action       | Result                               |
  |--------------|--------------------------------------|
  | **Hover**    | Opens the popover window.            |
  | **Left click** | Toggles the visibility of the popover. |
  | **Right click**| Opens the context menu.              |

### Popover Window

A small, frameless window (320x420 pixels) anchored below the tray icon.

- **Appearance**: Transparent with macOS vibrancy (`popover` material).
- **Behavior**: Auto-hides when the window loses focus (e.g., clicking outside).
- **Content**: Displays a compact list of Claude instances with live metrics, along with 'Open Dashboard' and 'Quit' buttons.
```

--------------------------------

### Verification Workflow

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

A composite command to ensure code quality and stability by running type checking, unit tests, and linting in a single sequence.

```bash
pnpm typecheck && pnpm test && pnpm lint
```

--------------------------------

### SoundPlayer Class for Task Completion Sounds (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Implements a `SoundPlayer` class in `sound-player.ts` to handle playing custom sounds on task completion. It determines the sound file path based on the environment (production or development) and provides an asynchronous `playTaskComplete` method. This method uses platform-specific commands (`afplay` for macOS, PowerShell for Windows) to play the sound, with graceful handling for missing sound files.

```typescript
// sound-player.ts
export class SoundPlayer {
  private soundPath: string

  constructor() {
    // In production: process.resourcesPath/sounds/task-complete.aiff
    // In dev: resources/sounds/task-complete.aiff
    this.soundPath = resolve(...)
  }

  async playTaskComplete(): Promise<void> {
    // macOS: execFile('afplay', [this.soundPath])
    // Windows: PowerShell [System.Media.SoundPlayer]
    // Graceful no-op if file missing
  }
}
```

--------------------------------

### Electron Architecture Structure

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

A visual representation of the three-process architecture (Main, Preload, Renderer) and their respective entry points within the project structure.

```text
electron.vite.config.ts
├── main      → src/main/index.ts         (Node.js — full system access)
├── preload   → src/preload/index.ts      (Bridge — limited, secure)
└── renderer  → src/renderer/main.tsx     (Browser — React UI)
```

--------------------------------

### Add Notification Settings to AppSettings (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Modifies the `AppSettings.notifications` interface in `types.ts` to include two new boolean settings: `onTaskComplete` and `pingSound`. These settings control whether notifications are triggered and custom sounds are played upon task completion, respectively. The `DEFAULT_SETTINGS` should also be updated to reflect the default values for these new options.

```typescript
// types.ts — add to AppSettings.notifications
onTaskComplete: boolean  // default true — notify when active → idle
pingSound: boolean       // default true — play custom ping on task complete
```

--------------------------------

### Code Signing Configuration for GitHub Actions

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

This snippet details the GitHub Actions secrets required for code signing builds. It specifies the base64-encoded certificate and its password, which are necessary for signing applications on macOS and Windows to avoid security warnings.

```yaml
- CSC_LINK — Base64-encoded .p12 certificate
- CSC_KEY_PASSWORD — Certificate password
```

--------------------------------

### Default Configuration Schema

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

The default settings object for ClaudeWatch, including polling intervals, CPU thresholds, and notification preferences.

```json
{
  "pollingIntervalMs": 3000,
  "cpuIdleThreshold": 3.0,
  "launchAtLogin": false,
  "notifications": {
    "onIdle": true,
    "onExited": true,
    "onError": true,
    "sound": true,
    "doNotDisturb": false
  },
  "theme": "dark",
  "maxHistoryEntries": 100
}
```

--------------------------------

### Expose IPC Bridge via Preload Script

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Defines the window.api object in the preload script to bridge the renderer process with the main process via ipcRenderer. This allows the UI to trigger actions like process management, settings updates, and application lifecycle control.

```typescript
window.api = {
  getInstances: () => ipcRenderer.invoke('instances:get'),
  getSettings: () => ipcRenderer.invoke('settings:get'),
  setSettings: (settings) => ipcRenderer.invoke('settings:set', settings),
  getHistory: () => ipcRenderer.invoke('history:get'),
  clearHistory: () => ipcRenderer.invoke('history:clear'),
  openDashboard: () => ipcRenderer.invoke('app:open-dashboard'),
  quit: () => ipcRenderer.invoke('app:quit'),
  openTerminal: (path, terminalType) => ipcRenderer.invoke('terminal:open', path, terminalType),
  onInstancesUpdate: (callback) => ipcRenderer.on('instances:update', callback),
  checkForUpdates: () => ipcRenderer.invoke('updater:check'),
  downloadUpdate: () => ipcRenderer.invoke('updater:download'),
  installUpdate: () => ipcRenderer.invoke('updater:install'),
  onUpdaterStatus: (callback) => ipcRenderer.on('updater:status', callback)
};
```

--------------------------------

### Renderer Communication (send/on)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Describes the IPC channels used for communication between the main process and the renderer process. This includes channels for updating instances, updater status, and other application events.

```APIDOC
## Renderer Communication (send/on)

### Description
This section outlines the IPC channels used for communication between the main process and the renderer process. These channels facilitate real-time updates and event handling within the ClaudeWatch application.

### Channels

#### `instances:update`
- **Direction**: Push
- **Payload**: `{ instances, stats }`
- **Description**: Pushes updates related to Claude instances and their statistics to the renderer.

#### `updater:status`
- **Direction**: Push
- **Payload**: `{ status: UpdateStatus, data?: UpdateInfo | UpdateProgress | string }`
- **Description**: Pushes the status of the update process, including any relevant data or progress information.
```

--------------------------------

### Node Environment Tests (Vitest)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Tests for the main process using the Node environment with Vitest. It imports testing utilities and a validation function to check settings, ensuring the polling interval is within a valid range.

```typescript
import { describe, it, expect, vi } from 'vitest'
import { validateSettings } from './ipc-handlers'

describe('validateSettings', () => {
  it('clamps pollingIntervalMs to valid range', () => {
    expect(validateSettings({ pollingIntervalMs: 100 })).toEqual({
      pollingIntervalMs: 500
    })
  })
})
```

--------------------------------

### Platform Detector Interface

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Defines the contract for implementing new platform-specific process monitoring logic. Each implementation must provide methods to list processes and resolve their working directories.

```typescript
interface PlatformDetector {
  getClaudeProcesses(): Promise<RawProcessInfo[]>
  getWorkingDirectory(pid: number): Promise<string>
}
```

--------------------------------

### Define Grouped Instance Types in useInstances Hook

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Extends the useInstances hook return type to include categorized instance arrays for recently completed, in-progress, and waiting tasks.

```typescript
groupedInstances: {
  recentlyCompleted: ClaudeInstance[]
  inProgress: ClaudeInstance[]
  waiting: ClaudeInstance[]
}
```

--------------------------------

### Default Settings

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Defines the default configuration settings for ClaudeWatch, including polling intervals, idle thresholds, notification preferences, and theme settings.

```APIDOC
## Default Settings

### Description
This section details the default configuration settings for the ClaudeWatch application. These settings control various aspects of the application's behavior, including performance, user interface, and notifications.

### Default Configuration Object

```typescript
{
  pollingIntervalMs: 3000,       // How often to scan for processes (in milliseconds)
  cpuIdleThreshold: 3.0,         // CPU percentage below which a process is considered idle
  launchAtLogin: false,          // Whether to launch the application automatically on system login (macOS/Windows)
  notifications: {
    onIdle: true,                // Enable notifications when an instance goes idle
    onExited: true,              // Enable notifications when an instance exits
    onError: true,               // Enable notifications for errors
    sound: true,                 // Play notification sounds
    doNotDisturb: false          // Suppress all notifications
  },
  theme: 'dark',                 // Application theme: 'dark', 'light', or 'system'
  maxHistoryEntries: 100         // Maximum number of entries to store in the command history
}
```
```

--------------------------------

### Renderer Tests (React Testing Library)

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Tests for the renderer process using jsdom and React Testing Library. This snippet demonstrates rendering the Dashboard component and asserting that a 'Total' stat card is present in the document.

```typescript
import { render, screen } from '@testing-library/react'
import { Dashboard } from '../components/Dashboard'

it('renders stat cards', () => {
  render(<Dashboard />)
  expect(screen.getByText('Total')).toBeInTheDocument()
})
```

--------------------------------

### Wire Task Completion Logic in Main Index

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Integrates the notification trigger into the instance-status-changed event handler. It ensures notifications and sounds only fire when transitioning from active to idle status.

```typescript
tracker.on('instance-status-changed', ({ instance, previousStatus }) => {
  if (previousStatus === 'active' && instance.status === 'idle') {
    notifier.notifyTaskComplete(instance)

    const settings = store.getSettings()
    if (settings.notifications.pingSound && !settings.notifications.doNotDisturb) {
      soundPlayer.playTaskComplete()
    }
  }
})
```

--------------------------------

### Add `lastBecameIdleAt` to ClaudeInstance Interface (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Extends the `ClaudeInstance` interface in `types.ts` to include `lastBecameIdleAt`. This optional `Date` property records the timestamp when an instance transitioned from 'active' to 'idle', aiding in the detection of recently completed tasks without adding a new explicit status.

```typescript
// types.ts — add to ClaudeInstance interface
lastBecameIdleAt?: Date  // timestamp when instance transitioned active → idle
```

--------------------------------

### Stamp `lastBecameIdleAt` on Status Change (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Modifies the `SessionTracker`'s `doPoll()` method in `session-tracker.ts` to stamp the `lastBecameIdleAt` timestamp when an instance's status changes from 'active' to 'idle'. This captures the precise moment of transition, providing crucial metadata for tracking task completion.

```typescript
// When instance goes active → idle, stamp the timestamp
if (prev && prev.status === 'active' && proc.status === 'idle') {
  proc.lastBecameIdleAt = new Date()
}
```

--------------------------------

### Validation Ranges

Source: https://github.com/theangeloumali/claudewatch/blob/main/README.md

Specifies the minimum, maximum, and default values for configurable settings, ensuring data integrity during validation.

```APIDOC
## Validation Ranges

### Description
This table outlines the valid ranges for key configurable settings in ClaudeWatch. Server-side validation is performed in `ipc-handlers.ts` before settings are persisted to ensure they fall within these acceptable limits.

| Setting             | Min   | Max   | Default | Description                                      |
| ------------------- | ----- | ----- | ------- | ------------------------------------------------ |
| `pollingIntervalMs` | 500   | 60000 | 3000    | Scan interval for processes in milliseconds.     |
| `cpuIdleThreshold`  | 0.1   | 100   | 3.0     | CPU usage percentage threshold for idle detection. |
| `maxHistoryEntries` | 1     | 10000 | 100     | Maximum number of history entries to store.      |
```

--------------------------------

### Implement Task Completion Notification in NotificationManager

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Adds a notifyTaskComplete method to the NotificationManager class. It checks user settings for notification preferences and displays a system notification when a task transitions to idle.

```typescript
notifyTaskComplete(instance: ClaudeInstance): void {
  const settings = this.getSettings()
  if (!settings.notifications.onTaskComplete || settings.notifications.doNotDisturb) return

  const notification = new Notification({
    title: '✅ Task complete',
    body: `${instance.projectName} — ran for ${instance.elapsedTime}`,
    silent: true
  })
  notification.show()
}
```

--------------------------------

### Calculate `recentlyCompleted` Count in `getStats` (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Implements the calculation for the `recentlyCompleted` count within the `getStats()` method in `session-tracker.ts`. It filters the list of instances to count those that are currently idle and whose `lastBecameIdleAt` timestamp is within the last 10 minutes (defined by `RECENT_WINDOW`), providing a real-time metric of recently finished tasks.

```typescript
const now = Date.now()
const RECENT_WINDOW = 10 * 60 * 1000
recentlyCompleted: instanceList.filter(
  i => i.status === 'idle' && i.lastBecameIdleAt &&
  (now - i.lastBecameIdleAt.getTime()) < RECENT_WINDOW
).length
```

--------------------------------

### Preserve `lastBecameIdleAt` Across Polls (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Updates the 'Update current instances map' section in `session-tracker.ts` to preserve the `lastBecameIdleAt` timestamp across polling intervals. This ensures that the idle timestamp is maintained as long as the instance remains idle, preventing data loss during continuous monitoring.

```typescript
if (prev) {
  proc.startedAt = prev.startedAt
  // Preserve idle timestamp unless status changed back to active
  if (prev.lastBecameIdleAt && proc.status === 'idle') {
    proc.lastBecameIdleAt = prev.lastBecameIdleAt
  }
}
```

--------------------------------

### Add `recentlyCompleted` Count to InstanceUpdate Stats (TypeScript)

Source: https://github.com/theangeloumali/claudewatch/blob/main/plans/macclaudetracker-task-tracking-notifications-2026-03-18.md

Updates the `InstanceUpdate.stats` interface in `types.ts` by adding a `recentlyCompleted` number field. This field will store the count of idle instances whose `lastBecameIdleAt` timestamp falls within the last 10 minutes, providing a metric for recently finished tasks.

```typescript
// types.ts — add to InstanceUpdate.stats
recentlyCompleted: number  // count of idle instances with lastBecameIdleAt < 10min
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.