Crate zentime_rs

Expand description

Zentime is a client/server based CLI pomodor/productivity timer written in Rust. This crate consists of a binary and a library crate. The library crate is a collection of tools to interact with zentime server, clients, configuration and to handle inter-process-communication.

Timer suited for the pomodoro technique
Socket-based Client/Server-Architecture, where multiple clients can attach to a single timer server
Server is terminal independent and runs as a daemon
TUI-interface with keymaps + and a minimal TUI-interface
CLI commands to interact with the timer without attaching a client (e.g. for integration into tools such as tmux)

Example with multiple clients + display inside the left status bar of tmux

Installation

NOTE: The timer has currently only been tested on Mac and Linux, but might also work on Windows (please let me know if you tried it succesfully).

Homebrew

brew tap on3iro/zentime
brew install zentime

Cargo

cargo install zentime-rs

Nix

Coming soon

Configuration

The default location for the configuration file is /home/<user>/.config/zentime/zentime.toml. To get an overview of available configuration options please have a look at the example configuration.

For an overview of all available configuration keys, check out the docs. Note that each key (view, timers etc.) corresponds to the header of a toml table while clicking on the type inside the docs shows you the available configuration fields.

Logs

Logs are being written to:

/tmp/zentime.d.err - this captures any panics
/tmp/zentime.d.out - this captures error/warn/info etc. logs

The default log level is warn. You can configure the log level by running zentime with RUST_LOG=<level> zentime. Here’s an overview of available log levels.

Zellij integration example

I’ve found that currently the easiest way to get some integration with zentime into zellij, is to create a custom layout and also create some shell aliases.

For example you could use the following layout as base for a ‘zellij-zentime’-layout:

layout {
    pane split_direction="vertical" size=1 {
      pane {
        size 30
        borderless true
        name "zentime"
        command "zentime"
      }
      pane borderless=true {
          plugin location="zellij:tab-bar"
      }
    }
}

You might need to adjust the size of the zentime pane depending on the terminal font you are using.

WARNING: There currently is no way to isolate regular panes in zellij from the tab-sync mechanism. (Only plugin panes are currently isolated) This means that you might accidentally change your timer, when you use tab-sync mode. I already created a feature request to create isolated panes and am planning to contribute and create a PR if the maintainer is fine with that.

NOTE: I actually wanted to write a plugin for zellij. However unfortunately this is currently not that easy for two reasons:

The zellij plugin system is currently being rebuilt and it doesn’t really make sense to built a “legacy”-plugin right now

Our zentime client library code makes use of a lot of async code, which does not yet compile to WASI

Because zellij also does not yet allow arbitary commands to be configured with keyboard shortcuts, you basically have three options to interact with zentime:

Just manually switch to the pane and use our regular zentime shortcuts
Manually run commands/trigger another zentime client inside the pane you are working in anyway right now
Recommnded: (This is basically just an alteration of 2. -> Create bash/zsh/ aliases for commands like zentime skip, zentime toggle-timer etc.

If you go the third route I would recommend to prefix each command with -s (--silent) as you probably are not interested in the minor output zentime gives you under these circumstances.

Tmux integration example

To display the current timer state inside the tmux status bar you could use zentime once which will be queried by tmux on each status bar update. Simply add the following snippet to your .tmux.conf:

set -g status-left " #(zentime once) "

If you would like to add shortcuts (e.g. to toggle pause/play) from inside tmux you could add bindings like this:

bind t run-shell "zentime toggle-timer > /dev/null"
bind y run-shell "zentime skip > /dev/null"

Usage as library

Zentime is built in such a way, that it should be possible to build custom clients etc. to attach to the server. To do so one should use the modules provided by the library crate. More documentation/examples on how to use these, will follow soon.

NOTE: The API of the library crate is not yet stable and might change on minor version updates. As soon as this crate reaches 1.0.0 status, breaking changes will only ever happen on major versions.

Modules

client
Code related to zentime terminal clients (e.g. async connection handling, terminal io etc.)
config
Code related to the runtime configuration of zentime
ipc
Utilities to handle zentime inter-process-communication
server
Zentime server utilities