Skip to content
[unmaintained] inter-process communication with i3, the improved tiling window manager.
Ruby Shell
Find file
Failed to load latest commit information.
bin add first version
dist Update aur pkgbuild.
examples Updated example to use new constant name.
lib Update to version 0.2.0
man Update to version 0.2.0
test New (working) tests.
.gitignore Update to version 0.2.0
Gemfile Update to version 0.2.0 version bump to 0.1.4
LICENSE add first version
README.markdown Add notice that this project is mostly dead.
Rakefile No gemspec build for now.
i3-ipc Update to version 0.2.0




This code is old, largely untested and might not even support all features provided by the IPC protocol. I don't have the time to develop this further.

But there is another project that provides a great abstraction of all the IPC stuff: i3ipc-glib.

It's possible to use this library in ruby using gir_ffi and the following code:

require 'gir_ffi'

namespace = 'i3ipc'
GirFFI.setup namespace

i3 =

i3.command 'focus left'

inter-process communication with i3, the improved tiling window manager.



gem install i3-ipc

Old school (for the cli script only):

curl -s > i3-ipc &&
chmod 755 i3-ipc &&
mv i3-ipc /usr/local/bin/i3-ipc

If you're on Arch Linux, you can use the AUR package:

curl &&
makepkg -i


i3-ipc -t 1
i3-ipc -t 1 -p
i3-ipc -t 3 -j
i3-ipc "exec xterm"

Read the man-page for more information.


As of commit 3db4890 i3 added events. For now there's only two events: workspace and focus.

According to the documentation:

workspace Sent when the user switches to a different workspace, when a new workspace is initialized or when a workspace is removed (because the last client vanished). output Sent when RandR issues a change notification (of either screens, outputs, CRTCs or output properties).

i3-ipc uses EventMachine to receive and handle these events.

With i3-ipc's interface and EventMachine as its backend it's rather easy to subscribe to this event notifying:

I3::IPC.subscribe [:workspace] do |em, type, data|
  # ...

There are 3 arguments passed to the block:

  • em is the instance of the EM::Connection class. To send data to the socket, you need to use em.send_data.
  • type is the received message type. This could be one of
  • data is the received data, already parsed.

For example you can use the following code to get the actual focused screen:

I3::IPC.subscribe [:workspace] do |em, type, data|
  case type
  when I3::IPC.message_type_get_workspaces
    data.each do |e|
      if e["focused"]
        puts "focused: %s" % e["name"]
        puts "unfocused: %s" % e["name"]
    em.send_data I3::IPC.format(I3::IPC.message_type_get_workspaces)

A full example of how this can be used for the workspace bar can be found in the examples directory.

You can use EM.stop to stop the connection.

What needs to be done?

  • cleanup the subscribtion frontend
  • write tests


Once you've made your great commits:

  1. Fork the project.
  2. Create a topic branch - git checkout -b my_branch
  3. Push to your branch - git push origin my_branch
  4. Create an Issue with a link to your branch
  5. That's it!


Copyright (c) 2010 Jan-Erik Rediger. See LICENSE for details.

Something went wrong with that request. Please try again.