An improved JavaScript library to control i3wm
Switch branches/tags
Clone or download
acrisci Add merge notice to readme
This library will be merged into the main project, i3ipc-GLib
( soon in the v1.0.0 release of
that project.
Latest commit c2f5dbf Oct 16, 2014


An improved JavaScript library to control i3wm.


This library will be merged into the main project, i3ipc-GLib soon in the v1.0.0 release of that project.


i3's interprocess communication (or ipc) is the interface i3wm uses to receive commands from client applications such as i3-msg. It also features a publish/subscribe mechanism for notifying interested parties of window manager events.

i3ipc-gjs is a JavaScript library for controlling the window manager. This project is intended to be useful for general scripting, and for applications that interact with the window manager like status line generators, notification daemons, and pagers.

If you have an idea for a script to extend i3wm, you can add your script to the examples directory or post a script request on the project issue tracker.


The latest documentation can be found here. i3ipc-gjs is a GObject introspection library (kind of like gtk).


i3ipc-gjs requires i3ipc-GLib and Gjs.

Then simply do:

sudo make install

Or get someone to host a package for your distro.


#!/usr/bin/env gjs

const i3ipc =;

// Create the Connection object that can be used to send commands and subscribe
// to events.
let conn = new i3ipc.Connection;

// Query the ipc for outputs. The result is a list that represents the parsed
// reply of a command like `i3-msg -t get_outputs`.
let outputs = conn.get_outputs();

print('Active outputs:');

outputs.forEach(function(o, i) {
    if (

// Send a command to be executed synchronously.
conn.command('focus left');

// Define a callback to be called when you switch workspaces.
let on_workspace = function(self, e) {
    // The first parameter is the connection to the ipc and the second is an object
    // with the data of the event sent from i3.
    if (e.current) {
        print('Windows on this workspace:');
        e.current.descendents().forEach(function(w) {

// Subscribe to the workspace event
conn.on('workspace', on_workspace);

// Start the main loop and wait for events to come in.


We should do what we can to make this library as JavaScript-like as good tastes allows. New features should be implemented on the main project at i3ipc-GLib.


This work is available under the GNU General Public License (See COPYING).

Copyright © 2014, Tony Crisci

All rights reserved.