A simple yet powerful CLI tool for tracking multiple timers and recording session data. Designed for time tracking in study blocks, work sessions, meetings, or projects — right from your terminal.
zeltimer/
├── app.py # Main CLI entry point (Click-based)
├── core/ # Core logic and utilities
│ ├── timer\_manager.py # Timer + session logic and logging
│ ├── storage.py # JSON and log file helpers
│ └── utils.py # Formatters and notifications
├── data/
│ ├── timers.json # Structured timer & session history
│ ├── log.txt # Append-only raw log of events
│ └── log.md # Markdown export (optional)
├── assets/
│ └── zeltimer\_icon.png # Icon for notify-send messages
pip install -e .Make sure you have libnotify installed for desktop notifications (notify-send).
zeltimer [COMMAND]Create a new timer with a custom title.
zeltimer new "Study Timer"Start a new session.
- If one is already running, it auto-inserts a
Stop. - With
--pomodoro, starts a Pomodoro-style cycle (see below).
zeltimer start 1 "WPR381 Reading"
zeltimer start 1 "Focused Session" --pomodoro --cycles 4 --work 25 --break 5Stops the running session for the given timer.
zeltimer stop 1Resumes the last session title of the given timer.
zeltimer resume 1Show session breakdown for a timer, or all active timers if no ID is given.
zeltimer status # Shows all active timers
zeltimer status 1 # Shows one timer breakdownOutput looks like:
Timer 1 - Study Session
├── MLG382 Recap - 00:04:20
├── WPR381 - 00:12:17 (running)
└── Total Time Breakdown:
Total Time: 00:16:37
Append-only raw log:
1|2025-06-07T14:00:02|Start|Prep
1|2025-06-07T15:00:15|Stop
Structured cache built from log:
[
{
"id": 1,
"name": "Study Timer",
"sessions": [
{
"title": "Prep",
"start": "2025-06-07T14:00:02",
"stop": "2025-06-07T15:00:15",
"duration_seconds": 3613
}
],
"total_time": 3613,
"archived": false
}
]Zeltimer uses notify-send with a custom icon.
libnotify- Desktop WM that supports notifications (e.g. Hyprland, GNOME, KDE)
- Timers are persistent and can run concurrently
- Logs are append-only (
log.txt) timers.jsonis rebuilt from logs on-demand- Sessions have optional titles
Startis always paired withStop(auto if needed)
| Feature | Description | Status |
|---|---|---|
| Pomodoro mode | Auto-run start/stop cycles with break notifications | 🔜 Planned |
list command |
Show all timers with active status + time summary | 🔜 Planned |
| Session tags | Add tags to group/filter sessions | 🔜 Planned |
| Markdown export | Save logs as a readable Markdown session report | 🔜 Planned |
| CSV export | Export all sessions to CSV format | 🔜 Planned |
| Timer rename | Rename a timer by ID | 🔜 Planned |
| Archive toggle | Hide unused timers from status unless explicitly listed | 🔜 Planned |
| Curses UI | Interactive terminal UI for managing timers | 🔜 Planned |
Test locally with:
zeltimer new "Test"
zeltimer start 1 "Reading"
zeltimer stop 1
zeltimer status 1To test Pomodoro:
zeltimer start 1 "Pomodoro" --pomodoro --cycles 2 --work 1 --break 1Built by zeldean
MIT Licensed
Logo and icon included in /assets