{"id":29874616,"url":"https://github.com/zeldean/zeltimer","last_synced_at":"2026-05-06T10:31:27.915Z","repository":{"id":304237245,"uuid":"1002516051","full_name":"Zeldean/zeltimer","owner":"Zeldean","description":"⏱️ A terminal-based time tracking tool with Pomodoro support, session logging, and Markdown exports — designed for flexible CLI workflows or future TUI integration.","archived":false,"fork":false,"pushed_at":"2025-11-04T21:12:07.000Z","size":1415,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T22:14:31.259Z","etag":null,"topics":["cli","logging","markdown","pomodoro-timer","productivity","python","study-tool","terminal","time-tracker","timer","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zeldean.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T16:30:59.000Z","updated_at":"2025-11-04T21:12:11.000Z","dependencies_parsed_at":"2025-07-11T21:26:14.200Z","dependency_job_id":"0f36cf84-3f4b-47f2-b97d-1ae6aac34dfe","html_url":"https://github.com/Zeldean/zeltimer","commit_stats":null,"previous_names":["zeldean/zeltimer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Zeldean/zeltimer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeldean%2Fzeltimer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeldean%2Fzeltimer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeldean%2Fzeltimer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeldean%2Fzeltimer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zeldean","download_url":"https://codeload.github.com/Zeldean/zeltimer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeldean%2Fzeltimer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32689066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","logging","markdown","pomodoro-timer","productivity","python","study-tool","terminal","time-tracker","timer","tui"],"created_at":"2025-07-31T00:43:28.043Z","updated_at":"2026-05-06T10:31:27.910Z","avatar_url":"https://github.com/Zeldean.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⏱️ Zeltimer\n\n![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n![Last Commit](https://img.shields.io/github/last-commit/Zeldean/zeltimer)\n![Issues](https://img.shields.io/github/issues/Zeldean/zeltimer)\n![Repo Size](https://img.shields.io/github/repo-size/Zeldean/zeltimer)\n\n**Zeltimer** is a terminal-based time tracker for managing multiple timers, recording sessions, and keeping your work organized.  \nIt supports session resuming today and will soon feature a full **Pomodoro mode** for focused work cycles.\n\n## Getting Started\n\n**First, install the Zel ecosystem:**\n```bash\ncurl -sSL https://raw.githubusercontent.com/Zeldean/zelutil/main/bootstrap-zel.py | python3\n```\n\nThis sets up ZelUtil and makes all Zel tools available. See the [ZelUtil repository](https://github.com/Zeldean/zelutil) for details.\n\nPart of the **Zel-suite** of tools:\n- [`zeltimer`](https://github.com/Zeldean/zeltimer) — time tracking\n- `zeltask` — task tracking *(coming soon)*\n- `zeljournal` — exports timers \u0026 tasks to Markdown *(coming soon)*\n\n---\n\n## 🚀 Overview\n\nZeltimer helps you track how you spend your time — whether it's studying, coding, or working on personal projects — directly from the terminal.\n\n- **Multiple concurrent timers**  \n- **Persistent logs** rebuilt into JSON after every command  \n- **Quick start / stop / resume / list** workflows  \n- **Filterable status reports** (per timer, per day, or custom range)  \n- **Desktop notifications** with the packaged icon (Linux `notify-send`)  \n- **Pomodoro mode** *(planned feature)*  \n\n---\n\n## 📦 Installation\n\n### From source\n```bash\ngit clone https://github.com/Zeldean/zeltimer.git\ncd zeltimer\npip install -e .\n````\n\n### With `pipx` (recommended for CLI tools)\n\n```bash\npipx install git+https://github.com/Zeldean/zeltimer.git\n```\n\n**Requirements**:\n\n* Python 3.10+\n* [click](https://pypi.org/project/click/)\n* Linux desktop with `notify-send` for notifications\n\n---\n\n## 💻 Usage\n\nGeneral syntax:\n\n```bash\nzeltimer [COMMAND] [ARGS]\n```\n\n### Commands\n\n| Command                     | Description                                             |\n| --------------------------- | ------------------------------------------------------- |\n| `new \u003cname\u003e`                | Create a new timer                                      |\n| `start \u003cid\u003e [session name]` | Start a timer (auto-stops active session on same timer) |\n| `stop \u003cid\u003e`                 | Stop the current session                                |\n| `resume \u003cid\u003e`               | Resume the last session                                 |\n| `status [id]`               | Show session breakdown for one or all timers (filterable) |\n| `ls`                        | List active timers                                      |\n\n`status` accepts `--date`, `--from-date`, `--to-date`, `--all-days`, and\n`--refresh` to control the window of sessions that are summarised.\n\n### Example session\n\n```bash\n# Create a new timer\nzeltimer new \"Study Session\"\n\n# Start it with a session name\nzeltimer start 1 \"Math Homework\"\n\n# Stop the timer\nzeltimer stop 1\n\n# Check status\nzeltimer status 1\n```\n\n---\n\n## ✨ Features\n\n✅ Multiple timers with separate sessions\n✅ Auto-stop on new session start for same timer\n✅ Persistent storage in `~/.local/state/zel`\n✅ Resume support for previous sessions\n✅ Fast active timer list via `zeltimer ls`\n📢 Desktop notifications (requires `notify-send` on Linux)\n🔄 Pomodoro cycles *(planned)*\n\n---\n\n## 🛠 Planned Features\n\n* **Pomodoro mode**: Per-timer configuration for cycles, work time, break time.\n* Archive/unarchive timers directly from the CLI.\n* TUI frontend.\n* Full integration with `zeljournal`.\n\n---\n\n## 📂 Data Storage\n\nYour data is stored in the XDG state directory:\n\n```\n~/.local/state/zel/\n```\n\nAll files are created with `zelutil.resolve_state_dir()` so every Zel tool shares\nthe same base directory.\n\n* `timers.json` — rebuilt timer list with session history\n* `timer_log.txt` — append-only event log used to rebuild state\n\nYou can back up or sync these files if needed.\n\n---\n\n## 🤝 Related Projects\n\n* `zeltask` — terminal-based task tracker *(coming soon)*\n* `zeljournal` — exports timers \u0026 tasks to Markdown *(coming soon)*\n\n---\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeldean%2Fzeltimer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeldean%2Fzeltimer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeldean%2Fzeltimer/lists"}