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.

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.

What you need first

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.)

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, quick actions)
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, or run that quick action
q	Close tuicc without doing anything

If a quick action asks "Run Shutdown? Y/N" or similar, press y to confirm or n to cancel — this only happens for things that can't be undone, like shutting down.

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 quick actions are available

Find the [[quick_actions.action]] blocks near the bottom of the file. Each one looks like this:

[[quick_actions.action]]
label = "Lock"
icon = ""
command = "swaylock"
confirm = false

• label is what you see on screen.
• 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 copy one of these blocks, paste it below the others, and change the details to add a new action.

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 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.

What you need first

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.)

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. 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.

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

• 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.

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 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!!