Zeltimer is a terminal-based time tracker for managing multiple timers, recording sessions, and keeping your work organized.
It supports session resuming today and will soon feature a full Pomodoro mode for focused work cycles.
First, install the Zel ecosystem:
curl -sSL https://raw.githubusercontent.com/Zeldean/zelutil/main/bootstrap-zel.py | python3This sets up ZelUtil and makes all Zel tools available. See the ZelUtil repository for details.
Part of the Zel-suite of tools:
zeltimer— time trackingzeltask— task tracking (coming soon)zeljournal— exports timers & tasks to Markdown (coming soon)
Zeltimer helps you track how you spend your time — whether it's studying, coding, or working on personal projects — directly from the terminal.
- Multiple concurrent timers
- Persistent logs rebuilt into JSON after every command
- Quick start / stop / resume / list workflows
- Filterable status reports (per timer, per day, or custom range)
- Desktop notifications with the packaged icon (Linux
notify-send) - Pomodoro mode (planned feature)
git clone https://github.com/Zeldean/zeltimer.git
cd zeltimer
pip install -e .pipx install git+https://github.com/Zeldean/zeltimer.gitRequirements:
- Python 3.10+
- click
- Linux desktop with
notify-sendfor notifications
General syntax:
zeltimer [COMMAND] [ARGS]| Command | Description |
|---|---|
new <name> |
Create a new timer |
start <id> [session name] |
Start a timer (auto-stops active session on same timer) |
stop <id> |
Stop the current session |
resume <id> |
Resume the last session |
status [id] |
Show session breakdown for one or all timers (filterable) |
ls |
List active timers |
status accepts --date, --from-date, --to-date, --all-days, and
--refresh to control the window of sessions that are summarised.
# Create a new timer
zeltimer new "Study Session"
# Start it with a session name
zeltimer start 1 "Math Homework"
# Stop the timer
zeltimer stop 1
# Check status
zeltimer status 1✅ Multiple timers with separate sessions
✅ Auto-stop on new session start for same timer
✅ Persistent storage in ~/.local/state/zel
✅ Resume support for previous sessions
✅ Fast active timer list via zeltimer ls
📢 Desktop notifications (requires notify-send on Linux)
🔄 Pomodoro cycles (planned)
- Pomodoro mode: Per-timer configuration for cycles, work time, break time.
- Archive/unarchive timers directly from the CLI.
- TUI frontend.
- Full integration with
zeljournal.
Your data is stored in the XDG state directory:
~/.local/state/zel/
All files are created with zelutil.resolve_state_dir() so every Zel tool shares
the same base directory.
timers.json— rebuilt timer list with session historytimer_log.txt— append-only event log used to rebuild state
You can back up or sync these files if needed.
zeltask— terminal-based task tracker (coming soon)zeljournal— exports timers & tasks to Markdown (coming soon)
This project is licensed under the MIT License.