liamg / shox

🍫 A customisable, universally compatible terminal status bar

Shox: Terminal Status Bar

A customisable terminal status bar with universal shell/terminal compatibility. Currently works on Mac/Linux.

Installation

NOTE This is still very experimental. I'm using it locally without any problems right now, but there's still a lot of testing and tweaking to do. Feel free to try it out, but get ready for some potential bugginess!

curl -s "https://raw.githubusercontent.com/liamg/shox/master/scripts/install.sh" | sudo bash

If you don't like to pipe to sudo - as well you shouldn't - you can remove the sudo above, but you'll have to add the shox dir to your PATH env var manually, as instructed by the installer.

Configuration

The shox config file should be created at $XDG_CONFIG_HOME/shox/config.yaml, which is usually ~/.config/shox/config.yaml. You can alternatively create it at ~/.shox.yaml

The config file looks like the following:

shell: /bin/bash
bar:
    format: "{time}||CPU: {cpu} MEM: {memory}"
    colours: 
      bg: red
      fg: white
    padding: 0

Shox will use your SHELL environment variable to determine the shell to run if a shell is not specified in the config file, but if your SHELL is set to shox, it'll default to /bin/bash to prevent a horrible recursive mess.

Bar Configuration

Bar configuration is done using a simple string format. Helpers are encased in braces e.g. {time}, alignment is done using pipes (see below), and any other text will be written to the bar.

Alignment

You can use pipes to align content within the status bar. All content before the first pipe will be aligned to the left, all content between the first and second will be centre aligned, and all content after the second pipe will be right aligned.

For example, to display a bar that centre aligns the time, you could use |{time}|

Colours

The following colours are available: black, white, red, green, yellow, blue, magenta, cyan, darkgrey, lightgrey, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan.

Helpers

Helpers create dynamic output in your status bar. You can use one by adding it to your bar format config. The following is a list of available helpers.

Helper	Description	Example Config	Example Output
time	Show current time	{time}	11:58:17
cpu	Show current CPU usage	{cpu}	20%
memory	Show current memory usage %	{memory}	20%
battery	Show current battery charge %	{battery}	20%
bash	Run a custom bash command	{bash:echo hi}	hi
weather	Show current weather (provided by http://wttr.in)	{weather:1}	🌧 +6°C
until	Show time remaining until a given unix timestamp	{until:1583255109}	13m26s

Ideally this list would be much longer - please feel free to PR more helpers! You can see simple examples here.

Weather

The configuration section of the weather helper holds the display format. For all available display formats please visit chubin/wttr.in#one-line-output The default value is 1 which only shows the weather

NOTE: You don't need to URL-encode the weather format, i.e. use %l: %c %t instead of %l:+%c+%t

Uninstallation

If installed with sudo

Remove the binary from /usr/local/bin

rm /usr/local/bin/shox

If installed without sudo

Remove the binary from the shox installation dir $HOME/bin

rm $HOME/bin/shox

NOTE: Don't forget to remove any configuration files you've created should you decide you don't need them

Why?

I frequently needed a way to have a quick overview of several things without cramming them into my PS1, and to update those things dynamicly.

How does it work?

Shox sits between the terminal and your shell and proxies all data sent between them. It identifies ANSI commands which contain coordinates and dimensions and adjusts them accordingly, so that the status bar can be drawn efficiently without interfering with the shell and it's child programs.

shox's Issues

Shox wont download, instead it gives me error 3.

Here is a screeenshot.
When I try to run the install.sh script, it just wont work.

100% CPU usage

Hi,

Using the install script, I've got the latest release of shox in ~/bin, but when run it eats up one/two threads on a dual-core HT machine. I haven't let it run long or tested it otherwise. Any idea as to why this could be?

I'm running Debian 10, with Linux 5.5.0, zsh 5.7.1 with oh-my-zsh. Please let me know if you need any more information.

Flickers on Simple Terminal (st)

I'm not certain if this is a problem that you are able to fix or if this just a problem with the way that st handles rendering. However, every time the bar update there is a very noticeable flicker. I have only experienced this problem with shox so I suspect that you may be able to fix it.

Theme of shell in the screenshot

I was wondering what the theme of the shell you are using in the README screenshot? I've not seen it before and it looks nice!

Install script depends on jq and fails when not installed

--- shox/scripts ‹master› » bash install.sh                                                                                                                                                                                                                                                                                                                           127 ↵
Determining platform...
Finding latest release...
install.sh: line 8: jq: command not found
(23) Failed writing body

Would u consider adding network status?

I may want to know the upload and download speed sometimes when I am uploading or downloading a file. Would u consider adding network status also?

window terminal & powershell ?

description state , its universal
but i don't see any window or powershell ? varient .

Current install instructions seem to be broken.

Hi!

This seemed like a nice project and I was looking to trying it. That said, it looks like the install instructions might be outaded.

Looking at https://raw.githubusercontent.com/liamg/shox/master/scripts/install.sh

#!/bin/bash

set -e

echo "Determining platform..."
platform=$(uname | tr '[:upper:]' '[:lower:]')
echo "Finding latest release..."
asset=$(curl --silent https://api.github.com/repos/liamg/shox/releases/latest | grep -o "https://github.com/liamg/shox/releases/download/.*/shox-$platform-amd64" | head -n1)
echo "Downloading latest release for your platform..."
curl -s -L -H "Accept: application/octet-stream" "${asset}" --output ./shox
echo "Installing shox..."
chmod +x ./shox
installdir="${HOME}/bin/"
if [ "$EUID" -eq 0 ]; then
  installdir="/usr/local/bin/"
fi
mkdir -p $installdir
mv ./shox "${installdir}/shox"
which shox &> /dev/null || (echo "Please add ${installdir} to your PATH to complete installation!" && exit 1)
echo "Installation complete!"

This https://api.github.com/repos/liamg/shox/releases/latest seems to return

{
  "url": "https://api.github.com/repos/liamg/shox/releases/29853635",
  "assets_url": "https://api.github.com/repos/liamg/shox/releases/29853635/assets",
  "upload_url": "https://uploads.github.com/repos/liamg/shox/releases/29853635/assets{?name,label}",
  "html_url": "https://github.com/liamg/shox/releases/tag/v0.0.18",
  "id": 29853635,
  "node_id": "MDc6UmVsZWFzZTI5ODUzNjM1",
  "tag_name": "v0.0.18",
  "target_commitish": "master",
  "name": "v0.0.18",
  "draft": false,
  "author": {
    "login": "liamg",
    "id": 1187060,
    "node_id": "MDQ6VXNlcjExODcwNjA=",
    "avatar_url": "https://avatars1.githubusercontent.com/u/1187060?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/liamg",
    "html_url": "https://github.com/liamg",
    "followers_url": "https://api.github.com/users/liamg/followers",
    "following_url": "https://api.github.com/users/liamg/following{/other_user}",
    "gists_url": "https://api.github.com/users/liamg/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/liamg/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/liamg/subscriptions",
    "organizations_url": "https://api.github.com/users/liamg/orgs",
    "repos_url": "https://api.github.com/users/liamg/repos",
    "events_url": "https://api.github.com/users/liamg/events{/privacy}",
    "received_events_url": "https://api.github.com/users/liamg/received_events",
    "type": "User",
    "site_admin": false
  },
  "prerelease": false,
  "created_at": "2020-08-19T09:03:07Z",
  "published_at": "2020-08-19T09:03:39Z",
  "assets": [

  ],
  "tarball_url": "https://api.github.com/repos/liamg/shox/tarball/v0.0.18",
  "zipball_url": "https://api.github.com/repos/liamg/shox/zipball/v0.0.18",
  "body": "- Fix rendering on OSX and IntelliJ"
}

And this grep -o "https://github.com/liamg/shox/releases/download/.*/shox-$platform-amd64" | head -n1 wont match anything 😢

Install script fetches from releases URL which returns a rate limit response

Install script fails at the point where it fetches from releases. The url right now returns a rate limited response and the install script fails with a jq: error (at <stdin>:4): Cannot iterate over null (null) error

Provide as NPM package (or something)?

In order to be easily by the user. That would be handy! ✨

Current running program or window name

Is it possible to get the statusbar to show the application thats currently running in the terminal?

that would be a neat feature for tiling window manager users. When you run multiple terminals on one screen you need a way to very quickly distinguish them from one another.

tmux has such a feature but it's feature set is so retundand with tiling window managers that it's not worth using considdering the associated learning curve, configuration and workflow breakages.

If seen people make the tmux/screen comparison here and on hn and wholeheartedly disagree with shox beeing redundand. For me shox looks like a much more unixy tool would finally fit well into my workflow as a tiling window manager users. I'd use shox as a terminal headline of sorts.

max one bash helper supported

When multiple {bash} helpers are in a format string, the output of the first command is repeated for the rest.

This example produces a status bar with three segments, each printing 1.

format: "{bash: echo 1}|{bash: echo 2}|{bash: echo 3}"

(Neat project!)

Comparison with byobu

Hi,

FYI, this use case seems well covered by byobu, so it would be helpful to compare and contrast them in the readme.

ANSI escape sequence visible after running clear

After running clear I can see an ANSI character sequence printed to my terminal which I presume should be getting interpreted properly, also my prompt appears half way down the screen, this behaviour occurred in kitty and urxvt.

Scrollback often times ends up being unusable. The nature of the tool, or is there possibly a way to minimize it?

Hey there,
I was just checking out this utility, and it seems like I would like to use it, but there is one possibly overpowering issue. When using certain commands, it seems ones that scroll the screen a bit slower, and I try to scroll back to look at prior text, well, you can see demonstrated below.

For quicker commands that dump to the screen, it is not so bad, but you will see when I run my update && upgrade command where the issue resides.

Is there perhaps anything that can be done to eliminate this, or possibly minimize it at least, or is this just what I would have to deal with?

Thanks,
-MH

Event System

UpdateInterval being a time seems weird for certain things.

Take path based things like git. Sure we could check every second if the branch has changed but that seems silly since we could check after a command is ran. Of if the current working directory has changed etc.

Maybe in the future somekinda event based system would be useful?

It's a cool tool. Thanks for sharing.

weather plugin not working ?

Can someone point me to right direction with weather helper. I just cant make it work, i have tried various formats but none of them working.

im sending it as : {weather:%l: %t %c}

Create uninstall instructions