{"id":13475299,"url":"https://github.com/dhth/hours","last_synced_at":"2025-04-05T07:01:48.825Z","repository":{"id":244388764,"uuid":"812644610","full_name":"dhth/hours","owner":"dhth","description":"A no-frills time tracking toolkit for command line nerds","archived":false,"fork":false,"pushed_at":"2025-03-23T22:34:38.000Z","size":224,"stargazers_count":150,"open_issues_count":10,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-29T06:01:37.137Z","etag":null,"topics":["time-tracker","time-tracking","tui"],"latest_commit_sha":null,"homepage":"https://tools.dhruvs.space/hours","language":"Go","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/dhth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-06-09T13:33:49.000Z","updated_at":"2025-03-23T22:34:41.000Z","dependencies_parsed_at":"2024-08-05T18:09:01.583Z","dependency_job_id":"944ecc3f-dd01-4f16-9da2-465d21e9925f","html_url":"https://github.com/dhth/hours","commit_stats":null,"previous_names":["dhth/hours"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fhours","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fhours/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fhours/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhth%2Fhours/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhth","download_url":"https://codeload.github.com/dhth/hours/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299828,"owners_count":20916190,"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","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":["time-tracker","time-tracking","tui"],"created_at":"2024-07-31T16:01:19.181Z","updated_at":"2025-04-05T07:01:48.602Z","avatar_url":"https://github.com/dhth.png","language":"Go","funding_links":[],"categories":["Go","\u003ca name=\"time-tracker\"\u003e\u003c/a\u003eTime trackers","Applications"],"sub_categories":["Productivity and Organization"],"readme":"# hours\n\n[![Build Workflow Status](https://img.shields.io/github/actions/workflow/status/dhth/hours/build.yml?style=flat-square)](https://github.com/dhth/hours/actions/workflows/build.yml)\n[![Vulncheck Workflow Status](https://img.shields.io/github/actions/workflow/status/dhth/hours/vulncheck.yml?style=flat-square\u0026label=vulncheck)](https://github.com/dhth/hours/actions/workflows/vulncheck.yml)\n[![Latest Release](https://img.shields.io/github/release/dhth/hours.svg?style=flat-square)](https://github.com/dhth/hours/releases/latest)\n[![Commits Since Latest Release](https://img.shields.io/github/commits-since/dhth/hours/latest?style=flat-square)](https://github.com/dhth/hours/releases)\n\n`hours` is a no-frills time tracking toolkit for the command line.\n\nIt's designed for users who want basic time tracking for their tasks/projects\nright in the terminal. With a simple and minimalistic UI, almost everything in\n`hours` can be achieved with one or two keypresses. It can also generate\nplaintext reports, summary statistics, and logs based on time tracked.\n\n![Usage](https://tools.dhruvs.space/images/hours/hours.gif)\n\n[Link to Video][2]\n\n🤔 Motivation\n---\n\nFor a while, I've been wanting to keep track of time I spend on side projects\nand other non-day-job activities. I also wanted to be able to generate plain\ntext reports to get an overview of time allocation. All of this needed to be\ndone via a fast command line tool that prioritised ease of use over\nfancy-but-ultimately-not-so-useful features. I couldn't find a tool that\nprecisely fit these needs, so I decided to build one for myself.\n\n💾 Install\n---\n\n**homebrew**:\n\n```sh\nbrew install dhth/tap/hours\n```\n\n**go**:\n\n```sh\ngo install github.com/dhth/hours@latest\n```\n\nOr get the binaries directly from a\n[release](https://github.com/dhth/hours/releases).\n\n⚡️ Usage\n---\n\n\u003e Newbie tip: If you want to see how `hours` works without having to track time,\n\u003e you can have it generate dummy data for you. See [here](#generate-dummy-data)\n\u003e for more details.\n\n### TUI\n\nOpen the TUI by simply running `hours`. The TUI lets you do the following:\n\n- create/update tasks\n- start/stop tracking time on a task\n- add manual task log entries\n- edit task logs\n- view task log details\n- deactivate/activate a task\n- view historical task log entries\n\n![Usage](https://github.com/user-attachments/assets/16e34df0-fab3-42d9-a183-c8a07af06cca)\n\n![Usage](https://github.com/user-attachments/assets/1213b61b-498a-4840-9ba3-f17097801b9d)\n\n![Usage](https://github.com/user-attachments/assets/d804cc05-53d0-4740-ac53-6f8bf636be6c)\n\nBesides a TUI, `hours` also offers reports, statistics, and logs based on the\ntime tracking you do. These can be viewed using the subcommands `report`,\n`stats`, and `log` respectively.\n\n### Reports\n\n```bash\nhours report [flags] [arg]\n```\n\nOutput a report based on task log entries.\n\nReports show time spent on tasks per day in the time period you specify. These\ncan also be aggregated (using `-a`) to consolidate all task entries and show the\ncumulative time spent on each task per day.\n\nAccepts an argument, which can be one of the following:\n\n    today:     for today's report\n    yest:      for yesterday's report\n    3d:        for a report on the last 3 days (default)\n    week:      for a report on the current week\n    date:      for a report for a specific date (eg. \"2024/06/08\")\n    range:     for a report for a date range (eg. \"2024/06/08...2024/06/12\")\n\n*Note: If a task log continues past midnight in your local timezone, it will be\nreported on the day it ends.*\n\n![Usage](https://tools.dhruvs.space/images/hours/report-1.png)\n\nReports can also be viewed via an interactive interface using the\n`--interactive`/`-i` flag.\n\n![Usage](https://tools.dhruvs.space/images/hours/report-interactive-1.gif)\n\n### Log\n\n```bash\nhours log [flags] [arg]\n```\n\nOutput task log entries.\n\nAccepts an argument, which can be one of the following:\n\n    today:     for log entries from today (default)\n    yest:      for log entries from yesterday\n    3d:        for log entries from the last 3 days\n    week:      for log entries from the current week\n    date:      for log entries from a specific date (eg. \"2024/06/08\")\n    range:     for log entries from a specific date range (eg. \"2024/06/08...2024/06/12\")\n\n*Note: If a task log continues past midnight in your local timezone, it'll\nappear in the log for the day it ends.*\n\n![Usage](https://tools.dhruvs.space/images/hours/log-1.png)\n\nLogs can also be viewed via an interactive interface using the\n`--interactive`/`-i` flag.\n\n![Usage](https://tools.dhruvs.space/images/hours/log-interactive-1.gif)\n\n\n### Statistics\n\n```bash\nhours stats [flag] [arg]\n```\n\nOutput statistics for tracked time.\n\nAccepts an argument, which can be one of the following:\n\n    today:     show stats for today\n    yest:      show stats for yesterday\n    3d:        show stats for the last 3 days (default)\n    week:      show stats for the current week\n    date:      show stats for a specific date (eg. \"2024/06/08\")\n    range:     show stats for a specific date range (eg. \"2024/06/08...2024/06/12\")\n    all:       show stats for all log entries\n\n*Note: If a task log continues past midnight in your local timezone, it'll\nbe considered in the stats for the day it ends.*\n\n![Usage](https://tools.dhruvs.space/images/hours/stats-1.png)\n\nStats can also be viewed via an interactive interface using the\n`--interactive`/`-i` flag.\n\n![Usage](https://tools.dhruvs.space/images/hours/stats-interactive-1.gif)\n\n### Active Task\n\n`hours` can show you the task being actively tracked using the `active`\nsubcommand. This subcommand supports the following placeholders using the\n`--template`/`-t` flag:\n\n    {{task}}:  for the task summary\n    {{time}}:  for the time spent so far on the active log entry\n\nTip: This can be used to display the active task in tmux's (or similar terminal\nmultiplexers) status line using:\n\n```\nset -g status-right \"#(hours active -t ' {{task}} ({{time}}) ')\".\n```\n\n### Generate Dummy Data\n\nYou can have `hours` generate dummy data for you, so you can play around with\nit, and see if its approach of showing reports/logs/stats works for you. You can\ndo so using the `gen` subcommand.\n\n```bash\nhours gen --dbpath=/var/tmp/throwaway.db\n```\n\n🎨 Custom Themes\n---\n\n`hours` supports custom themes for its user interface (for the TUI and the\noutput of the `logs`, `report`, and `stats` commands. New themes can be added\nusing `hours themes add`, which will create a JSON file in `hours`' config\ndirectory. You can then tweak this file as per your liking.\n\nA sample theme config looks like the following. Colors codes can be provided in\nANSI 16, ANSI 256, or HEX formats. You can choose to provide only the attributes\nyou want to change.\n\n```text\n{\n  \"activeTask\": \"#8ec07c\",                   # color for the active task in the footer\n  \"activeTaskBeginTime\": \"#d3869b\",          # color for the active task begin time in the footer\n  \"activeTasks\": \"#fe8019\",                  # primary color for the active task list view\n  \"formContext\": \"#fabd2f\",                  # color for the context message in all forms\n  \"formFieldName\": \"#8ec07c\",                # color for field names in all forms\n  \"formHelp\": \"#928374\",                     # color for the help text in all forms\n  \"helpMsg\": \"#83a598\",                      # color for help messages in the footer\n  \"helpPrimary\": \"#83a598\",                  # primary color for the help view\n  \"helpSecondary\": \"#bdae93\",                # secondary color for the help view\n  \"inactiveTasks\": \"#928374\",                # primary color for the inactive task list view\n  \"initialHelpMsg\": \"#a58390\",               # color of the initial help message in the footer\n  \"listItemDesc\": \"#777777\",                 # color to be used for the title of list items (when they're not selected)\n  \"listItemTitle\": \"#dddddd\",                # color to be used for the title of list items (when they're not selected)\n  \"recordsBorder\": \"#665c54\",                # color for the table border in the output of logs, reports, stats\n  \"recordsDateRange\": \"#fabd2f\",             # color for the data range picker in the output of logs, reports, stats\n  \"recordsFooter\": \"#ef8f62\",                # color for the footer row in the output of logs, reports, stats\n  \"recordsHeader\": \"#d85d5d\",                # color for the header row in the output of logs, reports, stats\n  \"recordsHelp\": \"#928374\",                  # color for the help message in the output of logs, reports, stats\n  \"taskLogDetails\": \"#d3869b\",               # primary color for the task log details view\n  \"taskEntry\": \"#8ec07c\",                    # primary color for the task entry view\n  \"taskLogEntry\": \"#fabd2f\",                 # primary color for the task log entry view\n  \"taskLogList\": \"#b8bb26\",                  # primary color for the task log list view\n  \"tasks\": [                                 # colors to be used for tasks in the output of logs, report, stats\n    \"#d3869b\",\n    \"#b5e48c\",\n    \"#90e0ef\",\n    \"#ca7df9\",\n    \"#ada7ff\",\n    \"#bbd0ff\",\n    \"#48cae4\",\n    \"#8187dc\",\n    \"#ffb4a2\",\n    \"#b8bb26\",\n    \"#ffc6ff\",\n    \"#4895ef\",\n    \"#83a598\",\n    \"#fabd2f\"\n  ],\n  \"titleForeground\": \"#282828\",              # foreground color to use for the title of all views\n  \"toolName\": \"#fe8019\",                     # color for the tool name in the footer\n  \"tracking\": \"#fabd2f\"                      # color for the tracking message in the footer\n}\n```\n\nYou can view configured themes using `hours themes list`.\n\nRunning hours with the `--theme \u003cTHEME_NAME\u003e` flag will load up that theme.\nAlternatively, you can set `$HOURS_THEME` to the theme name so you don't have to\npass the flag every time.\n\nHere's a sampling of custom themes in action.\n\n| Theme          | Preview                                                                                            |\n|----------------|----------------------------------------------------------------------------------------------------|\n| Solarized Dark | ![solarized-dark](https://github.com/user-attachments/assets/f68c0863-c45f-41d9-be2a-395f768b43ea) |\n| Monokai        | ![monokai](https://github.com/user-attachments/assets/42e1ed59-b9be-42c3-953c-553bd94ff8e2)        |\n| Nord           | ![nord](https://github.com/user-attachments/assets/407d54f3-e48a-4c08-8688-f19058e4c373)           |\n| Dracula        | ![dracula](https://github.com/user-attachments/assets/854273e9-be0c-4457-bb19-86a9e1a04434)        |\n| Gruvbox        | ![gruvbox](https://github.com/user-attachments/assets/b15982fb-0597-4457-940f-0e90b0d2cc06)        |\n| Catppuccin     | ![catppuccin](https://github.com/user-attachments/assets/2dfdd9ec-7a87-4d18-819f-f5135b77fb23)     |\n| Tokyonight     | ![tokyonight](https://github.com/user-attachments/assets/21ebe806-3159-4c5d-abbc-5405ef75087b)     |\n\n📋 TUI Reference Manual\n---\n\n```text\n\"hours\" has 6 views:\n  - Tasks List View                       Shows active tasks\n  - Task Management View                  Shows a form to create/update tasks\n  - Task Logs List View                   Shows your task logs\n  - Task Log Details View                 Shows details for a task log\n  - Inactive Tasks List View              Shows inactive tasks\n  - Task Log Entry View                   Shows a form to save/update a task log entry\n  - Help View\n\nKeyboard Shortcuts\n\nGeneral\n\n  1                                       Switch to Tasks List View\n  2                                       Switch to Task Logs List View\n  3                                       Switch to Inactive Tasks List View\n  \u003ctab\u003e                                   Go to next view/form entry\n  \u003cshift+tab\u003e                             Go to previous view/form entry\n  q/\u003cctrl+c\u003e                              Go back\n  ?                                       Show help view\n\nGeneral List Controls\n\n  k/\u003cUp\u003e                                  Move cursor up\n  j/\u003cDown\u003e                                Move cursor down\n  h\u003cLeft\u003e                                 Go to previous page\n  l\u003cRight\u003e                                Go to next page\n  \u003cctrl+r\u003e                                Refresh list\n\nTask List View\n\n  a                                       Add a task\n  u                                       Update task details\n  s                                       Start/stop recording time on a task; stopping\n                                              will open up the \"Task Log Entry View\"\n  S                                       Quick switch recording; will save a task log\n                                              entry for the currently active task, and\n                                              start recording time for another\n  \u003cctrl+s\u003e                                Edit the currently active task log/Add a new\n                                              manual task log entry\n  \u003cctrl+x\u003e                                Discard currently active recording\n  \u003cctrl+t\u003e                                Go to currently tracked item\n  \u003cctrl+d\u003e                                Deactivate task\n\nTask Logs List View\n\n  ~ at the end of a task log comment indicates that it has more lines that are not\n  visible in the list view\n\n  d                                       Show task log details\n  \u003cctrl+s\u003e/u                              Update task log entry\n  \u003cctrl+d\u003e                                Delete task log entry\n\nTask Log Details View\n\n  h                                       Go to previous entry\n  l                                       Go to next entry\n\nInactive Task List View\n\n  \u003cctrl+d\u003e                                Activate task\n\nTask Log Entry View\n\n  enter/\u003cctrl+s\u003e                          Save entered details for the task log\n  k                                       Move timestamp backwards by one minute\n  j                                       Move timestamp forwards by one minute\n  K                                       Move timestamp backwards by five minutes\n  J                                       Move timestamp forwards by five minutes\n  h                                       Move timestamp backwards by a day\n  l                                       Move timestamp forwards by a day\n```\n\nAcknowledgements\n---\n\n`hours` is built using [bubbletea][1], and is released using [goreleaser][2],\nboth of which are amazing tools.\n\n[1]: https://github.com/charmbracelet/bubbletea\n[2]: https://github.com/goreleaser/goreleaser\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhth%2Fhours","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhth%2Fhours","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhth%2Fhours/lists"}