README.md

i3 window manager + Node.js

This Node.js package allows to talk with i3 window manager using IPC interface.

No dependencies, no unecessary abstractions. Just simple, modern API.

Source code is only one file with clear comments and references to excellent i3wm docs.

Install

npm install i3wm

Examples

Connect to i3

const i3wm = require('i3wm')

i3wm.Client.connect().then(client => {
  console.log('Conneceted')
})

// or

const client = await i3wm.Client.connect()

You can also use custom binary by passing additional options to connect. For example: connect({ bin: 'sway' }).

Subscribe to events

client.subscribe('window', 'workspace')

client.on('window', msg => {
  if (msg.change === 'focus') {
    console.log('Jumping around')
  }
})

Messages

// Subscribe, payload is serialized
await client.message('subscribe', ['window'])

// Get tree of all windows and workspaces
const tree = await client.message('get_tree')

// send multiple commands in one go
const [r1, r2] = await client.message('run_command', 'workspace 0; mark m')

Possible messages can be found in source code and man i3-msg.

Commands

Use command() to send a command and get unwraped reply.

// Mark current window with 'm'
await client.command('mark m')

// command() throws on incorrect input
client.command('BLAH')
  .catch(err => console.log('Incorrect: ': err.input))

Disconnect

i3wm.Client.disconnect(client)