bspcq, q for query

A bspc analyzer (utility for bspwm)

This is a small program that prints a user friendly, visual representation, of your current bsp tree.

The aim is to assist in using bspwm so new users have an easier time getting into tiling window managers, and have some toys to play with.

It's essentially the same as running:

bspc query -M -m <monitor-name> | jq

Except there are fewer parameters, a less complex syntax to remember and an intuitive visual.

Installation

I'd recommend just copying the script from the root of this directory, bspcq, and changing the shebang.

git clone https://github.com/aidenlangley/bspcq
mv bspcq/bspcq ~/bin/bspcq # or ~/.local/bin/bspcq
chmod +x ~/bin/bspcq

Then edit the shebang - my shebang:

#! /usr/bin/env python3.10

Your shebang might need to be be:

#! /usr/bin/env python3

Dependencies

In addition, some Python modules are required, as is xtitle.

rich

rich is responsible for the nicely formatted tree.

python -m pip install rich

xtitle

xtitle assists in getting the title name of a node/window in X.

Requires C/C++ development tools, varies by distro.

git clone https://github.com/baskerville/xtitle
cd xtitle
make && make install

I've actually included it here, under contrib, so you can just copy it to ~/bin.

Via pipx

https://pypi.org/project/bspcq/

python -m pipx install bspcq

Upgrade

python -m pipx upgrade bspcq

Usage

# Prints the full tree, including output from all monitors.
bspcq

# Provides a simpler view, perfect for finding window class names.
bspcq -s

# Grabs info on all nodes that belong to the specified domain.
bspcq -M/D/N

# For a simplified view.
bspcq -M/D/N -s

# Passes through a query to `bspc query` and prints our tree, valid identifiers
# are names, ID's or the address output by `bspc -M/D/N`.
bspcq -m/d/n <monitor/desktop/node-identifier>

Preview

Plans

My goals currently are to:

• Align bspcq as closely as possible with bspc query. I would like for bspcq to behave almost identically to bspc query - it just adds a visual element.
• Remain as lean as possible. A nice-to-have feature would be 0 reliance on external libraries, so I'd like to remove rich and implement a way to display the tree myself.

This was just an afternoon project that's turning into a week long project since it's quite a lot of fun!