FloatingClock

A minimal, lightweight floating clock for macOS that stays above all windows.

Built entirely by Claude Code

Features

• Always on top - Floating window that stays above all other windows
• Liquid Glass effect - Beautiful translucent material with adaptive text that stays readable on any background
• Menu bar integration - No Dock icon, clean and unobtrusive
• Global hotkey - Toggle visibility with Cmd+Shift+C (configurable)
• Hot-reload config - JSON configuration with automatic reload
• CLI control - Run, kill, reload, toggle from terminal
• Resizable - Drag to resize with automatic font scaling
• Position persistence - Remembers position across launches

Requirements

• macOS 26+
• Xcode 26+ Command Line Tools

Installation

# Clone and build
cd FloatingClock
make install

This installs to ~/bin. Make sure ~/bin is in your PATH:

export PATH="$HOME/bin:$PATH"

Usage

CLI Commands

floatingclock run       # Launch the floating clock
floatingclock kill      # Terminate the floating clock
floatingclock toggle    # Toggle visibility
floatingclock reload    # Reload configuration
floatingclock status    # Check if running
floatingclock config    # Open config file in editor

Menu Bar

Click the clock icon in the menu bar for:

• Show/Hide Clock
• Reload Config
• Open Config File
• Quit

Keyboard Shortcut

Default: Cmd+Shift+C to toggle visibility (configurable)

Configuration

Config file: ~/.config/floatingclock/config.json

{
  "showSeconds": false,
  "use24HourFormat": true,
  "toggleShortcut": "cmd+shift+c",
  "fontStyle": "sans",
  "animateDigits": false,
  "padding": 8,
  "cornerRadius": 16,
  "textSize": 100
}

Options

Option	Type	Description
showSeconds	bool	Show seconds in time display
use24HourFormat	bool	Use 24-hour format (vs 12-hour with AM/PM)
toggleShortcut	string	Global hotkey to toggle visibility
fontStyle	string	"sans", "mono", or "rounded"
animateDigits	bool	Animate digit changes
padding	int	Inner padding in pixels
cornerRadius	int	Corner radius in pixels
textSize	int	Font size percentage (100 = auto)

Shortcut Format

Modifiers: cmd, shift, opt/alt, ctrl

Examples:

• cmd+shift+c
• ctrl+alt+t
• cmd+opt+space

Window Behavior

• Drag: Click and drag anywhere on the clock to move it
• Resize: Drag from any edge or corner to resize
• Font scaling: Font automatically scales with window size
• Position: Window position is saved between launches

Uninstall

make uninstall

Config files are preserved at ~/.config/floatingclock/.

Building from Source

# Build only (no install)
make build

# Run directly from build directory
make run

# Clean build artifacts
make clean

Architecture

• Pure Swift/SwiftUI with no external dependencies
• Uses AppKit for window management (NSPanel)
• Carbon API for global hotkeys
• DistributedNotificationCenter for CLI-to-app IPC

License

MIT