#i3 #sway #status #status-command

nightly bin+lib istat

A lightweight and batteries-included status_command for i3 and sway

14 releases (5 breaking)

0.6.0 Aug 15, 2023
0.5.1 Jun 25, 2023
0.4.0 Jun 16, 2023
0.3.0 Jun 6, 2023
0.1.5 May 21, 2023

#170 in Hardware support

Download history 35/week @ 2023-06-11 19/week @ 2023-06-18 34/week @ 2023-06-25 36/week @ 2023-07-02 5/week @ 2023-07-09 12/week @ 2023-07-16 14/week @ 2023-07-23 2/week @ 2023-07-30 33/week @ 2023-08-06 36/week @ 2023-08-13 14/week @ 2023-08-27 40/week @ 2023-09-03 6/week @ 2023-09-10 6/week @ 2023-09-17 3/week @ 2023-09-24

55 downloads per month


7.5K SLoC

istat: an i3 (or sway) status_command

I used to use i3blocks for i3's status_command, but I found that having all my configuration in separate scripts was getting a little cumbersome.

That, and also I could never find a good block for volume control that wasn't janky or slow.

So, I decided to write my own status_command generator, and what better language to write it in than Rust!


  • ⚡ completely single threaded (less resource usage)
    • 🔎 it's a status command, it shouldn't be heavy
  • ⏩ powerline theming and customisability
  • 🎮 ipc control
    • 🖱️ send click events via a command
    • ♻️ refresh items with a command
    • 📜 custom events for some integrations (e.g., controlling PulseAudio/PipeWire, etc)
    • 🤯 runtime updates - no restart required
  • 🖇️ many different bar items (continue reading for screenshots)

Each bar item is configurable, see the sample config for options.


Here's an image of a bar in i3:

screenshot of i3bar

And another one which powerline mode set:

screenshot of i3bar with powerline

This table contains screenshots of some bar items:

item description screenshots
battery Percentage, charging, etc. Supports multiple batteries.
cpu Usage expressed as a percentage
disk Usage, shows free disk space. Supports multiple mount points.
dunst Displays "do not disturb" status (if it's paused or not) off (invisible)
kbd Displays CapsLock/Numlock/etc states
krb Checks if a valid kerberos token exists (like klist -s)
mem Display free memory as bytes or as a percentage
net_usage Upload and download statistics
nic Network interface status - connection state and ip addresses
pulse Input/output volume status, full control and current speaker type (jack, bt, etc)
script Run arbitrary scripts and show their output
sensors Temperature sensors
time Displays the current date and/or time


With Rust (via cargo):

cargo install istat
# Make sure to look at the `sample_config.toml` file for configuration options

Via the AUR (Arch Linux):

paru -S istat


Setting it up

First, create a config file for istat. View the sample config for what's available. This file should be placed in:

  • $XDG_CONFIG_HOME/istat/<here>, or
  • $HOME/.config/istat/<here>

Even though the sample configuration file is a TOML file, YAML and JSON are also supported.

Then, update your i3/sway config to use istat as the status_command:

bar {
        status_command istat
        # ... other config

Interacting with istat

istat offers multiple ways of interacting with it:

  • standard click events from i3/sway
  • real-time signals
  • it's own ipc


Consider the following bar item which outputs the state of the CapsLock and NumLock keys:

type = "kbd"
show = ["caps_lock", "num_lock"]
interval = "30s"

It refreshes every 30 seconds, or every time the bar item receives a click event. That's alright, but we can do better with signals. Adding signal = 8 to the config, and removing interval we get:

type = "kbd"
show = ["caps_lock", "num_lock"]
signal = 8

Now, whenever istat receives the SIGRTMIN+8 signal, the bar item will be refreshed. Pair this with the following config in i3/sway, and you'll have a bar item that reflects your keys all the time:

bindsym --release Caps_Lock exec --no-startup-id pkill -RTMIN+8 istat
bindsym --release Num_Lock  exec --no-startup-id pkill -RTMIN+8 istat

Linux offers many realtime signals, to see which your machine supports the istat-signals command is provided:

$ istat-signals

The same signal can be configured for multiple bar items, so you many can be refreshed with the same signal!

Custom IPC events

The command istat-ipc is provided to interface with istat. It supports:

  • fetching the name and index of all the currently running bar items
  • refreshing all bar items at once
  • sending click events to each bar item
  • sending custom events to bar items
    • some bar items (like pulse) expose an advanced API which can be accessed with these events

Refresh all bar items at once:

istat-ipc refresh-all

Send a click event to a bar item - without actually clicking it!:

# emulate a left click on the disk item:
istat-ipc click disk left

Control PulseAudio/Pipewire via custom IPC events:

# see all the custom events that pulse has to offer:
istat-ipc custom pulse

# Some examples:

# turn the output (speakers) volume up
istat-ipc custom pulse volume-down sink
# turn the input (microphone) volume down
istat-ipc custom pulse volume-up   source
# mute or unmute the output
istat-ipc custom pulse mute-toggle sink


See the justfile!

Also give IDEAS.md a read too.


~523K SLoC