https://github.com/zeldean/zeltimer
⏱️ A terminal-based time tracking tool with Pomodoro support, session logging, and Markdown exports — designed for flexible CLI workflows or future TUI integration.
https://github.com/zeldean/zeltimer
cli logging markdown pomodoro-timer productivity python study-tool terminal time-tracker timer tui
Last synced: about 1 month ago
JSON representation
⏱️ A terminal-based time tracking tool with Pomodoro support, session logging, and Markdown exports — designed for flexible CLI workflows or future TUI integration.
- Host: GitHub
- URL: https://github.com/zeldean/zeltimer
- Owner: Zeldean
- License: mit
- Created: 2025-06-15T16:30:59.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-04T21:12:07.000Z (7 months ago)
- Last Synced: 2025-11-07T22:14:31.259Z (7 months ago)
- Topics: cli, logging, markdown, pomodoro-timer, productivity, python, study-tool, terminal, time-tracker, timer, tui
- Language: Python
- Homepage:
- Size: 1.35 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ⏱️ Zeltimer
**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.
## Getting Started
**First, install the Zel ecosystem:**
```bash
curl -sSL https://raw.githubusercontent.com/Zeldean/zelutil/main/bootstrap-zel.py | python3
```
This sets up ZelUtil and makes all Zel tools available. See the [ZelUtil repository](https://github.com/Zeldean/zelutil) for details.
Part of the **Zel-suite** of tools:
- [`zeltimer`](https://github.com/Zeldean/zeltimer) — time tracking
- `zeltask` — task tracking *(coming soon)*
- `zeljournal` — exports timers & tasks to Markdown *(coming soon)*
---
## 🚀 Overview
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)*
---
## 📦 Installation
### From source
```bash
git clone https://github.com/Zeldean/zeltimer.git
cd zeltimer
pip install -e .
````
### With `pipx` (recommended for CLI tools)
```bash
pipx install git+https://github.com/Zeldean/zeltimer.git
```
**Requirements**:
* Python 3.10+
* [click](https://pypi.org/project/click/)
* Linux desktop with `notify-send` for notifications
---
## 💻 Usage
General syntax:
```bash
zeltimer [COMMAND] [ARGS]
```
### Commands
| Command | Description |
| --------------------------- | ------------------------------------------------------- |
| `new ` | Create a new timer |
| `start [session name]` | Start a timer (auto-stops active session on same timer) |
| `stop ` | Stop the current session |
| `resume ` | 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.
### Example session
```bash
# 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
```
---
## ✨ Features
✅ 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)*
---
## 🛠 Planned Features
* **Pomodoro mode**: Per-timer configuration for cycles, work time, break time.
* Archive/unarchive timers directly from the CLI.
* TUI frontend.
* Full integration with `zeljournal`.
---
## 📂 Data Storage
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 history
* `timer_log.txt` — append-only event log used to rebuild state
You can back up or sync these files if needed.
---
## 🤝 Related Projects
* `zeltask` — terminal-based task tracker *(coming soon)*
* `zeljournal` — exports timers & tasks to Markdown *(coming soon)*
---
## 📄 License
This project is licensed under the [MIT License](LICENSE).