A generator for the i3 status bar.

Upstream URL


Yukari Hafner <>


Yukari Hafner <>



About Cari3s

This is an i3 status bar generator library/program.

How To

First make sure Cari3s is available to ASDF by either cloning and registering it, or downloading it via Quicklisp. Then build a standalone binary of Cari3s like this:

sbcl --eval "(asdf:make :cari3s)"

This should produce a binary called cari3s in the source directory. Copy or symlink it into your PATH.

Next, create a configuration file in ~/.config/i3/cari3s.conf with something like the following:


Then change your ~/.config/i3/config's status bar section and set the status_command to cari3s:

bar {
  status_command cari3s

Once you reload i3, it should display a status bar similar to the following:


In the above example we defined five generators. The following generators are available out of the box:

  • battery
  • clock
  • cpu-usage
  • disk-usage
  • io-usage
  • mem-usage
  • network-ip
  • uptime
  • weather

The look of each of them can be customised through the :text format string, and the :markup pango options, as well as a variety of extra options for blocks.

Defining new Generators

Defining a raw generator is just a matter of subclassing generator and providing a method for generate that, when invoked, returns a list of block instances that should be displayed on the status bar.

There's some helper classes available like the single-generator and the value-generator, as most generators will only produce a single block and produce their text based on some recomputed value every time.

For the value-generator all you need to implement is a method on compute-value and provide a sensible default :text initarg.

None of the existing generators are terribly complicated, so if you're still unsure what to do, have a look at their sources.

Interfacing with Cari3s

Cari3s includes a TCP server that can be used for RPC. By default the server listens on port 2424. It uses a simple UTF-8 protocol that works on a per-line basis. Each line sent by a client should be formatted something like this:

echo :message "hi!"

The server will reply in the same format. See serialize-object for the complete format spec. You can use this interface in order to interface with and extend Cari3s with other applications.

Dependencies (7)

  • cffi
  • closer-mop
  • documentation-utils
  • drakma
  • jzon
  • pango-markup
  • usocket

Dependents (0)

    • GitHub
    • Quicklisp