Warning

zshclock is in active development! Functionality is limited, and features may appear and disappear without warning. Please wait patiently for the 1.0 release, or until the banner color switches from orange to purple.

_{Curious eyeball-havers are encouraged to checkout the evolution branch and corresponding project board to track current development.}

Table of Contents

• About
• Installation
• Usage
• Contributing
• Acknowledgements

About

Note

Not all features and capabilities described here are currently implemented. Check the wiki and/or usage for details.

zshclock is a responsive and highly customizable timepiece for the terminal, written entirely in native zsh.

It boasts a multitude of features, from dazzling styles, layouts, and colors, to various modes and alternate behaviors. Built from the ground up with customization in mind, every part of the clock can be tweaked and tailored for the ultimate experience in chronographic adoration. Plus, it even tells the time.

Symbol	Meaning
✅	Fully implemented
⚪	Partially implemented
⭕	In progress
❌	Not yet implemented

	Features
✅	Tells the time.
✅	Customizable date line.
✅	Built-in command bar for runtime customization.
⚪	Navigate command bar history.
⭕	Clock, timer, stopwatch, and alarm modes.
⭕	Auto-size the clock based on window size, optionally preserving aspect ratio.
⭕	Customizable clock format (seconds on/off, 24-hour time, etc).
⭕	Shortcuts for rapid personalization.
❌	Ascii, binary, digital, and analog clock faces.
❌	Execute a shell command on alarm/timer completion.
❌	Load settings from a config file.
❌	Fuzzy search command bar history.
❌	Excessive color options.

Installation

Requirements
zsh (obviously)

Step 1: Get zshclock

If you have git installed, simply open your favorite terminal and run:

git clone https://github.com/tenault/zshclock.git

^{Alternatively, download the latest release.}

Step 2: Activate zshclock

Method 1 — Custom Function

Run the following to link the ztc command to zshclock in your ~/.zshrc:

echo "ztc() { ~/zshclock/zshclock.zsh }" >> ~/.zshrc

Tip

If you saved zshclock somewhere else, make sure to change the path inside { ... } accordingly.

🎉 That's it! 🎉 zshclock is now fully installed. Restart your terminal to give it a try.

^{To uninstall, simply delete the zshclock folder and remove the ztc() line from ~/.zshrc}

Method 2 — Local Binary

Alternatively, the following set of commands will create a local bin folder and add zshclock to it:

mkdir -p ~/.local/bin                          # Creates a local bin folder if one doesn't already exist
cp ~/zshclock/zshclock.zsh ~/.local/bin/ztc    # Copies zshclock into the local bin
echo "path+=~/.local/bin" >> ~/.zshrc          # Adds the local bin to the system PATH

rm -r ~/zshclock                               # Optional, removes the source folder

🎉 zshclock is now fully installed! 🎉 Restart your terminal to give it a try.

_{To uninstall, simply delete the ztc program from ~/.local/bin:}

rm ~/.local/bin/ztc

^{To remove the local bin folder entirely, delete ~/.local/bin and remove the path+=... line in ~/.zshrc}

Usage

• To start the clock, run ztc
• To stop the clock, type q

Yup. It's that simple. zshclock will take a few seconds to compile the first time you run it, but every run after that will be lightning-fast.

At any point while zshclock is running, you can type : or press <enter> to open the command bar, which lets you customize different parts of the clock. Currently, only one command is implemented:

Usage: date <format>

Arguments:
    format    A string containing strftime-compatible expansions

The date command lets you change the text under the clock to anything you want. Run the following to see it in action:

date %a @b%b %d@r %p

^{The symbols @b and @r in the above example are a special type of expansion unique to zshclock, called flares
For a complete list of available expansions, refer to the wiki on date formatting}

For a complete guide on using zshclock, including a list of available commands, refer to the wiki on usage

Contributing ♥

zshclock welcomes any and all contributions, so long as they adhere to the guidelines set forth in Contributing. Contributors are highly encouraged to glance over them before submitting their first contribution.

Additionally, zshclock is governed by the Code of Bill and Ted, and as such, all contributors are expected to follow its rules without exception.

Acknowledgements

zshclock is proudly forked from octobanana/peaclock ♥

^{Wordmark based on Nancyj from patorjk}