tmux-cpu-rs

A small, fast Rust-based CLI tool to display CPU usage inside your tmux status line — with caching for efficiency, and optional gradients & formatting.

Platform Support

Linux only - This tool reads CPU statistics from /proc/stat and only works on Linux systems.

Tested and supported architectures:

• x86_64 (64-bit Intel/AMD)

Untested architectures:

• aarch64 (64-bit ARM)
• armv7 (32-bit ARM)
• i686 (32-bit Intel/AMD)

Note: tmux-cpu-rs should still work on untested architectures, since there's no architecture specific code.

Features

• ✅ Accurate CPU usage using /proc/stat
• 🎨 Color gradients from green (low) to red (high) CPU usage
• 🖋 Customizable formatting with tmux-like format strings
• ⚡ Caching for minimal system overhead
• 🛠 Raw output mode for re-use in scripts
• 🔧 Configurable precision for f64-based stats

Installation

Using cargo:

cargo install tmux-cpu-rs

Or clone and build manually:

git clone https://github.com/playbahn/tmux-cpu-rs
cd tmux-cpu-rs
cargo build --release

Or you can grab pre-built binary(s) from the Releases page.

Usage

Usage: tmux-cpu-rs [OPTIONS] <PID>

Arguments:
  <PID>  Pass in #{client_pid}

Options:
  -H, --no-hook          Disable setting of cache removal hooks (`client-detached` and `session-closed`)
  -p, --precision <NUM>  f64 precision to use for displayed stats [default: 0]
  -w, --width <NUM>      Minimum width (right-aligned with spaces) for usage string [default: 0]
  -b, --before <FORMAT>  Tmux-like format strings to place before usage string (see below)
  -a, --after <FORMAT>   Tmux-like format strings to place after usage string (see below)
  -r, --raw              Get CPU usage and gradient in a "raw" reusable format (see below)
  -c, --cachedir <DIR>   Directory to cache stats in [default: /tmp/tmcpu/]
  -h, --help             Print help
  -V, --version          Print version

...

Formatting

--before and --after take tmux-like format strings where:

1. Embedded style strings are marked with @[] instead of #[], and

2. Every match for the exact pattern HEXGRAD inside @[] is replaced by a color from Hue 120 degrees (green) to Hue 0 degrees (red), going from low to high usage.

Multiple --before (and --after) options can also be specified, in which case the format strings are concatenated in order of occurrence.

Example

set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} -p1 -b '@[fg=HEXGRAD]') "

With a low CPU usage, the above will render as:

Raw Output

When using --raw, the output format becomes:

USAGE\nHEXGRAD

where:

• USAGE is the numeric CPU usage
• \n is the Unicode U+000A newline character
• HEXGRAD is the computed color (hex string)

This is useful if you want to build your own custom tmux formatting or use the values in other scripts.

Example tmux Integrations

1. Adding a percent sign after usage:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} --precision 1 --after %) "
   

   

2. With gradients turned on:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} -p1 --before '@[fg=HEXGRAD]' -a%) "
   

   

3. tmux-cpu-rs emits plain tmux format strings. So, styles are persistent:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} -b '@[fg=HEXGRAD]' -a%)"
   set -ga status-right " #[reverse] #H #[noreverse]"
   

   

   This will have to be resolved by resetting the style with either the --after option:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} \
   -b '@[fg=HEXGRAD]' -a '%@[fg=default]') \
   #[reverse] #H #[noreverse]"
   

   or with an embedded style string before the next text:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} \
   -b '@[fg=HEXGRAD]' -a% \
   ) #[fg=default,reverse] #H #[noreverse]"
   

   

4. --raw:

   path/to/tmux-cpu-rs $(tmux display -p '#{client_pid}') --raw
   

   

5. With Nerd Font (Powerline) half circles:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} \
   -p1 \
   -b '@[fg=HEXGRAD]\uE0B6' \
   -b '@[reverse,bold]\uF4BC ' \
   -a '@[noreverse]\uE0B4' \
   ) #[fg=default]\uE0B6#[reverse,bold]#H#[noreverse]\uE0B4"
   

   

6. With Nerd Font (Powerline) right dividers:

   set -g status-right "#(path/to/tmux-cpu-rs #{client_pid} \
   -p2 -w4 \
   -b '@[fg=HEXGRAD]\uE0B2' \
   -b '@[reverse,bold] \uF4BC ' \
   -a ' @[noreverse,bg=#14b5ff]\uE0D6'\
   )#[fg=default,bg=default,reverse,bold] #H "
   

   

Note

Unicode escape sequences in the form given above are only rendered as glyphs if they're parsed by tmux. In other words, this works at the tmux command prompt or .tmux.conf:

display "A\uE0B2B"

But at the (bash) shell command prompt or a (bash) shell script, it will need to be written as:

tmux display "A"$'\uE0B2'"B"

Fun reads (?)

How it works and stuff

Firstly, tmux-cpu-rs runs only when it's invoked with #(). It is as "frequent" as the status-interval your client is using. Users with lower status-intervals (say 1 second) will see more sensible stats than users with a higher status-interval (say 5 second).

The first time it is invoked it finds no past or "old" stats, so it only caches the current stats in a temp file with the name XYZ for a passed client_pid of XYZ) in the cachedir¹, and sets (appends) two hooks² at client-detached and session-closed for the removal of that cache file.

For every subsequent run it updates the cache, and prints new usage stats to stdout.

Additionally, you could also redirect the stderr of tmux-cpu-rs inside the same #() with 2> /tmp/tmcpu.log if something's not working.

ANOTHER CPU usage monitor?

While looking for a CPU usage monitor for my tmux statusline, I looked through some options, but was kind of annoyed by the fact that all (couldn't have been more than one or two) of them sleep every time tmux evaluates #()'s. Taking a noticeable time to end execution, throwing away current values, I wasn't happy. So, I wrote one in Rust that cached current stats in /tmp for the next delta calculation for CPU usage. I looked once more, and found tmux-plugins/tmux-cpu. Although tmux-cpu-rs is not a rewrite of the CPU portion of tmux-plugins/tmux-cpu (they also have a GPU portion), they're quite similar, as they both use caching. Then, I thought "let's make it use-able by people" and here we are. I would say the (deemed) selling point of tmux-cpu-rs would be caching.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.