klog: a time tracker whose records are plain text you can read

The state of the tracker is a file you can read

klog is a command line tool for time tracking in a human-readable, plain-text file format, and the project describes itself as both a file format and the tool that works with it.

That framing is the design. Most time trackers keep your hours in a database owned by somebody else's server, and getting at the raw record means an export, a support request or an API. klog puts the record in a file, in a format a person can open and understand, which means the tracker can be thrown away and the data kept, or the data edited by hand when the tool got something wrong.

The audience is a developer working from a terminal, and the topics on the repository name it plainly: cli, command-line-tool, file-format, plaintext, time-tracker. The site is klog.jotaen.net, and the project was created by Jan Heuermann.

The licence is split, and the split is deliberate. The command line tool is MIT licensed, with the licence text in LICENSE.txt, while the file specification is released into the public domain under CC0 and the OWFa, as recorded in the Specification.md file. That is the arrangement that lets a third party write a tool, a script or a spreadsheet formula that produces the same files without needing a licence negotiation, and it is also why the readme points you at Specification.md as the thing to study if you want to work with the format directly.

One detail catches people out, and the readme calls it out explicitly: the command line tool and the file format specification have independent version numbering schemes. So the number in the tool's version is not the number in the format's version, and a file written by one version of the tool is not automatically readable by a different version of the format.

Building from source, and where the install instructions live

The readme is short on installation on purpose, and everything it says is a pointer. The install section links to the documentation site with the anchor for getting klog, the documentation link is the main entry for learning what klog is and how to use it, and there are separate links for the changelog, the discussions, and the specification.

For compiling from sources, the readme gives one concrete instruction: refer to the run::build shell function in the run.sh file. That is a deliberate choice. Rather than reproducing a build recipe that would then drift from the script in the repository, the project points at the script, so what you run is the same thing the maintainer runs.

The repository layout supports that. There is a run.sh at the root, a klog.go file, a klog/ directory for the implementation, a lib/ directory, a staticcheck.conf for static analysis configuration, go.mod and go.sum, a CHANGELOG.md and a Specification.md, and a .github/ directory for the automation. The klog.go file at the root next to the klog/ package is the kind of layout a Go project with a single binary entry point tends to have.

The go.mod file shows the shape of the tool as well. The module is github.com/jotaen/klog and it requires Go 1.27. The command line parsing is done with github.com/alecthomas/kong, and there are two completion-related dependencies, github.com/jotaen/kong-completion and github.com/posener/complete, which together are what give you shell completion for the commands. There is also github.com/jotaen/genie, github.com/kballard/go-shellquote for handling quoted shell arguments, and github.com/stretchr/testify for tests. The indirect requirements bring in hashicorp/errwrap and go-multierror for error aggregation, and riywo/loginshell, which is a library for detecting the user's login shell, a detail that only matters for a program that reads configuration out of a shell profile.

The cloud.google.com/go dependency is the one that invites a question. It is a large module to require for a local tool, and its presence suggests some part of the tool talks to a Google-hosted service, but the readme does not describe such a feature, so the extent of that integration is not something the documentation in the repository explains.

A format that other tools are meant to be able to read

The presence of Specification.md as a first-class document, linked from the readme under the heading about studying the file format, is the strongest signal about the project's intent. This is a format that is supposed to outlive any one implementation of it.

That intent shows in the licence choice. Putting the specification in the public domain under CC0 and the OWFa means there is nothing to license and nothing to attribute when you write a parser, a generator, a migration script or a report that reads a klog file. For a format whose entire selling point is that it is plain text, the risk is that some other tool locks it into a proprietary dialect, and the public domain release is the answer to that.

The file format is described as plain text and human-readable, and the topics list includes plain-text, plaintext and fileformat. A human-readable format for time entries is unusual, and it is unusual on purpose. The value is not only in being able to read it but in being able to correct it, and in being able to see at a glance what you logged, which is the failure mode of every time tracker that keeps a relational model with an internal identifier per entry.

The specification is versioned separately from the tool, which reinforces the point. A file format with its own version number, published independently of the program that writes it, behaves like a published interface. Other implementations are not merely tolerated, they are anticipated, and the version scheme exists so that a reader can tell whether it understands the file in front of it.

The readme also links the discussions area for questions and feedback, and the CHANGELOG.md for what is new, which is a reasonable arrangement for a project whose users are also its potential third-party implementers.

A small Go program with a wide surface of dependencies

The dependency list is worth a second look, because it says something about where this kind of tool ends up.

The command line interface itself is built on kong, which is a struct-tag driven parser, so the set of commands and flags is declared in Go types rather than parsed by hand. The two completion dependencies mean the tool can generate completions for bash, zsh or fish, and posener/complete is the library that does the installing and caching of a completion script.

Then there is genie and the kballard/go-shellquote library, and the loginshell indirect dependency. A tool that needs to know the user's login shell is a tool that reads shell configuration, and the presence of a shell-quoting library means it also handles command lines that come from a config file rather than from the terminal. Those two facts together suggest a tool that lets you define how entries are recorded, including running something, and that a shared configuration file is a real use case.

The testify dependency is for tests, and the hashicorp error aggregation libraries are for combining multiple errors into one, which fits a tool that validates a set of entries and wants to report all the problems at once rather than stopping at the first.

The overall shape is a small, well-factored Go program whose dependency list is dominated by the command line and completion story, with a couple of libraries that suggest a command execution and configuration feature. It is a plausible design for a focused tool, and it also means the tool inherits the upgrade cadence of kong, posener/complete and testify, which is a cost for a program people may want to keep installed for years.

Where klog is the wrong choice

The first limitation is that a file on your own disk is not a shared system. There is no multi-user support, no server, no locking across machines and no notion of who logged which hour. If time tracking in your organisation exists because someone else needs the numbers, an invoicing flow or a payroll process, a single local file is the wrong shape, because the reporting has to happen somewhere else.

The second is that plain text is plain text in both directions. It is easy to read and easy to correct, and it is also easy to break, since nothing validates the file for you except the tool when it reads it. A corrupted or hand-edited file is your problem, and there is no undo. A database gives you transactions and a schema; a text file gives you legibility and no safety net. That trade is the point of the project, and it is a trade.

The third is reporting. klog stores entries in a format designed to be read, and the readme says nothing about report generation, aggregation across projects, invoicing, or any kind of reporting feature. If what you need from a time tracker is a timesheet per week, a monthly summary for a client or an export for a payroll system, you are going to write that yourself or use a different tool.

The fourth is the version split, which bites in the wrong direction. Because the tool and the format version independently, a file written by a newer tool may be unreadable by an older binary, and a file written by an older tool may confuse a newer one. A user with several machines on different versions has a small compatibility problem that a self-contained tool usually does not have, and the readme does not describe a compatibility matrix.

The fifth is the size of the surface for what it is. A tool whose whole job is recording time has dependencies on a Google Cloud module, a shell-quoting library, a login-shell detector and a shell completion framework. Some of that is convenience and some of it is the price of a rich command line, and the cloud dependency in particular is worth understanding before you install it, because the readme does not explain what it is used for.

Editorial conclusion

klog fits a developer who wants time tracking with no service to sign up for and no database to lose, since the entire state is a plain-text file you can read, diff, and correct by hand, and the format is specified in a separate document so other tools can write the same files. It is the wrong choice for a team that needs shared accounts, an approval workflow or billing-grade reporting, and it is the wrong choice if you want an app rather than a terminal. Before adopting it, read Specification.md, because the tool and the format version independently, and check the CHANGELOG.md, since the last push was on 2026-10-19 with version v7.2 released the same day and v7.1 back in February 2026.

Frequently asked questions

Official sources

1. jotaen/klog on GitHub
2. License: MIT
3. Project website
4. README
5. Releases