Khronos is a simple command line tool use to track the time you spend on a specific project and the one or more tasks associated with that project. It was inspired by the concepts of utt (Ultimate Time Tracker) and timetrap.
You can install khronos using [scoop](https://scoop.sh/). It is in the khronos bucket:
# Add the khronos bucket.
scoop bucket add khronos https://github.com/jlanzarotta/scoop-khronos
# Install khronos.
scoop install khronosI personally like to alias the Khronos executable (khronos.exe) to a simple command, in my case, I used 'k'. For Microsoft PowerShell, you can use
> Set-Alias -Name k -Value khronosWhen Khronos starts up, it checks to make sure there is a default configuration file. If it does not exist, it is automatically created for you.
Khronos uses the following precedence order when determining where the configuration file is located. Each item listed, takes precedence over the item below it:
|
Note
|
For Microsoft Windows®, the default directory is %USERPROFILE%, while under Unix (FreeBSD®, Linux, macOS®, etc.) the directory is $HOME.
|
-
per-user configuration file
-
%USERPROFILE%/.khronos.yaml
-
$HOME/.khronos.yaml
-
-
XDG_CONFIG_HOME configuration file
-
%XDG_CONFIG_HOME%/khronos/.khronos.yaml
-
$XDG_CONFIG_HOME/khronos/.khronos.yaml
-
The default Microsoft Windows® Khronos configuration is as follows. These configuration options can be modified by the user after installation.
database_file: %USERPROFILE%\.khronos.db (1)
debug: false (2)
report: (3)
by_day: true
by_entry: true
by_project: true
by_task: true
require_note: false (4)
round_to_minutes: 15 (5)
week_start: Sunday (6)
show_by_day_totals: true (7)
split_work_from_break_time: false (8)
favorites: (9)
- favorite: general+training
- favorite: general+product development
- favorite: general+personal time
- favorite: general+holiday
- favorite: general+vacation/PTO/Comp-
The database file used by Khronos. Default is
.khronos.db. -
If debug type information should be printed to the screen or not. Default is
false. -
Indicated which report to run and which ones to not.
-
If a note is required when entering a new entry into Khronos. Default is
false. -
The number of minutes to round up or down to when running reports. This makes is easy to report on a consistent time "buckets".
-
The day used to indicate the start of the week. Some company’s week start on Saturday, some on Sunday. This allows to to change that start day to fit your needs. The default is
Sunday. -
Should a daily total be shown for each day when rendering the "by day" report. Default is
true. -
Indicates if work and break time should be split into seperate values during reports or not. The default is
false. -
The list of favorites.
Khronos supports natural language time constructs for a subset of commands. Commands such as hello, add, break, and stretch have additional parameters that accept time an argument. Any time you pass a time, Khronos will try to parse it as a natural language time.
This feature can be very handy if you start a project/task and forget to add it simply by specifying the --at subcommand.
$ k hello --at "18 minutes ago"The previous example tells Khronos that you want it to add a hello entry with the time that was 18 minutes ago.
$ k hello --at "today at 7:30AM"The previous example tells Khronos that you want it to add a hello entry with the time that was at 7:30AM this morning. This is more straight and to the point.
$ k break lunch --at "12:30"The previous example tells Khronos that you want it to add a break entry with the time that was at specifically "12:30PM".
$ k add project+task -- at "13:45"The previous example tells Khronos that you want it to add an entry with the time that was at specifically "13:45".
For more information about Natural Language Time as well as samples, head over to [https://pkg.go.dev/github.com/ijt/go-anytime]
Khronos has many commands for the user to use:
The hello command tells Khronos you have arrived and to start tracking
time. This should be the first command you execute at the start of your day.
$ k hello|
Warning
|
Keep in mind that if you forget to execute the hello command at the start of the day, Khronos will think you worked throughout the night and calculate your time spent on your task accordingly when you run a report. This may or may not be correct outcome.
|
The add command tells Khronos that you would like to record a project with optional one or more tasks you have just finished working on.
If you would like to perform an interactive add, simply perform the following command.
$ k addDuring an interactive add, your list of favorites are displayed and you can interactively select from your list.
Favorites found in configuration file[C:\Users\yourname\.khronos.yaml]:
# | PROJECT+TASK
---+-----------------------------
0 | general+training
1 | general+product development
2 | general+personal time
3 | general+holiday
4 | general+vacation/PTO/Comp
Please enter the number of the favorite; otherwise, [Return] to quit. > 0In this example, the user chose project/task 0.
If the configuration option require_note: is set to true, Khronos will prompt the user to enter a note. Otherwise, a note is not required.
Please enter the number of the favorite to add; otherwise, [Return] to quit. > 0
A note is required. Enter note or leave blank to quit. >If the note is left blank/empty, nothing is added.
Nothing added.If no favorites are found in your configuration file, an error is displayed and the interactive add is cancelled.
Fatal: No favorites found in configuration file[C:\Users\jlanzarotta\.khronos.yaml]. Unable to perform an interactive add.If during an add, the project+task is specified, this tells Khronos that you just finished working on the project, khronos and the task, programming.
$ k add khronos+programmingIf during an add, you have multiple task you finished, you can specify then like below. This tells Khronos that you just finished working on the project, khronos and the tasks, programming and documentation.
$ k add khronos+programming+documentationThe --note command tells Khronos that you would like to add a note associated with your new entry.
$ k add khronos+programming --note "I love programming."The --favorite flag tells Khronos that you would like to use one of your preconfigured favorite project/task combinations. These favorites are stored in the .khronos.yaml file which is located in the installation directory. By default, there are 5 preconfigured favorites; however, you can add as many as you would like.
|
Note
|
Favorites are zero (0) based. |
Favorites are in the following format:
favorites:
- favorite: general+training
- favorite: general+product development
- favorite: general+personal time
- favorite: general+holiday
- favorite: general+vacation/PTO/CompIf you want to finish working on a known favorite, you can use the --favorite flag to specify the favorite.
$ k add --favorite 0
Adding Project[general] Task[training] Date[2023-12-07T14:10:02-05:00].The previous command tells Khronos that you just finished working on the favorite referenced by the number '0'. If we look in our .khronos.yaml file for the '0' favorite, we find that it references the 'project1+task1' combination. With that, 'project1+task1' would be automatically logged as being completed.
|
Tip
|
Configuring and using favorites, help improve consistency as well as improves speed of entering frequently used project/task combinations. |
An optional URL can be added to a favorite. This URL will show up on various commands and reports. This URL can be uses to a link to JIRA or any website you need to have linked to favorite.
Here is an example:
favorites:
- favorite: general+training
- favorite: general+product development
- favorite: general+personal time
- favorite: general+holiday
- favorite: general+vacation/PTO/Comp
- favorite: project1+screen coding task
url: https://jira.yourcompany.com/task/sreen_coding_task
.
.
.The amend command tells Khronos that you are wanting to modify a recent entry’s information. By default, amend amends the most recent entry’s information. How if you would like to get a list of the entries for today, use the --today option. More on the --today option below.
Using this option, you are shown a list of all the entries for today. You are then given the opportunity to chose the entry you would like to amend.
+---+----------+----------+---------------------------+
| | PROJECT | TASK(S) | DATE/TIME |
+---+----------+----------+---------------------------+
| 1 | ***hello | | 2024-04-15T07:23:03-04:00 |
| 2 | general | training | 2024-04-15T07:49:12-04:00 |
| 3 | general | training | 2024-04-15T08:29:02-04:00 |
| 4 | general | training | 2024-04-15T08:53:01-04:00 |
| 5 | general | training | 2024-04-15T09:18:23-04:00 |
+---+----------+----------+---------------------------+
Please enter index number of the entry you would like to amend; otherwise, ENTER to quit...You are prompted to modify each of the entry’s properties and then asked to validate those modifications before they are committed to the database.
|
Important
|
The Date/Time must be in ISO8601 format. https://en.wikipedia.org/wiki/ISO_8601 |
$ k amend
Amending...
Project[proj-001]
Task[meeting]
Note[CRP with customer.]
Date[2024-04-10T10:32:24-04:00]
Enter Project (empty for no change) [proj-001] : proj-002
Enter Task (empty for no change) [meeting] :
Enter Note (empty for no change) [CRP with customer.] :
Enter Date Time (empty for no change) [2024-04-10T10:32:24-04:00] : 2024-04-10T10:302:00-00:00
| OLD | NEW
----------+---------------------------+---------------------------
Project | proj-001 | proj-002
Task | meeting | meeting
Note | CRP with customer. | CRP with customer.
Datetime | 2024-04-10T10:32:24-04:00 | 2024-04-10T10:30:00-00:00
Commit these changes? (Y/N (yes/no))The break command tells Khronos that you are going went on a break. The time associated with breaks are not added to your daily work time. They are consider under the break classification when doing a `report'.
$ k break lunchThe previous command tells Khronos that you just finished your lunch break.
The edit command tells Khronos you would like to edit the Khronos configuration file with the default system editor.
$ k editOver time as you enter new entries into the database, the database will naturally grow. To clear out old entries, use the nuke command.
The all command tells Khronos that you would like to nukes ALL entries from the database. This includes the current years.
|
Warning
|
Use this extreme caution as ALL entries will be nuked. You are given ample warning before your entries are actually nuked. YOU HAVE BEEN WARNED. |
$k nuke --all
Are you sure you want to nuke ALL the entries from your database? (Y/N (yes/no)) yes
WARNING: Are you REALLY sure you want to nuke ALL the entries from your database? (Y/N (yes/no)) yes
LAST WARNING: Are you REALLY REALLY sure you want to nuke ALL the entries from your database? (Y/N (yes/no)) yes
All entries nuked.The prior-years command tells Khronos that you would like to nuke all entries prior to the current year. So in other words, if you were tracking the past 5 years worth of entries in your database, and you issued the prior-years command, the past 4 years worth of entries would be nuked from the database, leaving just the current year.
|
Note
|
You are given ample warning before your entries are actually nuked… |
$k nuke --prior-years
Are you sure you want to nuke all entries prior to 2024 from the database? (Y/N (yes/no)) yes
WARNING: Are you REALLY sure you want to nuke all entries prior to 2024 from the database? (Y/N (yes/no)) yes
LAST WARNING: Are you REALLY REALLY sure you want to nuke all entries prior to 2024 from the database? (Y/N (yes/no)) yes
All entries prior to 2024 have been nuked.The dry-run command tells Khronos that you do not really want anything nuked. But instead just report on how many entries would have been nuked.
$k nuke --all --dry-run
Are you sure you want to nuke ALL the entries from your database? (Y/N (yes/no)) yes
WARNING: Are you REALLY sure you want to nuke ALL the entries from your database? (Y/N (yes/no)) yes
LAST WARNING: Are you REALLY REALLY sure you want to nuke ALL the entries from your database? (Y/N (yes/no)) yes
All 639 entries would have been nuked.The show command tells Khronos you would like to show various information.
The favorites command tells Khronos that you would like to show all your currently configured favorites that are stored in the .khronos.yaml file which is located in the installation directory.
$ k show --favorites
Favorites found in configuration file[C:\Users\yourname\.khronos.yaml]:
# | PROJECT+TASK
---+-----------------------------
0 | general+training
1 | general+product development
2 | general+personal time
3 | general+holiday
4 | general+vacation/PTO/CompIf one or more of your favorites have an associated URL, your favorites will be shown like this:
$ k show --favorites
Favorites found in configuration file[C:\Users\yourname\.khronos.yaml]:
# | PROJECT+TASK | URL
---+-----------------------------+-------------------------------------------------
0 | general+training | https://yoursite.com/url1
1 | general+product development | https://yoursite.com/url2
2 | general+personal time |
3 | general+holiday |
4 | general+vacation/PTO/Comp |The statistics command tells Khronos that you would like to show some statistics related to the entries you have entered into the database.
$ k show --statistics
STATISTIC | VALUE
---------------+----------------------------------------------------------
First Entry | Project[***hello] Task[] Date[2023-11-27T07:17:36-05:00] (1)
Last Entry | Project[***hello] Task[] Date[2024-04-25T07:15:58-04:00] (2)
Total Records | 21 weeks 2 days 22 hours 58 minutes 22 seconds (3)-
The first entry in the database.
-
The last entry in the database.
-
The total duration that is currently in the database.
The report command tells Khronos you would like to run a report on your activities. By default, you get the current days activities.
A couple of things you will notice when you run a report is, first, the header.
------------ 2024-04-04 00:00:00(14) to 2024-04-04 23:59:59(14) -----------The report header tell you that start and end date/time of the report as well as the week number in parentheses.
Secondly, you will see the Total Time. The Total Time can be in two formats, which is controlled by the split_work_from_break_time configuration option.
If split_work_from_break_time is set to false, you will get a combined Total Time…
Total Time: 3 hours 45 minutes 0 secondIf split_work_from_break_time is set to false, you will get a split Total Time…
Total Working Time: 3 hours 30 minutes 0 second
Total Break Time: 15 minutesThe report command had several handy options what allow you to customize what needs to be reported.
By specifying the option --current-week, this tells Khronos you would like a report for the current week’s activities.
$ k report --current-weekBy specifying the option --previous-week, this tells Khronos you would like a report for the previous week’s activities.
$ k report --previous-weekBy specifying the option --last-entry, this tells Khronos you would like a report for just the last entry’s activity.
$ k report --last-entryBy specifying the option --from date, this tells Khronos you would the report to start from this specific date.
$ k report --from 2019-03-02By specifying the option --to date, this tells Khronos you would the report to end at this specific date.
$ k report --to 2019-03-02By specifying the option --today, this tells Khronos you would the report specifically for today.
$ k report --todayBy specifying the option --yesterday, this tells Khronos you would the report specifically for yesterday.
$ k report --yesterdayBy specifying the option --date, this tells Khronos you would like the report specifically for the given date. The date MUST be in the following format YYYY-mm-dd.
$ k report --date 2024-10-11By specifying the option --no-rounding, this tells Khronos you would the all
the duration to be their original, unrounded values. This option is good it you
have durations that are less than the value you have configured for rounding.
$ k report --from 2019-04-01 --to 2019-04-13 --no-rounding
$ k report --previous-week --no-roundingBy specifying the option '--export', this tells Khronos you would like export the report to one three types, CSV, HTML, and Mark Down. The default is CSV.
$ k report --current-week --export --type csv
$ k report --previous-week --export --type html
$ k report --export --type mdThese commands will create a unique report file with the extension associated with the type you specified. CSV produces a file ending in .csv, HTML produces a file ending in .html, and MD produces a file ending in .md.
Stretches the last entry to the current or specified date/time.
In the below example, the latest entry to 05-Dec-2023… Khronos will as you if you want to perform the stretch or not. If you enter (y or Yes), the latest entry is stretched. If you enter (n/No), the latest entry is not stretched.
$ k stretch
Would you like to stretch Project[***hello] to Tuesday, 05-Dec-2023 13:48:32 EST? (Y/N (yes/no)) yes
Last entry was stretched.BSD 3-Clause License
Copyright (c) 2018-2025, Jeff Lanzarotta All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice,this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.