{"id":14966002,"url":"https://github.com/masukomi/hey_3","last_synced_at":"2025-11-12T02:37:16.050Z","repository":{"id":64869602,"uuid":"578444379","full_name":"masukomi/hey_3","owner":"masukomi","description":"Hey! An Interruption and Time Tracking Command line app.","archived":false,"fork":false,"pushed_at":"2024-11-19T13:39:07.000Z","size":721,"stargazers_count":12,"open_issues_count":29,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-10T12:33:21.758Z","etag":null,"topics":["cli","raku","rakulang","timetracker","timetracking"],"latest_commit_sha":null,"homepage":"https://interrupttracker.com/","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/masukomi.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","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":"2022-12-15T04:16:59.000Z","updated_at":"2025-09-29T18:35:06.000Z","dependencies_parsed_at":"2024-09-14T01:22:10.626Z","dependency_job_id":"91d98286-05ba-4307-aa1e-fc08bf2aed4e","html_url":"https://github.com/masukomi/hey_3","commit_stats":{"total_commits":112,"total_committers":2,"mean_commits":56.0,"dds":0.0267857142857143,"last_synced_commit":"ad81b902f7b9aafdf4a45407a11d0ceac645cfde"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/masukomi/hey_3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masukomi%2Fhey_3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masukomi%2Fhey_3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masukomi%2Fhey_3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masukomi%2Fhey_3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masukomi","download_url":"https://codeload.github.com/masukomi/hey_3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masukomi%2Fhey_3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283966324,"owners_count":26924586,"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-11-12T02:00:06.336Z","response_time":59,"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","raku","rakulang","timetracker","timetracking"],"created_at":"2024-09-24T13:35:40.654Z","updated_at":"2025-11-12T02:37:16.034Z","avatar_url":"https://github.com/masukomi.png","language":"Raku","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nHey - a simple command line time tracker, written in Raku and backed by SQLite.\n\n# DESCRIPTION\n\nHey is a command line tool that tracks your time spent on various projects that may have happened along the way. \n\n\n# USAGE\n\n**Quickie Version**\n\n``` text\nUsage:\n  hey start [\u003cstart_args\u003e ...] -- Start a new timer\n  hey stop [\u003cstop_args\u003e ...] -- stop an existing timer\n  hey log \u003cnumber\u003e \u003cduration\u003e -- see a log of recent timers\n  hey log-interrupts \u003cnumber\u003e \u003cduration\u003e -- see a log of recent interruptions\n  hey running -- lets you know if there are any timers running \u0026 what they are for\n  hey \u003cname\u003e [\u003cstart_args\u003e ...] -- Record an interruption\n  hey kill timer \u003cid\u003e -- Remove an unwanted timer.\n  hey nevermind -- Cancel \u0026 delete the most recent running timer\n  hey kill \u003cname\u003e -- Remove an unwanted person / thing from interruptions\n\n    [\u003cstart_args\u003e ...]    optional time adjustment, project(s), \u0026 optional tags\n    [\u003cstop_args\u003e ...]     optional id, and optional time adjustments (e.g. 4 minutes ago)\n    \u003cnumber\u003e              number of duration units\n    \u003cduration\u003e            duration string. E.g. minutes, hours, days, etc.\n    \u003cname\u003e                name of person / thing that interrupted you\n    \u003cid\u003e                  the id of the timer to delete.\n```\n\nAnd now for some useful details to fill in the gaps...\n\n\n# Timers\n\nStarting and stopping timers is pretty straightforward. At a bare minimum you just tell it to start and give it a project name: `hey start @my_project` and stop it when you're done with `hey stop`\n\n## Associating Projects \u0026 Tags\n\n- Project names are prefixed with `@`. \n- Tag names are prefixed with `+`. Neither can contain spaces.\n- Every timer event must be associated with _at least one_ project.\n- Tags are optional.\n- Order of tags and projects doesn't matter. They can be mixed too.\n\n\n``` text\n# simple usage\nhey start @project +tag1 +tag2\nhey stop\n\n```\n\n## Backdating Timers\n\nThe start and stop of a timer can be backdated using relative or absolute times. \n\nTime modifiers must come immediately after start/stop. \n\n### Absolute Times \nAbsolute times are specified with 12 hour or 24 hour time formats. You can also just specify the hour with no minutes. The expected format is \"at\" followed by the time.\n\n``` text\nhey start at 4 @project +tag\nhey start at 4:30 @project +tag\nhey start at 16:30 @project\n```\n\nThe system will always assume you mean the most recent corresponding time. So, if for example it's 6PM and you say `at 4` it's going to assume you mean 2 hours ago.  If, however it's 3PM and you say `at 4` it's going to assume you meant `4 AM`. This will carry-over to the previous day if you leave a timer running overnight. And yes, it should handle year boundaries correctly and not accidentally mark something as being done in the future.\n\nOccasionally you'll need to specify stop a timer you left running the prior day, or maybe add a record for some time you forgot to track on a past day. In that case you can also specify the date. Dates come before times and are in MM/DD format. When you do this you will need to specify the full time in 24hr format. There's no good way for Hey to know if `4:00` means 4 PM or 4 AM. \n\n``` text\nhey start at 12/16 11:50 @project\n```\n\n### Relative Times \n\nRelative times come immediately after start/stop and follow the syntax of `\u003cnumber\u003e \u003ctime unit\u003e ago`\n\nYou must include \"ago\" as it provides a clue to the code as to what you're intending.\n\n``` text \n# backdating \nhey start 4 minutes ago @project +tag1\nhey start 3 days ago @project\n```\n\n#### Supported Duration Words\n\nYou can use any of the following duration words. \n\n* second\n* seconds\n* minute\n* minutes\n* hour\n* hours\n* day\n* days\n* week\n* weeks\n* month\n* months\n* year\n* years\n\n### Multiple Timers\nHey supports multiple simultaneous timers. There's nothing fancy to it. The only special note is that `stop` will stop the most recent one unless you provide an id. \n\n### Stopping A Specific Timer\n\nTo stop a specific timer you just give it the integer id shown in the log.\n\n`hey stop 12`\n\n### Killing A Specific Timer\nSometimes, things don't go as planned. For example, I started a timer\nto go walk the dogs, left my computer, and unexpectedly ended up\neating lunch. That timer was no good. \n\nTo kill an unwanted timer say `hey kill timer \u003cid\u003e`\n\n```text\nhey kill timer 4\n```\n\nA timer's id is shown when you create a new timer, or when you view\nthe log.\n\n#### Alternately....\n\nStop the most recently created running timer without knowing its ID.\n\n```\nhey nevermind\n```\n\nWhy? Because I keep starting a timer and then finding myself being\nretasked. For example: \n\n\u003e me: \"I'm going to start cooking...\" \n\u003e `hey start @cooking`\n\u003e wifey: \"Maybe you should walk the dogs first so that they don't\n\u003e annoy you with constantly wanting to go in and out.\"\n\u003e me: 🤔\n\u003e `hey nevermind`\n\u003e `hey start @dogs +walking`\n\n\n## Viewing the Log\n\n`hey log \u003cnumber\u003e \u003cduration\u003e`\n\n![example log output](../readme_images/images/all_timers.png)\n\n\nThis uses the same duration words as in backdating. \n\n``` text\nhey log 4 days\nhey log 24 hours\n```\n\nNote: when it comes to durations of a day or larger it uses cultural meaning not literal meaning. \n\nSo, for example:\n\n* `hey log 1 day` is going to get you _today's_ log. \n* `hey log 1 week` is going to get you _this week's_ log. Monday is treated as the start of the week, so if it's Monday you'll only see one day worth of records. \n* `hey log 1 month` is going to get you _this month's_ log.\n* `hey log 1 year` is going to get you _this year's_ log.\n\nDay's an larger all count from midnight. All times _should_ be local.\n\nIf you want a specific and literal amount of time use seconds, minutes, or hours. \n\nSo, for example, `hey log 1 day` doesn't get you the past 24 hours worth of logs. It gets you everything from midnight yesterday. If you really want 24 hours, just say `hey log 24 hours`.\n\n## Summarized Time\nSummarizing timers follows the same pattern as generating a log of them. Asking for a summary of timers will produce a table displaying the amount of time spent on each project during that duration.\n\n`hey summarize timers \u003camount of time\u003e \u003cduration\u003e`\n\nSo, for example, `hey summarize timers 2 days` might output something like this.\n\n![example summary output](../readme_images/images/summarized_timers.png)\n\n\n# Interruptions\n\nRecording an interruption is the same as recording a timer, except that you start with the name of the person / thing that interrupted you, and project is completely optional.\n\n``` text\nhey bob\nhey bob at 9:15\nhey bob at 10:30 +gossip\nhey bob at 11:15 @project_x +questions\nhey bob 20 minutes ago \nhey bob 10 minutes ago @project_x +questions\n```\n## Viewing the Log\nThis works the same as viewing your timer logs, but you say \"log-interrupts\" instead of \"log\"\n\n`hey log-interrupts \u003cnumber\u003e \u003cduration\u003e`\n\n![example log output](../readme_images/images/all_interruptions.png)\n\n# Other\n\n## Tagging After the fact\nYou can add tags to a timer or interruption after it's been created, by running `hey tag \u003cid\u003e \u003clist of tags\u003e` If you ran a marathon and wanted to tag it with your thoughts afterwards you might say `hey tag 33 +hard +fulfilling`\n\n\n## Listing Projects\n`hey projects` will output a list of all the projects you've entered.\nThis is useful when you've forgotten what you called something, and\nfor integrations like shell autocomplete. \n\n\n# INSTALLATION\n\nHey is written in [Raku](https://raku.org), and uses the\n[zef](https://github.com/ugexe/zef) package manager for installation.\n\nIf you've already got Raku and `zef` installed then just run:\n\n`zef install Hey`\n\nIf you don't have Raku installed then...\n\n## Raku install quick-guide\n\nMy recommendation is to use [Homebrew](https://brew.sh/) to install\n[Rakudo](https://rakudo.org/) Regardless of if you use Homebrew, or\ndownload from the main site, you'll want the [Rakudo-Star](https://rakudo.org/star) package. This brings along a handful of other\nuseful things, like our package manager: [zef](https://github.com/ugexe/zef).\n\n```\nbrew install rakudo-star\n```\n\nNow, go back and run the `zef install Hey` command from above.\n\n\n## Coming soon\n\n### Tagging After The fact\nSometimes you'll record an interruption, or some work, but forget to add a tag. \n\n### Reports\n* Graph Interruptions over time, to find parts of the day where you're most likely to be able to focus, or need to hide.\n* Graph Interruptions by people to find out who you need to talk to.\n* Graph Interruptions by tag or projects to find out where you would best benefit from adding documentation.\n\n### Configuration\nIt'd be nice to be able to configure things, such as when the start of the day is. Many of us work past midnight, and consider it part of the prior day's work. So, it'd be nice to have the logging use our preferred \"start of day\" time. [Here's the GitHub issue for that feature](https://github.com/masukomi/hey_3/issues/3).\n\nI'm betting you might have ideas for configurations too. Like, maybe colors for specific data types in the report? \n\n# CONTRIBUTING\n\nPull Requests are _very_ welcomed. \n\nI'm using this daily now so there will be modifications and improvements over time. I'm especially interested in adding useful reporting and data extraction functionality. \n\nLet's chat [on Mastodon](https://connectified.com/@masukomi) if you've got some ideas. Alternately, just [file a new ticket on github](https://github.com/masukomi/hey_3/issues).\n\nNote: this app's version numbers follow strict [Semantic Versioning](https://semver.org). \n\n## Tests\n\nThe test suite uses [bash_unit](https://github.com/pgrange/bash_unit) because testing an app where 90% of the behaviors are based upon side-effects of data that may, or may not, have been persisted in the DB is way easier to write System tests for than Unit tests. If you feel like writing some Raku unit tests with all the stubbing that that will require, I'll happily merge the PR. \n\nRegardless of unit tests, if you do add / change functionality please include additional bash_unit tests with your PR.\n\nThe bash_unit tests can be run by changing into the `bash_unit_tests` directory and running `bash_unit hey_test.sh`\n\nNote that these will work on a local test database, so you don't have to worry about hurting your real time \u0026 interruption tracking data. \n\n# AUTHOR\n\nmasukomi (A.K.A. Kay Rhodes)\n\n- Web: [masukomi.org](https://masukomi.org)\n- Mastodon: [@masukomi@connectified.com](https://connectified.com/@masukomi)\n\nCOPYRIGHT AND LICENSE\n=====================\n\nCopyright 2022 Kay Rhodes \u0026 distributed under the GNU Affero General Public License version 3.0 or later.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasukomi%2Fhey_3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasukomi%2Fhey_3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasukomi%2Fhey_3/lists"}