Vahid Code Break

Gentle reminders to rest your eyes and get out of your chair while you work in VS Code.

• Eye break every 20 minutes: look at something far away for 20 seconds.
• Movement break every 60 minutes: stand up and move around.

Timers start automatically when VS Code starts. Reminders are ordinary VS Code notifications, mirrored as a desktop notification of the operating system so you also see them in another application; nothing blocks the editor or opens a window.

Using it

Each reminder offers three actions:

When the break is over, an alarm sound and a short status bar message tell you to come back: 20 seconds after an eye reminder and 5 minutes after a movement reminder by default. Answering the reminder with any of the three actions cancels that alarm.

If you ignore a reminder, the next one of the same kind does not stack a second notification; it shows briefly in the status bar instead.

Desktop notifications

Each reminder, and the end of each break, also appears as a notification of the operating system. reminders.systemNotification controls when: always (default), unfocused (only while VS Code is not the focused application) or off. The desktop notification has no buttons; answer the reminder in VS Code.

Run Eye Care: Test System Notification to see one right away.

The status bar shows the time to the next breaks, for example 👀 12m 🚶 42m, or ⏸ Paused 14m while paused. Click it for a menu with pause/resume, reset, status and settings.

Commands

All commands are in the Command Palette under Eye Care:

A pause applies to both reminders. Countdowns freeze while paused and continue from where they stopped. A timed pause ends on its own, and the pause survives a window reload or restart.

Screen lock

Locking the screen stops the countdowns in every window, and the status bar shows 💤 Away. They continue once the screen is unlocked and a VS Code window has focus again, not at the unlock itself. An absence at least as long as a reminder's break counts as that break taken, so its countdown starts over: any lock of 20 seconds or more restarts the eye countdown, 5 minutes or more the movement one (with the default break lengths). A shorter lock continues from where it stopped. A break-end alarm still pending when the screen locks is dropped.

The lock is read from GNOME's screensaver signal (gdbus), or from systemd-logind's LockedHint (loginctl, polled every five seconds) where that signal is missing. On macOS, Windows, or a Linux desktop that reports neither, the countdowns keep running while locked. Turn it off with reminders.pauseWhenLocked.

Multiple windows and profiles

All VS Code windows on the machine share one schedule, including windows in different profiles or started with a different --user-data-dir. The schedule and the pause state are stored in ~/.vahid-code-break/.

• Every window shows the same countdown.
• Each reminder appears once: in the focused window, or in one of the open windows if none has focus.
• Pause, resume, reset, Done and Remind me later in any window apply to all of them, within about two seconds.
• Closing a window does not interrupt the countdown.

Settings are still per profile. A profile with a reminder disabled never shows it. If profiles use different intervals, each new cycle uses the interval of the window that showed the reminder, so keep them the same.

Settings

Ten sounds are bundled: Chime, Ding, Glass, Success, Alert, Knock, Pop, Bubble, Marimba and Doorbell. In the Settings editor, each sound setting has ▶ links that play a sound when clicked, and the last setting has a link that resets everything to defaults.

Each message list is edited in the Settings editor with Add Item, or in settings.json as an array of strings. The same message is never shown twice in a row. Blank lines are ignored, and an empty list brings back the defaults.

Changes apply immediately. When an interval changes, time already elapsed in the current cycle is kept (20 → 30 minutes with 12 minutes elapsed leaves 18 minutes).

With work hours on, nothing counts down outside the window and the status bar shows 🌙 Off until 09:00. A reminder that would have fallen due after the end is dropped, not shown the next morning; the countdown starts fresh when the window opens. The start is inclusive and the end exclusive.

Intervals must be between 1 and 1440 minutes. Zero, negative and non-numeric values fall back to the default; larger values are capped at 1440.

Limitations

• Sound is best effort. VS Code has no audio API for extensions, so the extension plays its bundled WAV files through a system player (afplay on macOS, PowerShell on Windows, paplay, pw-play or aplay on Linux). If none is available, reminders are silent. Windows ignores the volume setting.
• Desktop notifications are best effort too: notify-send on Linux, osascript on macOS, a PowerShell toast on Windows. If the tool is missing, only the VS Code notification appears. Some Linux desktops (GNOME) ignore the on-screen time; 0 still keeps the notification until dismissed.

Development

Requirements: Node.js 20.4 or newer, VS Code 1.85 or newer.

npm install
npm run compile

Run in the Extension Development Host

1. Open this folder in VS Code.
2. Press F5 (or Run and Debug → Run Extension). This compiles the project and opens a second VS Code window with the extension loaded.
3. In that window, check the status bar countdown and run Eye Care: Show Status from the Command Palette.

To see a reminder quickly, set eyeCare.interval to 1 in the development window's settings. Use npm run watch to recompile on save, then Developer: Reload Window in the development window.

Tests

npm test

Tests use Node's built-in test runner with fake timers and cover TimerManager, PauseService, SharedStore, settings validation, and ReminderManager across several simulated windows. They do not need VS Code.

Package and install locally

npx @vscode/vsce package          # or, without vsce: python3 scripts/build-vsix.py
code --install-extension vahid-code-break-1.8.0.vsix

Architecture

src/
├── extension.ts               activation: builds and wires the services
├── constants.ts               command ids and defaults
├── sounds.ts                  catalog of bundled sounds
├── managers/
│   ├── TimerManager.ts        one countdown; the only place timers are created
│   └── ReminderManager.ts     one TimerManager per reminder, aligned with the shared schedule
├── services/
│   ├── ConfigurationService.ts  reads, validates and watches settings
│   ├── NotificationService.ts   VS Code notifications, mirrored to the desktop
│   ├── LockMonitor.ts           screen lock state (GNOME signal, logind fallback)
│   ├── PauseService.ts          global pause, persisted, auto-resume
│   ├── SharedStore.ts           state shared by all windows (~/.vahid-code-break)
│   ├── SoundService.ts          plays the bundled sounds
│   ├── StatusBarService.ts      status bar countdown
│   └── SystemNotificationService.ts  desktop notifications of the operating system
├── commands/commands.ts       Command Palette commands and menus
├── utils/validation.ts        setting validation and duration formatting
├── utils/workHours.ts         the daily working window
├── types/index.ts
└── test/                      unit tests

• TimerManager does not import vscode. It reports through onTick and onComplete callbacks and tracks remaining time against a wall-clock deadline, so the countdown stays correct after system sleep.
• The eye and movement reminders each have their own TimerManager. PauseService uses a third, non-repeating one for auto-resume.
• SharedStore keeps each reminder's due time and the pause state as small JSON files and polls them every two seconds. There is no leader window: every window counts down to the same due time.
• ReminderManager.sync() is idempotent: on any settings, pause or shared-state change it brings each timer to the required state. When a reminder is due, the focused window claims it at once with an exclusive file create; unfocused windows try 1.5 seconds later, so exactly one window shows it.
• Everything that holds a timer, listener or UI element is registered in context.subscriptions and disposed on deactivation.

License

MIT