A visual analog clock timer with URL schemes, calendar export, and floating window support. Perfect for removing temporal cognition load and maintaining focus on your primary tasks.
sessiontimer:// for seamless macOS and iOS integrationBreaking free from iCab dependency: v2.0 introduces native sessiontimer:// URL scheme support, eliminating reliance on third-party browsers while maintaining the same seamless experience.
| Legacy Versions: index.html | settings.html |
# 30-minute focus session (replaces iCab x-callback-url)
sessiontimer://timer?s=a,14:30,30&mode=down
# Pomodoro sequence
sessiontimer://segments?data=09:00,25,down|09:25,5,up|09:30,25,down|09:55,15,up
Made with respect to Dieter Rams.
cd macos-helper
./build.sh
cp "build/SessionTimer Helper.app" /Applications/
open "/Applications/SessionTimer Helper.app"
open "sessiontimer://timer?s=a,14:30,40&mode=down"
ios-shortcuts/SessionTimer-URLHandler.shortcutsessiontimer://timer?s=a,14:30,30&mode=downtimer-v2.html in Safaritimer-v2.html# Generate calendar from JSON segments
./scripts/generateCalendar.sh examples/pomodoro-session.json
# Custom output filename
./scripts/generateCalendar.sh my-segments.json my-calendar.ics
Example segments.json:
[
{"time": "09:00", "duration": 25, "mode": "down"},
{"time": "09:25", "duration": 5, "mode": "up"},
{"time": "09:30", "duration": 25, "mode": "down"}
]
Use the CLI script in Keyboard Maestro macros:
./generateCalendar.sh "$KMVAR_segments" && open "session-timer-$(date +%Y%m%d-%H%M%S).ics"
Built-in presets available in the enhanced settings panel:
# Count down 30 minutes (manual start)
timer.html?s=m,12:00,30&mode=down
# Count up 45 minutes (manual start)
timer.html?s=m,12:00,45&mode=up
Note: Use m instead of a for manual start. The time parameter is ignored for manual starts.
# Autostart at 2:30 PM, count down for 40 minutes (ends at 3:10 PM)
timer.html?s=a,14:30,40&mode=down
# Autostart at 9:00 AM, count up for 60 minutes (ends at 10:00 AM)
timer.html?s=a,09:00,60&mode=up
# Multiple segments with different modes
timer.html?segments=09:00,30,up|10:30,45,down|14:15,60,down
# Full day schedule
timer.html?segments=08:30,90,up|11:00,30,down|13:30,120,down|16:00,45,up
# Timer will autostart at 15:30 (3:30 PM) for 25 minutes
timer.html?s=a,15:30,25&mode=down
# Timer will autostart at 20:15 (8:15 PM) for 90 minutes
timer.html?s=a,20:15,90&mode=up
# Evening session - timers start later in the day
timer.html?segments=18:00,45,down|19:30,30,up|21:00,60,down
# Tomorrow morning schedule
timer.html?segments=07:00,30,up|08:15,45,down|10:30,60,down
?S=a,TIME,DURATION&Mode=MODE
| Parameter | Description | Values |
|---|---|---|
s |
Timer configuration | a = autostart, m = manual |
TIME |
Time in HH:MM format | 09:30, 14:45, etc. |
DURATION |
Duration in minutes | 30, 45, 120, etc. |
mode |
Count direction | up or down |
?segments=TIME,DURATION,MODE|TIME,DURATION,MODE|...
| Component | Description | Example |
|———–|————-|——–|
| TIME | HH:MM format | 09:00, 13:30 |
| DURATION | Minutes | 30, 45, 90 |
| MODE | Count direction | up, down |
| | | Separator between segments | 09:00,30,up|10:30,45,down |
÷
Workout Session Warm-up + Main + Cool-down
timer.html?segments=06:00,15,up|06:15,45,down|07:00,10,up
Work Pomodoro 25min work + 5min break + 25min work + 15min break
timer.html?segments=09:00,25,down|09:25,5,up|09:30,25,down|09:55,15,up
Cooking Schedule Prep + Cook + Rest
timer.html?segments=17:30,20,up|17:50,35,down|18:25,10,up
Study Sessions Morning study blocks
timer.html?segments=08:00,50,down|09:00,10,up|09:10,50,down|10:10,20,up
Count Down Mode (mode=down or default)
s=a,15:00,30 means “end at 3:00 PM after 30 minutes” (starts at 2:30 PM)Count Up Mode (mode=up)
s=a,15:00,30 means “start at 3:00 PM for 30 minutes” (ends at 3:30 PM)timer.html?s=m,00:00,30 # 30 minutes, manual start
timer.html?s=a,14:30,45 # Start at 2:30 PM for 45 minutes
timer.html?segments=10:00,30,up|11:00,45,down|15:30,60,down
If you load a URL after the start time but before the end time, the timer will:
The hamburger menu automatically generates these URLs when you:
This may make it easier than manually constructing URLs - for some.
# Open in floating popup window
timer.html?s=a,14:30,40&mode=down&view=popup
sessiontimer://timer?s=a,14:30,40&mode=down&view=popup
Personalize timer colors to match your workflow preferences:
Examples:
Design rationale: Minutes are more intuitive than percentages and work consistently across different timer durations. A 30-minute session and 2-hour session both benefit from the same “5 minutes remaining” warning, whereas percentage-based thresholds would feel inconsistent.
Customizable alerts when timer segments complete:
Accessibility Benefits: Multiple notification modalities ensure completion awareness regardless of user attention focus, environmental noise, or device settings.
Customizable second hand movement with luxury watch aesthetics:
Technical Implementation: Uses dual second hands with opacity-based transitions and proper state management to achieve smooth, jitter-free animation. The feature automatically resets on timer state changes to prevent any visual artifacts.
Design Philosophy: This experimental feature creates a subtle yet noticeable visual cue at the top of each minute, helping with time awareness during idle periods. The second hand pauses at 12 o’clock, then smoothly continues, creating an elegant mechanical feel reminiscent of luxury timepieces.
timer.html?s=a,10:30,30&mode=down
timer.html?segments=09:00,25,down|09:25,5,up|09:30,25,down|09:55,15,up
timer.html?segments=07:00,10,up|07:10,20,down|07:30,5,up|07:35,20,down|07:55,5,up
timer.html?segments=14:00,45,down|14:50,10,up|15:00,30,down
Session-Timer/
├── timer.html # Original single-file version
├── timer-v2.html # New enhanced version with all v2.0 features
├── index.html # Legacy version with external JSON
├── settings.html # Legacy settings generator
├── settings.json # Fallback JSON configuration
├── manifest.json # PWA manifest for home screen installation
├── sw.js # Service worker for offline functionality
├── src/ # Modular ES6 components
│ ├── eventBus.js # Event system for module communication
│ ├── coreTimer.js # Timer logic, animation, and drawing
│ ├── urlParser.js # URL handling and generation
│ └── calendarExport.js # ICS generation and calendar integration
├── macos-helper/ # Custom URL scheme support
│ ├── build.sh # Build script for helper app
│ ├── SessionTimerHelper/ # Swift source code
│ └── build/ # Compiled .app bundle (after build)
├── ios-shortcuts/ # iOS integration
│ └── SessionTimer-URLHandler.shortcut
├── scripts/ # Command-line automation tools
│ └── generateCalendar.sh # CLI calendar generator with jq/icalBuddy
└── examples/ # Sample configurations for testing
├── pomodoro-session.json
└── focus-session.json
Single File (Current): timer.html remains fully self-contained
Enhanced v2.0: timer-v2.html + supporting files for full feature set
PWA: All files for offline home screen installation
Development: Modular src/ components with build process
This application is particularly suitable for individuals who experience difficulties with temporal cognition and calculation. Research indicates that people with dyscalculia often have impaired number sense and difficulties in estimating or manipulating temporal intervals (Butterworth, 2010). Similarly, those with executive function deficits, such as individuals with ADHD, frequently demonstrate “time-blindness,” defined as impaired awareness of elapsed and future time, which can compromise planning and sustained task engagement (Barkley, 1997; Brown, 2005). For such populations, interpreting analogue clocks or performing time arithmetic can present unnecessary cognitive load, distracting from the primary task. By externalizing time tracking, automating calculations, and presenting progress in an intuitive visual form, this application minimizes distraction and supports task persistence.
References