{"id":13425041,"url":"https://github.com/liamg/shox","last_synced_at":"2025-04-04T07:09:24.003Z","repository":{"id":41363585,"uuid":"242812587","full_name":"liamg/shox","owner":"liamg","description":"🍫 A customisable, universally compatible terminal status bar","archived":false,"fork":false,"pushed_at":"2024-01-25T16:38:07.000Z","size":10859,"stargazers_count":721,"open_issues_count":14,"forks_count":23,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-28T06:09:37.549Z","etag":null,"topics":["customisation","customization","status-bar","terminal"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liamg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-24T18:34:39.000Z","updated_at":"2025-03-27T09:47:34.000Z","dependencies_parsed_at":"2022-09-06T03:02:07.769Z","dependency_job_id":"5b4e8069-a2f6-4451-9453-ed81984d98bf","html_url":"https://github.com/liamg/shox","commit_stats":{"total_commits":43,"total_committers":4,"mean_commits":10.75,"dds":"0.11627906976744184","last_synced_commit":"79f64da5434be30ac8f05fc9dc5aadb314fcb25b"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liamg%2Fshox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liamg%2Fshox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liamg%2Fshox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liamg%2Fshox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liamg","download_url":"https://codeload.github.com/liamg/shox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135146,"owners_count":20889421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["customisation","customization","status-bar","terminal"],"created_at":"2024-07-31T00:01:03.049Z","updated_at":"2025-04-04T07:09:23.976Z","avatar_url":"https://github.com/liamg.png","language":"Go","readme":"# Shox: Terminal Status Bar\n\n[![Travis Build Status](https://travis-ci.org/liamg/shox.svg?branch=master)](https://travis-ci.org/liamg/shox)\n[![GoReportCard](https://goreportcard.com/badge/github.com/liamg/shox)](https://goreportcard.com/report/github.com/liamg/shox)\n[![Github Release](https://img.shields.io/github/release/liamg/shox.svg)](https://github.com/liamg/shox/releases)\n\nA customisable terminal status bar with universal shell/terminal compatibility. Currently works on Mac/Linux.\n\n![](./screenshot.png)\n\n## Installation\n\n**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!\n\n```bash\ncurl -s \"https://raw.githubusercontent.com/liamg/shox/master/scripts/install.sh\" | sudo bash\n```\n\nIf 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.\n\n## Configuration\n\nThe 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`\n\nThe config file looks like the following:\n\n```yaml\nshell: /bin/bash\nbar:\n    format: \"{time}||CPU: {cpu} MEM: {memory}\"\n    colours: \n      bg: red\n      fg: white\n    padding: 0\n```\n\nShox 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.\n\n### Bar Configuration\n\nBar 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.\n\n#### Alignment\n\nYou 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.\n\nFor example, to display a bar that centre aligns the time, you could use `|{time}|` \n\n#### Colours\n\nThe following colours are available: `black`, `white`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`,  `darkgrey`, `lightgrey`, `lightred`, `lightgreen`, `lightyellow`, `lightblue`, `lightmagenta`, `lightcyan`.\n\n#### Helpers\n\nHelpers 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.\n\n| Helper  | Description                                       | Example Config     | Example Output |\n|---------|---------------------------------------------------|--------------------|----------------|\n| time    | Show current time                                 | {time}             | 11:58:17       |\n| cpu     | Show current CPU usage                            | {cpu}              | 20%            |\n| memory  | Show current memory usage %                       | {memory}           | 20%            |\n| battery | Show current battery charge %                     | {battery}          | 20%            |\n| bash    | Run a custom bash command                         | {bash:echo hi}     | hi             |\n| weather | Show current weather (provided by http://wttr.in) | {weather:1}        | 🌧 +6°C         |\n| until   | Show time remaining until a given unix timestamp  | {until:1583255109} | 13m26s         |\n\n\nIdeally this list would be much longer - please feel free to PR more helpers! You can see simple examples [here](https://github.com/liamg/shox/tree/master/pkg/helpers).\n\n##### Weather\n\nThe configuration section of the weather helper holds the display format.\nFor all available display formats please visit\n[chubin/wttr.in#one-line-output](https://github.com/chubin/wttr.in#one-line-output)\nThe default value is `1` which only shows the weather\n\n\u003e **_NOTE:_** You don't need to URL-encode the weather format, i.e. use `%l: %c %t` instead of `%l:+%c+%t`\n\n## Uninstallation\n\n### If installed with `sudo`\nRemove the binary from `/usr/local/bin`\n```bash\nrm /usr/local/bin/shox\n```\n\n### If installed without `sudo`\nRemove the binary from the shox installation dir `$HOME/bin`\n```bash\nrm $HOME/bin/shox\n```\n\n\u003e **_NOTE:_** Don't forget to remove any configuration files you've created should you decide you don't need them\n\n## Why?\n\nI frequently needed a way to have a quick overview of several things without cramming them into my PS1, and to update those things dynamicly.\n\n## How does it work?\n\nShox 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.\n","funding_links":[],"categories":["Go","terminal"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliamg%2Fshox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliamg%2Fshox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliamg%2Fshox/lists"}