Skip to content
A generator for the i3 status bar.
Common Lisp
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

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.

You can’t perform that action at this time.