FloatingPomodoro

KO | EN

gitlite — search

#hacktoberfest #rust #deep-learning #linux #docker #macos #nodejs #java #windows #awesome #kubernetes #awesome-list #ios #mcp

FloatingPomodoro

(★ 13)

Pomodoro timer on X11, built with GTK4 with a modern UI and a floating ball

FloatingPomodoro 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Floating Pomodoro

Low-power Pomodoro timer for GTK4 on X11 (Linux). It combines a modern main window, a floating always-visible overlay, tray controls, and an optional focus guard that can warn when you drift off-task.

Platform scope: GTK4 + X11 only. It is not cross-platform and does not support Wayland today. Wayland support or a Qt port may be considered in the distant future.

## Highlights

- Pomodoro timer with focus, short break, long break, pause, skip, and stop
- Task list with repeat cycles, inline editing, and task history
- Automatic task completion and configurable archiving rules
- Floating ball overlay with progress ring, hover details, opacity control, and right-click menu
- StatusNotifierItem (SNI) tray icon with quick actions
- Focus guard: blacklist warnings plus app usage stats
- Optional Chrome + Ollama relevance checks for off-task detection

## Screenshots

![Main window](https://raw.githubusercontent.com/ErrorTzy/FloatingPomodoro/master/docs/screenshots/mainwindow.png)

![Floating overlay](https://raw.githubusercontent.com/ErrorTzy/FloatingPomodoro/master/docs/screenshots/floatingoverlay.png)

## Feature tour

### Timer and task workflow

- Default cycle: 25 min focus, 5 min short break, 15 min long break every 4 focus sessions
- Start/pause/resume/skip/stop from the main window, tray, or overlay
- Timer controls are disabled until an active task exists
- Focus time and completed break count are tracked per run (reset on Stop)

Task behavior:
- Tasks have a "Cycles" count (1-99) that represents how many focus sessions the task needs
- When a focus session ends (the timer switches to a break), the active task is decremented
- When the cycle count reaches zero, the task is marked completed automatically
- Tasks can be set to Active, Pending, or Completed manually via the status button
- Inline edit, archive/restore, and delete actions are available per task

### Task archiving

Archived tasks are kept in a separate window and can be restored later. Archive behavior is configurable:
- After N days (default 3)
- Archive immediately after completion
- Keep latest N completed tasks (default 5)

You can also archive all tasks or delete archived tasks from the Settings window.

### Floating overlay ("floating ball")

An always-visible overlay shows the current timer at a glance:
- Circular progress ring with phase color changes (focus / break / long break)
- Hover to expand and show current and next task
- Opacity slider (0.3 to 1.0, default ~0.65)
- Right-click menu for start/pause, skip, stop, open app, hide, quit
- Draggable by left-click
- Best-effort "always on top", skip taskbar, skip pager hints (X11)

When focus guard warnings trigger, the overlay turns red and displays a warning message. If the overlay was hidden, it is automatically shown.

### Tray integration (SNI)

Uses StatusNotifierItem over D-Bus:
- Left-click (Activate) opens the main window
- Menu actions: Start/Pause/Resume, Skip, Stop, Toggle Floating Ball, Open App, Quit

### Focus guard (blacklist + usage stats)

Focus guard works only during an active focus session with an active task:
- Active window detection via X11 (_NET_ACTIVE_WINDOW + WM_CLASS)
- Blacklist matches are case-insensitive substring checks
- Warnings repeat on a configurable interval (default 1 second)
- Per-task stats are collected during focus sessions
- Global usage stats (optional) track active app usage while the app runs
- Usage stats are shown in the main window (top 5 apps for the current day)
- Click a task row to see per-task usage stats
- Stats are stored in SQLite and pruned after 35 days

### Chrome + Ollama relevance checks (optional)

If built with `-Dchrome_ollama=enabled` (and libsoup/json-glib installed) and Ollama is installed, an additional settings page appears:
- Only runs when Chrome/Chromium is the active app
- Chrome must be launched with a remote debugging port (default 9222)
- Fetches the active tab via CDP and extracts title, URL, and page text (innerText capped at 8000 chars)
- Sends a structured prompt to Ollama and expects one of: "directly relevant", "not sure", "clearly irrelevant"
- Only "clearly irrelevant" triggers warnings
- Relevance checks are rate-limited (every 15 seconds)

The Chrome relevance toggle is disabled until a model is selected from `ollama list`. A refresh button reloads models.

## Settings overview

Timer:
- Focus minutes (1-120)
- Short break minutes (1-30)
- Long break minutes (1-60)
- Long break interval (1-12)

Startup and tray:
- Autostart on login
- Start in tray when autostarting
- Minimize to tray
- Close to tray

Focus guard:
- Warnings on/off
- Global usage stats on/off
- Detection interval (1-60 seconds)
- Blacklist management (manual entry or "Use active app")

Chrome relevance (only when Ollama is available):
- Enable relevance checks
- Select Ollama model
- Refresh model list
- Chrome debug port
- Trafilatura python (optional; set a venv/conda python)

Maintenance:
- Reset settings to defaults
- Archive all tasks
- Delete archived tasks
- Delete usage stats

## System requirements

- Linux with X11 session (tested on Debian XFCE)
- Xfwm4 compositor enabled (for overlay transparency)
- GTK4 (>= 4.8)
- X11 development headers for build

Wayland is not supported today.

## Build

Required dependencies:
- GTK4 development packages
- fontconfig
- sqlite3
- pkg-config
- Meson + Ninja
- X11 development headers

Optional (disabled by default; enables Chrome/Ollama features and the integration test):
- libsoup-3.0
- json-glib
- python3 + `trafilatura` (optional; configure the Python path in Settings if using venv/conda)

Typical Debian packages (may vary by release):
- `libgtk-4-dev`
- `libfontconfig1-dev`
- `libsqlite3-dev`
- `libx11-dev`
- `libsoup-3.0-dev` (optional)
- `libjson-glib-dev` (optional)
- `python3` (optional; trafilatura is typically installed via pip/venv/conda)
- `meson`, `ninja-build`, `pkg-config`

Build commands:

```sh
meson setup build
ninja -C build
```

To enable Chrome/Ollama integration:

```sh
meson setup build -Dchrome_ollama=enabled
```

## Run

```sh
./build/floating-pomodoro
```

Autostart launch (used by the autostart .desktop file):

```sh
./build/floating-pomodoro --autostart
```

## Data locations

All user data is stored under the XDG data dir:
- Settings: `~/.local/share/floating-pomodoro/settings.ini`
- Tasks: `~/.local/share/floating-pomodoro/tasks.ini`
- Usage stats: `~/.local/share/floating-pomodoro/usage_stats.sqlite3`

Bundled fonts are extracted to:
- `~/.cache/floating-pomodoro/fonts/`

Autostart file:
- `~/.config/autostart/floating-pomodoro.desktop`

## Logging and debug

Logging is quiet by default. Set:

```sh
POMODORO_LOG_LEVEL=info ./build/floating-pomodoro
```

Accepted values: `warn` (default), `info`, `debug`.

Fast timer mode for UI testing:

```sh
POMODORO_TEST_TIMER=1 ./build/floating-pomodoro
```

## Chrome and Ollama setup (optional)

1) Ensure Ollama is installed and running. The app detects `ollama` from PATH.
   Optional: install `python3` + `trafilatura` in a venv/conda or system Python.
   If it is not in your system PATH, set the interpreter in Settings → Chrome →
   "Trafilatura python".
2) Pull a model:

```sh
ollama pull llama3
```

3) Start Chrome with remote debugging enabled (default port 9222):

```sh
google-chrome --remote-debugging-port=9222
```

4) Open Settings -> Focus guard -> Chrome relevance:
- Refresh model list
- Select a model
- Enable relevance checks
- (Optional) Set "Trafilatura python" if using a venv/conda interpreter

If Chrome is active during a focus session and the page is clearly irrelevant, the overlay will warn.

## Tests

If built with `-Dchrome_ollama=enabled` and libsoup/json-glib available, an integration test is available:

```sh
meson test -C build
```

The Chrome/Ollama test can be configured with:

```sh
POMODORO_TEST_OLLAMA_MODEL=your-model-name meson test -C build
```

## App ID

`com.scott.Xfce4FloatingPomodoro`

## License

MIT. See `LICENSE`.

FloatingPomodoro

FloatingPomodoro 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

FloatingPomodoro

FloatingPomodoro 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README