{"id":29874616,"url":"https://github.com/zeldean/zeltimer","last_synced_at":"2025-07-31T00:43:32.627Z","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-07-26T23:06:58.000Z","size":1403,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-27T02:19:59.978Z","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-07-26T23:07:02.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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267967915,"owners_count":24173595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-07-31T00:43:32.593Z","avatar_url":"https://github.com/Zeldean.png","language":"Python","readme":"# ⏱️ Zeltimer – Terminal Time Tracker\n\nA 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.\n\n---\n\n## 📁 Project Structure\n\n```\n\nzeltimer/\n├── app.py                      # Main CLI entry point (Click-based)\n├── core/                       # Core logic and utilities\n│   ├── timer\\_manager.py        # Timer + session logic and logging\n│   ├── storage.py              # JSON and log file helpers\n│   └── utils.py                # Formatters and notifications\n├── data/\n│   ├── timers.json             # Structured timer \u0026 session history\n│   ├── log.txt                 # Append-only raw log of events\n│   └── log.md                  # Markdown export (optional)\n├── assets/\n│   └── zeltimer\\_icon.png       # Icon for notify-send messages\n\n````\n\n---\n\n## 🚀 Getting Started\n\n### 1. Install dependencies\n\n```bash\npip install -e .\n````\n\nMake sure you have `libnotify` installed for desktop notifications (`notify-send`).\n\n---\n\n### 2. Run the app\n\n```bash\nzeltimer [COMMAND]\n```\n\n---\n\n## ✅ Commands\n\n### `zeltimer new \u003ctitle\u003e`\n\nCreate a new timer with a custom title.\n\n```bash\nzeltimer new \"Study Timer\"\n```\n\n---\n\n### `zeltimer start \u003cid\u003e \u003csession title\u003e [--pomodoro]`\n\nStart a new session.\n\n* If one is already running, it auto-inserts a `Stop`.\n* With `--pomodoro`, starts a Pomodoro-style cycle (see below).\n\n```bash\nzeltimer start 1 \"WPR381 Reading\"\nzeltimer start 1 \"Focused Session\" --pomodoro --cycles 4 --work 25 --break 5\n```\n\n---\n\n### `zeltimer stop \u003cid\u003e`\n\nStops the running session for the given timer.\n\n```bash\nzeltimer stop 1\n```\n\n---\n\n### `zeltimer resume \u003cid\u003e`\n\nResumes the last session title of the given timer.\n\n```bash\nzeltimer resume 1\n```\n\n---\n\n### `zeltimer status [id]`\n\nShow session breakdown for a timer, or all active timers if no ID is given.\n\n```bash\nzeltimer status        # Shows all active timers\nzeltimer status 1      # Shows one timer breakdown\n```\n\nOutput looks like:\n\n```\nTimer 1 - Study Session\n├── MLG382 Recap - 00:04:20\n├── WPR381 - 00:12:17 (running)\n└── Total Time Breakdown:\nTotal Time: 00:16:37\n```\n\n---\n\n## 📦 Data Format\n\n### `log.txt`\n\nAppend-only raw log:\n\n```\n1|2025-06-07T14:00:02|Start|Prep\n1|2025-06-07T15:00:15|Stop\n```\n\n---\n\n### `timers.json`\n\nStructured cache built from log:\n\n```json\n[\n  {\n    \"id\": 1,\n    \"name\": \"Study Timer\",\n    \"sessions\": [\n      {\n        \"title\": \"Prep\",\n        \"start\": \"2025-06-07T14:00:02\",\n        \"stop\": \"2025-06-07T15:00:15\",\n        \"duration_seconds\": 3613\n      }\n    ],\n    \"total_time\": 3613,\n    \"archived\": false\n  }\n]\n```\n\n---\n\n## 🔔 Notifications\n\nZeltimer uses `notify-send` with a custom icon.\n\n### Requirements\n\n* `libnotify`\n* Desktop WM that supports notifications (e.g. Hyprland, GNOME, KDE)\n\n---\n\n## 🧠 Design Principles\n\n* Timers are persistent and can run concurrently\n* Logs are append-only (`log.txt`)\n* `timers.json` is rebuilt from logs on-demand\n* Sessions have optional titles\n* `Start` is always paired with `Stop` (auto if needed)\n\n---\n\n## 🌟 Planned Features\n\n| Feature         | Description                                             | Status     |\n| --------------- | ------------------------------------------------------- | ---------- |\n| Pomodoro mode   | Auto-run start/stop cycles with break notifications     | 🔜 Planned     |\n| `list` command  | Show all timers with active status + time summary       | 🔜 Planned |\n| Session tags    | Add tags to group/filter sessions                       | 🔜 Planned |\n| Markdown export | Save logs as a readable Markdown session report         | 🔜 Planned  |\n| CSV export      | Export all sessions to CSV format                       | 🔜 Planned |\n| Timer rename    | Rename a timer by ID                                    | 🔜 Planned |\n| Archive toggle  | Hide unused timers from status unless explicitly listed | 🔜 Planned     |\n| Curses UI       | Interactive terminal UI for managing timers             | 🔜 Planned |\n\n---\n\n## 🛠 Developer Tips\n\nTest locally with:\n\n```bash\nzeltimer new \"Test\"\nzeltimer start 1 \"Reading\"\nzeltimer stop 1\nzeltimer status 1\n```\n\nTo test Pomodoro:\n\n```bash\nzeltimer start 1 \"Pomodoro\" --pomodoro --cycles 2 --work 1 --break 1\n```\n\n---\n\n## 🧩 Credits\n\nBuilt by **zeldean**\nMIT Licensed\nLogo and icon included in `/assets`\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"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"}