Credit goes first to Stephan Coertzen https://github.com/jfscoertzen/ChatGPT-client/ This was the base repo used and itterated on to create this custom version tailored to my own use case.

ChatGPT Electron Wrapper

A local Electron desktop wrapper for ChatGPT. It provides a tabbed shell, persistent windows, configurable shortcuts, diagnostic logging, quick access windows, and Linux-friendly packaging around the normal ChatGPT web app.

This project is not an official OpenAI desktop client. It loads ChatGPT in Electron using the user's normal ChatGPT account and session.

Install

npm install

Run

npm start

The app uses Electron single-instance behavior. If another packaged copy of this wrapper is already running, a repo launch may hand off to that instance and exit.

Test

npm test

Coverage check:

npm run test:coverage

Current Functionality

ChatGPT Shell

• Loads https://chatgpt.com in a desktop Electron window.
• Shares one persistent ChatGPT login/session across all main tabs and compatibility windows.
• Persists window geometry, maximized state, title-bar mode, tab URLs, active tab, and multi-window layout.
• Restores multiple saved windows and tabs on startup.
• Preloads saved tabs so switching between restored tabs is fast.
• Blocks unsafe or unrelated external navigation inside ChatGPT views and opens allowed ChatGPT/OpenAI navigation in-app.
• Sends blocked-navigation notices to the shell UI.

Tabs

• Creates, activates, closes, and restores tabs.
• Supports horizontal drag reorder within a tab strip.
• Supports middle-click tab close.
• Supports context-menu tab actions:
  • New tab
  • Close current tab
  • Move tab to new window
  • Move tab to another existing window
  • Open tab URL in the system browser
• Supports dragging a tab downward/outside the window to detach it into a separate app window.
• Shows a floating tab-like preview while dragging out.
• Opens the detached window near the mouse drop point and clamps it into the nearest display work area.
• Cleans up stale floating previews on drag cancel, Escape, blur, source window close, renderer crash, app quit, and display changes.

Window Behavior

• Supports multiple independent ChatGPT shell windows.
• Closing one window does not close unrelated windows.
• Closing the last tab in a window closes only that window when other windows still exist.
• Closing the final remaining tab minimizes/hides the app instead of exiting outright.
• Supports tray behavior when a tray is available.
• Rebuilds the tray icon after physical monitor or taskbar topology changes and retries startup tray registration if the desktop shell was not ready yet.
• Supports single-instance app activation.
• Supports custom title bar and system title bar modes.
• Keeps the active ChatGPT view fitted during fullscreen and rapid window resizing.

Voice Compatibility

• Provides an Open Active Tab in Voice Window option.
• The voice window opens the active ChatGPT tab URL in a normal top-level Electron BrowserWindow using the same ChatGPT session.
• This is intended for ChatGPT features that behave better in a normal foreground browser window than in an embedded BrowserView.
• Includes microphone, camera, notifications, media, and speaker-selection permission handling for trusted ChatGPT/OpenAI origins.
• Includes speaker-selection and selectAudioOutput compatibility shims where Electron/browser support is incomplete.

Quick Chat

• Provides a separate quick-chat window controlled by the global Toggle Quick Chat shortcut.
• Persists quick-chat window geometry and URL.
• Uses the same ChatGPT session as the main app.
• Can be opened/hidden from the tray menu or hotkey.

Shortcuts

Configurable shortcuts are available through the keyboard shortcut editor.

Defaults:

• Toggle Quick Chat: Alt+Space
• Open Web Debug Window: CommandOrControl+Alt+D
• New Tab: CommandOrControl+T
• Close Current Tab: CommandOrControl+W
• Refresh Current Tab: F5
• Reset Font Size: CommandOrControl+/

Global shortcuts:

• Toggle Quick Chat
• Open Web Debug Window

Window-local shortcuts:

• New tab
• Close current tab
• Refresh current tab
• Reset font size

Font Size

• Stores defaultFontSize in the app preferences file.
• Default value is 16.
• Supported values are 10 through 28.
• Ctrl+wheel adjusts the active ChatGPT view in small steps.
• The reset-font-size shortcut restores the configured default.

Default Downloads

• Stores defaultDownloadDirectory in the app preferences file.
• Defaults to the system Downloads folder.
• The Default Download Folder settings menu lets the user choose a preferred folder or reset to the system Downloads folder.
• The preferred folder seeds the first artifact save dialog after app startup, and seeds the next save dialog after the preference changes.
• After that first seeded save, the system file picker can remember the last subdirectory chosen inside the save dialog, so repeated saves can stay in that subdirectory.

Auto Image Downloads

• Stores autoImageDownloadEnabled and autoImageDownloadDirectory in the app preferences file.
• Defaults to disabled.
• Defaults the folder to the active default download directory plus automated_downloads.
• When enabled, loaded ChatGPT content images with a content?id=... URL are saved automatically without prompting.
• The content id is used as the saved filename basename, and existing ids are skipped.
• The Auto Image Download menu shows the active folder and its current recursive size.

Debugging And Logs

• Main-process diagnostic logging is configurable from the app menu/settings menu.
• Debug levels:
  • error: errors only
  • info: operational messages
  • fine: useful debugging details
  • finer: verbose data dumps and high-volume diagnostics
• Log location can be changed from the menu.
• Logs can be saved as an uploadable snapshot.
• The main debug window can be opened from the settings menu or shortcut.
• Renderer console logs from ChatGPT views can be captured with the configured debug level.
• Drag-detach placement diagnostics include:
  • renderer screenX/screenY
  • Electron cursor point when available
  • selected display work area
  • display scale factor
  • requested detached-window bounds
  • final clamped detached-window bounds

Preferences And State

Preferences are stored under Electron's userData directory in preferences.json.

Persisted data includes:

• title-bar mode
• default font size
• default download directory
• auto-image download enabled state and optional custom directory
• debug level and log directory
• main window bounds/maximized state
• multi-window tab/session layout
• quick-chat window state
• hotkeys
• main debug startup preference

The app stores tab URLs and window layout. It does not store ChatGPT message content itself beyond what ChatGPT and the Electron session already persist.

What This App Can Do

• Provide a desktop shell around the ChatGPT web app.
• Keep multiple ChatGPT tabs and windows organized.
• Detach tabs into separate windows by drag or context menu.
• Improve usability around title bars, shortcuts, font sizing, tray behavior, and debug logging.
• Seed ChatGPT artifact save dialogs from a configured default download folder without overriding the file picker's later subdirectory memory.
• Automatically save loaded ChatGPT content images to a configured local folder when enabled.
• Reuse the same logged-in ChatGPT session across main tabs, quick chat, and the voice compatibility window.
• Help diagnose window placement, permission, navigation, and renderer-console issues.

What This App Cannot Do

• It cannot enable ChatGPT features that are disabled by the user's ChatGPT account, workspace, region, subscription, or ChatGPT settings.
• It cannot bypass OpenAI-side feature flags, model availability, voice settings, or service outages.
• It cannot guarantee that ChatGPT's web UI will keep the same DOM, behavior, or feature-detection logic over time.
• It cannot make every browser API identical to Chrome. Electron support and ChatGPT-side checks may differ.
• It cannot guarantee floating drag previews work perfectly on every Linux compositor, Wayland/XWayland setup, display scale, or multi-monitor layout.
• It is not a general-purpose browser. Navigation is intentionally restricted to trusted ChatGPT/OpenAI URLs.
• It does not provide browser extensions, password-manager integration, sync, or full browser profile management.
• It does not implement automatic updates.
• It does not replace manual QA on packaged artifacts. Repo behavior and packaged AppImage behavior should both be checked for release confidence.

Manual QA

Drag-preview manual QA is documented in:

docs/drag-preview-manual-test.md

Important checks:

• horizontal tab reorder still works
• drag-out preview appears and follows the cursor
• detach opens near the mouse drop point
• detach clamps near screen edges
• Escape/blur/pointer cancel remove the preview without detaching
• context-menu detach still works
• custom and system title-bar modes both work
• default download folder seeds the first artifact save after startup, then allows repeated saves to remain in the last chosen subdirectory
• auto image download can be enabled, shows folder size, and skips an already-saved content id
• packaged AppImage behavior matches repo behavior

Build Locally For Linux

Run these commands on a Linux machine.

Full Linux AppImage

npm run build:linux

Build outputs are generated in dist/:

• .AppImage

Linux Directory Build Check

npm run build:appimage -- --dir

This keeps the AppImage target selected, but asks Electron Builder to leave an unpacked app in dist/linux-unpacked for inspection.

Build Locally For Windows

Run these commands on a Windows machine.

Full Windows Installer And Portable Builds

npm run build:windows

Build outputs are generated in dist/:

• Windows installer .exe
• Windows portable .exe

Windows Directory Build Check

npm run build:windows -- --dir

This generates dist/win-unpacked for inspection without creating the installer/portable artifacts.

Optional: Windows Directory Check From Linux

From Linux, you can run a no-Wine packaging sanity check:

npm run build:windows -- --dir

This generates dist/win-unpacked. Full Windows installer/portable artifacts should be built on Windows, or from Linux only if you intentionally install and use Wine.

One-Click Extracted Deploy

Build the AppImage, extract its contents, install the unpacked app into ~/.local/opt/chatgpt/app, register a desktop entry, and create a ~/.local/bin/chatgpt launcher that does not depend on FUSE:

npm run deploy:appimage

If the installed app is running, deployment stops it before replacing the application files and starts the newly installed version afterward.

Windows Manual Test Checklist

• Launch the app.
• Confirm login/session persistence works.
• Confirm the tray icon appears and tray menu works.
• Change physical monitor/taskbar configuration and confirm the tray icon returns.
• Confirm close-to-tray behavior works.
• Fullscreen and rapidly resize the main window; confirm ChatGPT content fills the window.
• Confirm Quit exits fully.
• Confirm the main window opens and restores.
• Confirm Quick Chat opens, hides, restores, and persists size.
• Confirm configurable hotkeys save and work after restart.
• Confirm the default download folder can be changed, seeds the first artifact save dialog after restart, and then allows repeated saves to remain in the last chosen subdirectory.
• Confirm tabs create, close, reorder, detach, and persist.
• Confirm external link blocking still works.
• Confirm title-bar mode changes still work.