Task Timer - GNOME Shell Extension

A GNOME Shell extension for planning your work day by timing your tasks.

Features

• Timed Tasks: Create tasks with planned durations and track time spent
• Checklists: Create checkbox-based task lists for simple to-dos
• Temporary Tasks: Quick tasks with optional timers that can be deleted
• Exclusive Timers: Only one timer runs at a time (auto-stops others)
• Persistent State: Tasks survive logout/login and system restarts
• Weekly Planning: Track time spent per weekday for recurring tasks
• Notifications: Get notified when task time is reached
• Scrollable List: Native scrolling for task lists with 10+ items

Installation

1. Copy the extension folder to your GNOME extensions directory:

   cp -r TaskTimer@rothirsch.tech ~/.local/share/gnome-shell/extensions/

2. Restart GNOME Shell:

   • Press Alt+F2, type r, press Enter (X11)
   • Or log out and back in (Wayland)

3. Enable the extension:

   gnome-extensions enable TaskTimer@rothirsch.tech

Compatibility

• GNOME Shell 45, 46

Architecture

See the architecture diagram.

TaskTimer@rothirsch.tech/
├── extension.js              # Entry point - enables/disables extension
├── metadata.json             # Extension metadata
├── stylesheet.css            # UI styling
├── docs/
│   └── architecture.drawio   # Architecture diagram
└── classes/
    ├── core/
    │   ├── constants.js      # UI, TIME, KEYS, COLORS constants
    │   └── state_manager.js  # Persistent state (atomic writes, backup recovery)
    ├── base/
    │   ├── base_item.js      # Base class for all task item types
    │   └── base_settings.js  # Base class for all settings panels
    ├── ui/
    │   └── navigation.js     # ScrollView-based task list navigation
    ├── task_timer.js         # Main panel button and task orchestration
    ├── task_item.js          # Timed task item (extends BaseItem)
    ├── checkbox_item.js      # Checklist item (extends BaseItem)
    ├── temporary_item.js     # Temporary task item (extends BaseItem)
    ├── task_settings.js      # Settings for timed tasks (extends BaseSettings)
    ├── checkbox_settings.js  # Settings for checklists (extends BaseSettings)
    ├── temporary_settings.js # Settings for temporary tasks (extends BaseSettings)
    ├── timer_notification.js # Desktop notifications
    └── utils.js              # Time formatting, color generation

Class Hierarchy

Item Classes

All item classes extend BaseItem (PopupMenu.PopupBaseMenuItem):

Class	Purpose	Features
TaskItem	Timed tasks	Play/pause, progress bar, time tracking
CheckboxItem	Checklists	Multiple checkboxes, completion tracking
TemporaryItem	Quick tasks	Optional timer, auto-delete option

Settings Classes

All settings classes extend BaseSettings (PopupMenu.PopupMenuSection):

Class	Purpose	Features
TaskSettings	Task configuration	Time sliders, round-up, weekly table
CheckboxSettings	Checklist config	Description, link, color
TemporarySettings	Temporary config	Name, timer toggle, planned time

Core Classes

Class	Purpose
TaskTimer	Main panel button, task list management
StateManager	JSON state persistence with atomic writes
NavigationController	St.ScrollView wrapper for scrollable list

Signals

Items emit these signals to communicate with TaskTimer:

Signal	Description
delete_signal	Task should be deleted
moveUp_signal	Move task up in list
moveDown_signal	Move task down in list
update_signal	Task data changed, save state
settings_signal	Open settings panel
closeSettings_signal	Close settings panel
timer_started	Timer started (triggers exclusive timer)

State Persistence

Tasks are saved to ~/.config/task-timer-state/state.json:

• Atomic writes: Write to temp file, then move (prevents corruption)
• Backup recovery: Automatically recovers from .backup if main file corrupted
• Auto-save: Every 15 seconds while running
• Shutdown save: Saves on GNOME Shell shutdown

Configuration

Edit classes/core/constants.js to customize:

export const UI = {
    VISIBLE_TASKS: 10,      // Tasks visible before scrolling
    PROGRESS_LEN: 400,      // Progress bar width (px)
};

export const TIME = {
    SNOOZE_SECONDS: 300,    // Notification snooze (5 min)
    AUTOSAVE_INTERVAL: 15,  // Auto-save interval (seconds)
};

Development

Debugging

Watch GNOME Shell logs:

journalctl -f -o cat /usr/bin/gnome-shell

Testing

Run nested GNOME Shell:

dbus-run-session -- gnome-shell --nested --wayland

Reload Extension

gnome-extensions disable TaskTimer@rothirsch.tech
gnome-extensions enable TaskTimer@rothirsch.tech

Troubleshooting

Extension not showing

1. Check if enabled: gnome-extensions list --enabled
2. Check for errors: journalctl -f -o cat /usr/bin/gnome-shell
3. Verify GNOME version matches metadata.json

Tasks not saving

1. Check directory exists: ls ~/.config/task-timer-state/
2. Check file permissions
3. Look for backup file: ls ~/.config/task-timer-state/*.backup

Timer issues

• Only one timer runs at a time (exclusive timer feature)
• Timers pause on screen lock (configurable in code)

License

See LICENSE file.