Getting Started

Getting Started (No Coding Required)

This page is for trying tuicc out and making it look/feel the way you want, without needing to read or understand any code. If you're comfortable with terminals but that's about it, this page is for you.

First launch, the short version

1. Make sure sway or i3 is already running — tuicc talks to a live window manager, it doesn't do anything on its own.
2. Install it:

   git clone https://github.com/Lshika-linux/tuicc
   cd tuicc
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Run it:

   python main.py

   • On sway, that's it — tuicc should open right away.
   • On i3, it won't connect yet — that's expected, see step 4.
4. i3 only: open ~/.config/tuicc/config.toml (created by the run in step 3), find provider = "sway" under [wm], change it to provider = "i3", save, and run python main.py again.

That's the whole setup. Everything below explains each of these steps in more detail, plus how to make tuicc launch with a keybind and look the way you want.

First launch, the long version

tuicc currently works on sway and i3 (other window managers are coming — see the main README). You need a working sway or i3 session already running.

Installing

Open a terminal and run these lines one at a time:

git clone https://github.com/Lshika-linux/tuicc
cd tuicc
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

That downloads tuicc and sets up everything it needs, in its own isolated folder — it won't interfere with anything else on your system.

Telling tuicc which window manager you use

Before running it for the first time, open ~/.config/tuicc/config.toml (it gets created the first time you run python main.py, so if it's not there yet, run tuicc once, close it, then come back to this step) and find the [wm] section near the top:

[wm]
provider = "sway"

If you use i3 instead, change that line to:

[wm]
provider = "i3"

Save the file. That's the only thing tuicc needs to know about your setup — everything else works the same either way.

Running it

Every time you want to open tuicc, from the tuicc folder:

source .venv/bin/activate
python main.py

(The source .venv/bin/activate part only matters if you opened a fresh terminal — you don't need it again if you're already in the same terminal window from the install step.)

Launching it with a keybind instead

Typing those two lines every time gets old. Most people bind a key in their sway or i3 config to pop tuicc open instantly, the same way you'd bind a key to open a terminal or app launcher. tuicc can't set this up for itself — it's a couple of lines in your WM's own config file, not tuicc's.

Open ~/.config/sway/config (or ~/.config/i3/config) and add:

bindsym $mod+grave exec kitty --class=tuicc --directory=/full/path/to/tuicc -e /full/path/to/tuicc/.venv/bin/python main.py
for_window [app_id="tuicc"] floating enable

i3 users: use class="tuicc" instead of app_id="tuicc" on that second line — i3 runs on X11, which doesn't have sway's app_id concept.

• Swap $mod+grave (Super + `) for whichever key combo you want.
• Swap kitty for whatever terminal you actually use — alacritty, foot, and most others accept the same --class=tuicc flag; check your terminal's manpage if it doesn't.
• Replace both /full/path/to/tuicc with wherever you cloned it in the Installing step above. Pointing straight at .venv/bin/python like this means you don't need source .venv/bin/activate first.
• Don't skip the for_window line — without it, tuicc opens as an ordinary tiled window and eats a slot in your layout instead of floating on top. See Config Reference for why, and how to make it open fullscreen too.

Reload your WM config ($mod+Shift+c by default) and try your new keybind.

Controls

Key	What it does
Tab	Move to the next item in the section you're currently in
Shift+Tab	Jump to a different section (workspaces, preview, launcher, connectivity, power menu)
Arrow keys	Move around — between windows in the preview, or back to the workspace list
Enter	Do the selected thing — switch to that workspace, focus that window, connect/disconnect wifi or bluetooth, launch an app, or run a power-menu action
any letter/number key	Start typing to open the launcher and search for an app, from anywhere
Ctrl+C	Close tuicc without doing anything (there's no dedicated quit key yet — this is an ordinary terminal interrupt)

If a power-menu action asks "Reboot now? Y/N" or similar, press y to confirm or n to cancel — this only happens for things that can't be undone, like rebooting or shutting down. (Those two letters are themselves configurable — see Config Reference — so press whatever your config actually binds if you've changed it.) Some power-menu actions also have a keyboard shortcut (shown next to the entry, like [^L]) that works from anywhere in tuicc, not just when that entry is selected.

The help menu, and moving things around live

Press F1 any time to open an in-app help menu — often faster than coming back to this wiki. Press 1, 2, or 3 to pick a page, Escape to back out:

1. Help — an FAQ covering the basics (really short right now), plus your actual current keybinds and power-menu shortcuts, read straight from your config so it's never out of sync with whatever you've customized.
2. Resize mode — a quick reference for the F2 mode described below.
3. Colors — a live editor for every [theme] color (see "Changing a color" below): arrow keys pick a role, Enter edits it in place, and you see the change applied immediately — no manual config.toml editing needed.

Press F2 on any module (Tab/Shift+Tab to it first, if it isn't already active) to enter resize mode: arrow keys resize it one terminal cell at a time, m switches to moving it instead of resizing, Delete removes the module entirely (asks y/n to confirm first), Enter keeps the change, Escape reverts it. F6 lets you spawn a module that isn't currently on screen and drops you straight into resize mode to place it. F3 saves your current layout as a new preset; F4 cycles to a different existing one. This is the easiest way to change tuicc's layout — no preset file to hand-edit.

Changing colors and other settings

Everything customizable lives in one plain text file:

~/.config/tuicc/config.toml

Open it with any text editor (even a simple one like nano ~/.config/tuicc/config.toml from the terminal, or a graphical text editor if you prefer). This file gets created automatically the first time you run tuicc — you don't need to make it yourself.

Changing a color

Find the [theme] section. Each line is one color you can change:

[theme]
accent = "cyan"
selected = "blue"
urgent = "red"

Change "cyan" to any of: black, red, green, yellow, blue, magenta, cyan, white. Save the file, then run python main.py again to see the change — it applies immediately, no reinstalling needed.

If you want a color that isn't in that list, you can also use a color code like "#7dd3fc" — if you don't know what that means, a quick web search for "hex color picker" will get you one to copy.

Changing what's in the power menu

Find the [[power_menu.action]] blocks — this is what you actually see when you jump to the power menu section. Each one looks like this:

[[power_menu.action]]
label = "Lock"
shortcut = "Ctrl+L"
icon = ""
command = "swaylock"
confirm = false
shell_true = false

• label is what you see on screen.
• shortcut is optional — a key like "Ctrl+L" that runs this action from anywhere in tuicc, and shows up next to the label automatically. Delete this line entirely if you don't want a shortcut for that action.
• command is what actually runs — if you know the terminal command for something (like locking your screen or opening an app), you can put it here.
• confirm = true makes it ask "are you sure?" first — good for anything you don't want to trigger by accident, like shutting down. You can also add confirm_text = "Shut down now?" to customize the question, otherwise it just shows Y/N.
• shell_true — leave this false unless your command needs things a plain command line doesn't have, like && to chain two commands together. Most commands (including all the defaults above) don't need it. Be careful with it: shell_true runs your command through a shell, so if malicious text ever ended up in your config, this is what would let it actually do damage. The preview still shows you the exact command before you run it (hover any power-menu entry) — worth a glance before pressing Enter on anything you didn't write yourself.

You can copy one of these blocks, paste it below the others, and change the details to add a new action.

(There's also a [[quick_actions.action]] section further down the file, with the same fields — it's not shown anywhere in the default layout yet, reserved for something more open-ended later. Editing it won't visibly do anything right now.)

If something breaks after you edit the config

The most common issue: if tuicc shows an error and won't start after you edit config.toml, you likely broke the file's formatting somewhere (a missing quote mark, for example). The safest fix:

rm ~/.config/tuicc/config.toml
python path/to/tuicc/main.py

This deletes your edited version and lets tuicc regenerate a fresh, working default — you'll need to redo your changes, including the provider line above if you'd set it to "i3", since the fresh default is "sway".

Want more detail?

• Config Reference — every single option, spelled out in full
• Keybindings — a deeper look at exactly how navigation decides where to go

If you get stuck on something this page doesn't cover, open an issue — genuinely, no question is too basic, and I will be most happy to help anyone!!