Skip to content

Getting Started

Jump to bottom
Lshika edited this page Jul 28, 2026 · 11 revisions

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.

# 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](https://github.com/Lshika-linux/tuicc)). 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](https://github.com/Lshika-linux/tuicc/issues) — genuinely, no question is too basic.

Clone this wiki locally