# rainbarf: a CPU and memory chart bar for the tmux status line

> rainbarf is a Perl command that draws a CPU utilization history chart, tinted by the memory breakdown, plus a battery indicator, and drops it into the tmux status line. It suits terminal users who want a live resource gauge in the bar they already look at, and it depends on colour support that not every terminal theme provides.

**creaktive/rainbarf** — it's like Rainmeter, but for CLI!

- Repository: https://github.com/creaktive/rainbarf
- Website: https://metacpan.org/module/rainbarf
- Stars: 1,209 · Forks: 65
- Language: Perl
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/creaktive-rainbarf

## One chart, two signals, one status line

rainbarf is a command line tool that draws fancy resource usage charts for the tmux status line, and the GNU screen equivalent. It is version 1.5, written in Perl, and the repository description puts it plainly: it's like Rainmeter, but for CLI. The visual design is one strip with two readings in it. The CPU utilization history chart is tinted with colours that reflect the system memory allocation, so the shape of the CPU curve and the memory state are read together rather than from two separate widgets. If available, the battery charge is displayed on the right. That combination is the whole idea, and it is why the tool fits a single line of a terminal rather than a panel. The homepage is the MetaCPAN page for the module, the topics cover battery, chart, cpu, graph, memory, monitoring, powerline, rainmeter, tmux and widget, and the last push was on 2026-08-15 with no GitHub releases published.

## The colour code is the memory breakdown

The tinting scheme is the part to learn first, because it turns the chart into a two-instrument display. Green means free memory. Yellow means active memory. Blue means inactive memory. Red means wired memory on Mac OS X and FreeBSD, and unaccounted memory on Linux, which is the same slot with a different meaning per operating system. Cyan means cached memory on Linux and buf on FreeBSD. Magenta is used swap memory. The `--order INDEXES` option controls the order of the memory usage bar, and the default is `fwaic`, which stands for free, wired, active, inactive and cached. If the `--swap` option is enabled the used swap amount is added to the total amount, but the free swap amount is not, which is a detail that changes how the bar is read when swap is in play.

## Wiring it into tmux, and the width arithmetic

The configuration is two lines in `~/.tmux.conf`:

```
set-option -g status-utf8 on
set -g status-right '#(rainbarf)'
```

Under GNOME Terminal the documented variant adds the colour flag:

```
set-option -g status-utf8 on
set -g status-right '#(rainbarf --rgb)'
```

After editing, reload the config with `tmux source-file ~/.tmux.conf`. The `#(...)` form is tmux's shell command substitution, so the chart is regenerated on every status refresh, and that is why the persistent data file exists. Width matters more than it looks. The chart width defaults to 38 so that both the chart and the battery indicator fit the status line, and higher values may require disabling the battery indicator or raising the `status-right-length` value in `~/.tmux.conf`. The same value comes up again in the colour caveat, where the remaining-time display needs `status-right-length` raised to 48.

## A config file, and command line options that win

Options can be persisted in `~/.rainbarf.conf`, one per line, and the example given is:

```
width=20   # widget width
bolt       # fancy charging character
remaining  # display remaining battery
rgb        # 256-colored palette
```

The precedence rule is simple: options given on the command line override the values in the configuration file. The configuration file path itself can be set through the `RAINBARF` environment variable, for example `RAINBARF=~/.rainbarf.conf rainbarf`. The option surface is small and mostly boolean pairs written as `--[no]something`, so `--[no]battery`, `--[no]remaining`, `--[no]bolt`, `--[no]bright`, `--[no]rgb`, `--[no]loadavg` and `--[no]swap`. The negative form is how you turn something off, and it is worth knowing because a setting baked into `~/.tmux.conf` is otherwise hard to override from a one-off shell run.

## Load average mode and the max threshold

The default metric is CPU utilization, but the `--[no]loadavg` option switches the chart to the load average metric instead, and it is disabled by default. The documentation flags a practical consequence: because the load average is an absolute value with varying ranges on different systems, you might want to set the `--max` threshold. The maximum is the load average you expect before the chart rescales, and the default is 1. That default makes sense for a percentage-style utilization reading and is wrong for a load average, where a single core fully busy reads as 1 and a multi-core machine routinely sits higher. This is a case where the tool defaults sensibly for the common case and needs one extra flag for the other case, and where the threshold semantics are not obvious from the name.

## The colour caveat is the real limitation

If you see the memory usage bars but no CPU utilization chart, the cause is that the terminal's colour scheme needs an explicit distinction between foreground and background colours. On terminals that lack it, red on a red background is drawn as a solid red block. The fix has two routes and they conflict. The first is the ANSI bright attribute, offered as `--[no]bright`, but other colour schemes, notably solarized, give the bright attribute a different meaning, so the result is described as quite psychedelic. The second route is the 256-colour palette, enabled with `--rgb`, which sidesteps the bright attribute problem. There is a wrinkle: older versions of the Term::ANSIColor dependency do not recognise bright or RGB settings and fall back to plain 16 colours, though the dependency is optional and is only needed to preview the effect of the options before editing `~/.tmux.conf`. The documented guarantee is that `rainbarf --bright --tmux` works despite the outdated Term::ANSIColor, because the real rendering happens in tmux rather than in the preview.

## Persisted history and the skip threshold

CPU utilization stats are persistently stored in the `~/.rainbarf.dat` file, and every rainbarf execution updates and rotates it. That file is what makes the chart a history rather than an instantaneous reading, and it is also the mechanism that makes the tool usable in a status line, since tmux calls the command repeatedly and the chart fills in as the file accumulates samples. The `--datfile FILENAME` option changes where that file lives, and the `--skip NUMBER` option controls write frequency: do not write CPU stats if the file already exists and is newer than this many seconds, which the documentation says is useful if you refresh the tmux status quite frequently. Without it, a fast status refresh means a lot of redundant writes to a file that is only read a few characters at a time.

## Conclusion

Adopt rainbarf if you spend your day in tmux and want CPU, memory and battery state in the status bar without opening a dashboard. Skip it if your terminal theme cannot distinguish foreground from background colours, because the memory bars will be unreadable without the bright attribute or the 256-colour palette, and skip it if you need per-process detail rather than a system-level bar. Before adding it to ~/.tmux.conf, remember that CPU history is persisted in ~/.rainbarf.dat, that the chart width defaults to 38 so it fits the status line, and that the `status-right-length` value has to be raised if you enable the remaining-time indicator.

## FAQ

### How do I install rainbarf?

You can build it from source with perl Build.PL, ./Build test and ./Build install, install it with `brew install rainbarf` or `port install rainbarf`, install the CPAN module with `cpan -i App::rainbarf`, or install from GitHub with `cpanm git://github.com/creaktive/rainbarf.git`.

### How do I add rainbarf to my tmux status line?

Add `set-option -g status-utf8 on` and `set -g status-right '#(rainbarf)'` to your ~/.tmux.conf, then reload it with `tmux source-file ~/.tmux.conf`. Under GNOME Terminal the documented variant uses `set -g status-right '#(rainbarf --rgb)'`.

### What do the colours in the rainbarf chart mean?

Green is free memory, yellow active memory, blue inactive memory, red wired memory on Mac OS X and FreeBSD or unaccounted memory on Linux, cyan cached memory on Linux or buf on FreeBSD, and magenta is used swap memory. The order of the memory bar is controlled with --order and defaults to fwaic.

### Why is the CPU chart not showing in my terminal?

The terminal colour scheme needs an explicit distinction between foreground and background colours, otherwise red on a red background is drawn as a red block. You may need the ANSI bright attribute via --bright, though that looks psychedelic under schemes like solarized, or the 256-colour palette via --rgb, which is unaffected by the bright attribute issue.

### Where does rainbarf store its CPU history?

In ~/.rainbarf.dat by default, which you can change with --datfile. The --skip option prevents writing stats when the file already exists and is newer than the given number of seconds, which helps if you refresh the tmux status frequently.

## Sources

- [creaktive/rainbarf on GitHub](https://github.com/creaktive/rainbarf)
- [Issues](https://github.com/creaktive/rainbarf/issues)
- [Project website](https://metacpan.org/module/rainbarf)
- [README](https://github.com/creaktive/rainbarf/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/creaktive-rainbarf