Files

m3tm3re 44485c4c72 docs: update zellij-ps to reflect project switcher functionality

- Update package description and fix mainProgram typo
- Rewrite documentation to describe project switching, not process viewing
- Add PROJECT_FOLDERS configuration and usage examples
- Update all references across docs (README, guides, module overviews)

2025-12-30 15:42:52 +01:00

3.9 KiB

Raw Blame History

pomodoro-timer

A work timer based on the Pomodoro Technique.

Description

A simple, shell-based Pomodoro timer that uses timer, Kitty terminal, Rofi, libnotify, and speech synthesis to provide visual and audio feedback for work and break sessions.

Features

⏱️ Pomodoro Technique: 45-minute work, 10-minute break cycles
🎨 Terminal UI: Floating Kitty terminal window
📋 Rofi Menu: Easy session selection
🔔 Notifications: Desktop and voice notifications
⚙️ Custom Times: Set custom durations
🎯 Quick Access: Simple keybinding integration

Installation

Via Overlay

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    launch-timer  # The main program is named launch-timer
  ];
}

Direct Reference

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.launch-timer
  ];
}

Run Directly

nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#launch-timer

Usage

Basic Usage

# Launch timer selection menu
launch-timer

This opens a Rofi menu with three options:

work - 45-minute work session
break - 10-minute break session
custom - Custom time duration

Session Options

Work Session

# Select "work" from menu
# Starts 45-minute timer

Break Session

# Select "break" from menu
# Starts 10-minute timer

Custom Time

# Select "custom" from menu
# Enter time in format: 25m, 1h, 30s

# Examples:
# 25m  - 25 minutes
# 1h   - 1 hour
# 30s  - 30 seconds

Time Formats

Supported formats:

Format	Example	Description
`Xm`	`25m`	X minutes
`Xh`	`1h`	X hours
`Xs`	`30s`	X seconds

Configuration

Keybinding Integration

Add to Hyprland config:

{pkgs, ...}: {
  wayland.windowManager.hyprland.settings = {
    bind = [
      # Launch Pomodoro timer with SUPER + T
      "SUPER, T, exec, ${pkgs.launch-timer}/bin/launch-timer"
    ];
  };
}

Custom Defaults

Modify the script for custom defaults:

# Change work duration
start_timer "60m" "work"

# Change break duration
start_timer "15m" "break"

Requirements

Dependencies

timer - Terminal timer utility
kitty - Terminal emulator
rofi - Application launcher
libnotify - Desktop notifications
speechd - Text-to-speech synthesis

System Requirements

Linux (primary)
Desktop environment with notification support
Audio output for speech synthesis

Platform Support

Linux (primary)
macOS (not supported)
Windows (not supported)

Behavior

Timer Window

Opens as floating Kitty window
Window class: floating-pomodoro
Window title: floating-pomodoro

Notifications

When session ends, you'll receive:

Desktop notification: "work session ended!" or "break session ended!"
Voice announcement: "work session ended" or "break session ended"

Input Validation

For custom times:

Valid: 25m, 1h, 30s, 1h30m
Invalid: 25, abc, 1.5h

Build Information

Version: 0.1.0
Type: Shell script
License: MIT
Main Program: launch-timer

Troubleshooting

Kitty Not Found

Ensure Kitty is installed:

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    kitty
  ];
}

No Notifications

Ensure notification daemon is running:

# Check for notification daemon
ps aux | grep -i notify

# Start notification daemon
# Depends on your DE: dunst, mako, etc.

Speech Not Working

Check if speech synthesis is working:

# Test speech
spd-say "Hello"

# Check if speech-dispatcher is running
ps aux | grep speech-dispatcher

Adding Packages - How to add new packages
Quick Start - Getting started guide

3.9 KiB Raw Blame History