# gitfrog1111/openwhip architecture

> Architecture diagram of the GitHub repository gitfrog1111/openwhip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gitfrog1111/openwhip
- Repository: https://github.com/gitfrog1111/openwhip

## Overview

OpenWhip is an Electron tray utility for interrupting and prompting Claude Code with keyboard automation. The user clicks the tray icon to show or drop a full-screen whip overlay, then clicks the whip to send Ctrl-C and an encouraging prompt to the previously active app. The launcher starts Electron; the main process owns tray, overlay, IPC handling, and platform-specific input. The README documents the user workflow; overlay internals were not sampled, so its click-to-IPC wiring is not asserted.

Main entry points: [`main.js`](https://github.com/gitfrog1111/openwhip/blob/main/main.js) (Electron main), [`bin/openwhip.js`](https://github.com/gitfrog1111/openwhip/blob/main/bin/openwhip.js) (CLI launcher), [`preload.js`](https://github.com/gitfrog1111/openwhip/blob/main/preload.js) (IPC bridge), [`overlay.html`](https://github.com/gitfrog1111/openwhip/blob/main/overlay.html) (Whip overlay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["App launch"]
  node_launcher["CLI launcher<br/>[openwhip.js]"]
end

subgraph group_interface["Tray and overlay"]
  node_main["Electron main<br/>[main.js]"]
  node_tray["Tray controls<br/>[main.js]"]
  node_overlay["Whip overlay<br/>[overlay.html]"]
  node_preload["IPC bridge<br/>[preload.js]"]
end

subgraph group_automation["Keyboard automation"]
  node_macro["Macro dispatch<br/>[main.js]"]
  node_windows["Windows input<br/>[main.js]"]
  node_macos["macOS input<br/>[main.js]"]
  node_linux["Linux input<br/>[main.js]"]
end

node_user(("User"))
node_activeapp["Active app"]

node_user -->|"runs command"| node_launcher
node_launcher -->|"starts Electron"| node_main
node_user -->|"clicks icon"| node_tray
node_main -->|"loads window"| node_overlay
node_main -->|"configures preload"| node_preload
node_main -->|"sends spawn/drop"| node_overlay
node_preload -->|"sends IPC"| node_main
node_main -->|"handles crack event"| node_macro
node_macro -->|"dispatches on Windows"| node_windows
node_macro -->|"dispatches on macOS"| node_macos
node_macro -->|"dispatches on Linux"| node_linux
node_windows -->|"types keystrokes"| node_activeapp
node_macos -->|"types keystrokes"| node_activeapp
node_linux -->|"types keystrokes"| node_activeapp

click node_launcher "https://github.com/gitfrog1111/openwhip/blob/main/bin/openwhip.js"
click node_main "https://github.com/gitfrog1111/openwhip/blob/main/main.js"
click node_tray "https://github.com/gitfrog1111/openwhip/blob/main/main.js"
click node_overlay "https://github.com/gitfrog1111/openwhip/blob/main/overlay.html"
click node_preload "https://github.com/gitfrog1111/openwhip/blob/main/preload.js"
click node_macro "https://github.com/gitfrog1111/openwhip/blob/main/main.js"
click node_windows "https://github.com/gitfrog1111/openwhip/blob/main/main.js"
click node_macos "https://github.com/gitfrog1111/openwhip/blob/main/main.js"
click node_linux "https://github.com/gitfrog1111/openwhip/blob/main/main.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_user toneBlue
class node_main,node_tray,node_overlay,node_preload toneAmber
class node_macro,node_windows,node_macos,node_linux toneMint
class node_activeapp toneIndigo
```

## Components

### App launch

- [CLI launcher](https://github.com/gitfrog1111/openwhip/blob/main/bin/openwhip.js): `bin/openwhip.js`

### Tray and overlay

- [Electron main](https://github.com/gitfrog1111/openwhip/blob/main/main.js): `main.js`
- [Tray controls](https://github.com/gitfrog1111/openwhip/blob/main/main.js): `main.js`
- [Whip overlay](https://github.com/gitfrog1111/openwhip/blob/main/overlay.html): `overlay.html`
- [IPC bridge](https://github.com/gitfrog1111/openwhip/blob/main/preload.js): `preload.js`

### Keyboard automation

- [Macro dispatch](https://github.com/gitfrog1111/openwhip/blob/main/main.js): `main.js`
- [Windows input](https://github.com/gitfrog1111/openwhip/blob/main/main.js): `main.js`
- [macOS input](https://github.com/gitfrog1111/openwhip/blob/main/main.js): `main.js`
- [Linux input](https://github.com/gitfrog1111/openwhip/blob/main/main.js): `main.js`

### Other components

- **User**
- **Active app**

## Connections

- User → CLI launcher: runs command (evidence: `README.md`)
- CLI launcher → Electron main: starts Electron (evidence: `bin/openwhip.js`)
- User → Tray controls: clicks icon (evidence: `main.js`)
- Electron main → Whip overlay: loads window (evidence: `main.js`)
- Electron main → IPC bridge: configures preload (evidence: `main.js`)
- Electron main → Whip overlay: sends spawn/drop (evidence: `main.js`)
- IPC bridge → Electron main: sends IPC (evidence: `preload.js`)
- Electron main → Macro dispatch: handles crack event (evidence: `main.js`)
- Macro dispatch → Windows input: dispatches on Windows (evidence: `main.js`)
- Macro dispatch → macOS input: dispatches on macOS (evidence: `main.js`)
- Macro dispatch → Linux input: dispatches on Linux (evidence: `main.js`)
- Windows input → Active app: types keystrokes (evidence: `main.js`)
- macOS input → Active app: types keystrokes (evidence: `main.js`)
- Linux input → Active app: types keystrokes (evidence: `main.js`)
