FocusKeeper

A cross-platform desktop application that automatically brings selected browser windows to the foreground based on configurable rules.

Features

• System Tray Operation: Runs primarily in the system tray
• Automatic Focus: Brings Chromium-based browser windows to foreground
• Multiple Modes: Single mode (focus one window) or Cycle mode (rotate through windows)
• Configurable Interval: Set focus interval from 1 second to 24 hours
• Idle Detection: Optional idle detection to only focus when user is away
• Global Shortcut: Press Ctrl+Alt+Q to stop scheduler and exit

Supported Platforms

• Windows: Full support using Windows API
• Linux: X11 environments only (requires xdotool and xprintidle)

Installation

Prerequisites

• Node.js 18+
• npm 9+

Install Dependencies

npm install

Development

Run the application in development mode:

npm run dev

This will compile TypeScript and launch Electron.

Build

Build the application:

npm run build

Package for Distribution

# Package for current platform
npm run pack

# Package for Windows
npm run dist:win

# Package for Linux
npm run dist:linux

Linux Dependencies

On Linux, the following dependencies are required:

xdotool

Window manipulation tool used to detect and focus windows.

# Debian/Ubuntu
sudo apt install xdotool

# Fedora
sudo dnf install xdotool

# Arch Linux
sudo pacman -S xdotool

xprintidle

Tool to detect user idle time.

# Debian/Ubuntu
sudo apt install xprintidle

# Fedora
sudo dnf install xprintidle

# Arch Linux
sudo pacman -S xprintidle

How the Scheduler Works

Single Mode

In single mode, the scheduler focuses the first selected window every interval:

1. Start scheduler with selected windows
2. Every intervalMs milliseconds:
   • Check if user is idle (if idle threshold is set)
   • If idle, focus the first selected window
   • Skip if already focused or window doesn't exist

Cycle Mode

In cycle mode, the scheduler rotates through selected windows:

1. Start scheduler with selected windows
2. Every intervalMs milliseconds:
   • Check if user is idle (if idle threshold is set)
   • If idle, focus the next window in the sequence
   • Skip if already focused or window doesn't exist
   • Move to next window for next cycle

Safety Features

• Never focus if already focused: Skips focus attempts if the target window is already active
• Window existence check: Verifies window still exists before attempting focus
• Idle detection: Optional threshold to only focus when user is away
• Graceful error handling: Handles missing windows and errors without crashing

Configuration

Configuration is stored in:

• Windows: %APPDATA%/FocusKeeper/config.json
• Linux: $HOME/.config/FocusKeeper/config.json

Config Fields

Field	Type	Description	Default
mode	string	"single" or "cycle"	"single"
selectedWindows	array	Window IDs to focus	[]
intervalMs	number	Focus interval in ms	30000
idleThresholdMs	number/null	Idle threshold in ms	null
globalShortcut	string	Global shortcut to exit	"CommandOrControl+Alt+Q"

Validation

• intervalMs: Clamped to 1,000 - 86,400,000 ms (1s to 24h)
• idleThresholdMs: Clamped to 1,000 - 86,400,000 ms if set

Usage

1. Launch: App starts in system tray
2. Open Settings: Double-click tray icon or use tray menu
3. Select Windows: Check browser windows you want to focus
4. Choose Mode: Single (one window) or Cycle (rotate through)
5. Set Interval: Choose preset or enter custom interval
6. Start: Click "Start Scheduler"

Keyboard Shortcut

• Ctrl+Alt+Q: Stop scheduler and exit application immediately

Supported Browsers

The app detects these Chromium-based browsers:

• Google Chrome
• Chromium
• Microsoft Edge
• Brave

Logging

Key actions are logged to console:

• Scheduler start/stop
• Window focus attempts
• Errors and warnings

Safety Notes

⚠️ Warning: Focus Stealing Behavior

This application automatically brings windows to the foreground. This can:

1. Interrupt typing: If you're typing in another application, the focus switch can interrupt your work
2. Cause data loss: Focus changes in applications with unsaved data could lead to lost work
3. Be disruptive: Frequent focus changes can be annoying during focused work

Recommendations

• Use with caution in professional environments
• Set appropriate intervals (avoid very short intervals)
• Enable idle detection to only focus when you're away
• Test with non-critical applications first

Project Structure

focuskeeper/
├── src/
│   ├── main/
│   │   ├── main.ts         # Main entry point
│   │   ├── tray.ts         # System tray management
│   │   ├── ipc.ts          # IPC handlers
│   │   ├── scheduler.ts    # Focus scheduling
│   │   ├── focusManager.ts # Focus operations
│   │   ├── windowManager.ts# Window detection
│   │   ├── idleMonitor.ts  # Idle detection
│   │   └── preload.ts      # Preload script
│   ├── config/
│   │   ├── defaultConfig.ts# Default configuration
│   │   └── configManager.ts# Config persistence
│   ├── platform/
│   │   ├── windows.ts      # Windows-specific code
│   │   └── linux.ts        # Linux-specific code
│   └── renderer/
│       ├── index.html      # Settings UI
│       ├── app.ts          # UI logic
│       └── style.css       # Styles
├── package.json
├── tsconfig.json
└── README.md

License

MIT