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

Want the absolute fastest path instead? Skip to Quick install below — one command does steps 2-4 here for you, plus the keybind-toggle setup from "Launching it with a keybind instead". The steps below are for understanding what's actually happening, or if you'd rather do it by hand.

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.

Heads up: running python main.py directly like this is fine for a first look, but it's not how you're meant to use tuicc day-to-day — see "Launching it with a keybind instead" below for the real setup (launch once, toggle with a keybind).

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.

Quick install

The fastest way to get tuicc running as your actual daily-driver setup — not just a one-off look — is one command:

curl -fsSL https://raw.githubusercontent.com/Lshika-linux/tuicc/main/install.sh | bash

This does everything the manual sections below walk through by hand, including the keybind toggle from "Launching it with a keybind instead":

• Clones tuicc into ~/.local/share/tuicc and sets up its own venv.
• Detects whether you're running sway or i3 (asks if it can't tell).
• Asks which terminal to run tuicc in, and what keybind should summon it — sensible defaults for both (whichever terminal you're running the installer from, and $mod+Tab).
• Asks whether tuicc should show fullscreen or as a plain floating window. Fullscreen is the default — a fresh install gives you the full experience right away, no WM-config tweaking needed first; floating is a tweak you can opt into later (see Config Reference's fullscreen_only).
• Writes all of that into ~/.config/tuicc/config.toml for you, and installs a ready-made toggle script to ~/.local/bin/tuicc_toggle.py.
• Shows you the exact WM config block it wants to add and asks before touching your WM config — say no and it just prints the block for you to paste in and reload yourself. Never edits anything silently.

Re-running it later is safe: it git pulls the existing checkout instead of re-cloning, and never overwrites a config.toml you already have.

Prefer to see exactly what it does before running it, or don't want to pipe a script straight into bash? Download it first, read it, then run it yourself:

curl -fsSL https://raw.githubusercontent.com/Lshika-linux/tuicc/main/install.sh -o install.sh
bash install.sh

Everything from here down walks through what that script does, by hand — useful for understanding the pieces, customizing something the installer doesn't ask about, or if you'd rather not run someone else's script sight-unseen at all.

Installing

The manual, step-by-step version — if you just want it running as fast as possible, use Quick install above instead. Otherwise, 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

For a quick first test, 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.) That's fine for trying tuicc out, but relaunching it fresh from scratch every time isn't how it's meant to be used day-to-day — see the next section.

Launching it with a keybind instead

tuicc is meant to run as one long-lived process that your WM shows and hides, not something you relaunch each time you want it. The real setup: launch tuicc once (by hand, or from your WM's startup config), then bind a key that toggles its window in and out of view — it stays running in the background the whole time, ready instantly the next time you summon it. tuicc can't set this up for itself — it's a couple of lines in your WM's own config file, not tuicc's.

Here's the plain sway version — tagged with a stable identity (tuicc_scratch) so the WM config can target its window specifically:

# ~/.config/sway/config
exec kitty --app-id tuicc_scratch -e python /full/path/to/tuicc/main.py
for_window [app_id="tuicc_scratch"] move scratchpad
bindsym $mod+grave [app_id="tuicc_scratch"] scratchpad show

i3 users: swap --app-id for i3's class-based criteria. See Summoning tuicc for the full i3 snippet, the ready-made single-key toggle scripts (recommended over the raw exec/for_window lines above — they also re-assert fullscreen correctly, see below), Hyprland/niri versions, and the reasoning behind each line.

• Swap $mod+grave (Super + `) for whichever key combo you want.
• Swap kitty for whatever terminal you actually use — most accept the same --app-id (or --class) flag; check your terminal's manpage if it doesn't.
• Replace /full/path/to/tuicc with wherever you cloned it in the Installing step above.
• Once tuicc is tagged this way, also set [wm] self_app_id = "tuicc_scratch" in ~/.config/tuicc/config.toml — this lets tuicc mark and dismiss its own window unambiguously (see Config Reference) instead of relying on "whatever's focused," which can race on the very first launch.
• If you'd rather not hand-write the toggle logic, contrib/sway/tuicc_toggle.py is a ready-made single-key summon/dismiss/focus script for sway — bind a key to run it instead of the raw exec kitty ... line above.

Reload your WM config ($mod+Shift+c by default) and try your new keybind. Pressing it again dismisses tuicc (hides it, doesn't end the process) rather than closing it — see Keybindings for the full dismiss-vs-quit model.

Controls

Key	What it does
Tab	Move to the next item, rolling into the next section once you run past the last item in this one
Shift+Tab	Tab's mirror — previous item, rolling into the previous section
Up/Down	Same as Tab/Shift+Tab
Left/Right	Jump straight to the next/previous section's first item
h/j/k/l (optional)	Same as the arrow keys above, but only active if you turn on vim_mode in your config — off by default so those letters keep reaching the launcher
Enter	Do the selected thing — switch to that workspace, focus that window, connect/disconnect wifi or bluetooth, launch an app, flip a system toggle, control media playback, or run a power-menu action — then dismiss tuicc (hide it, keep it running in the background) unless you're in the launcher, connectivity, sessions, control, or media modules, which stay open
Escape	Same dismiss as Enter, without doing anything first
any letter/number key	Start typing to open the launcher and search for an app, from anywhere (press i first if vim_mode is on)
Ctrl+C	The only way to actually quit tuicc and end the process — an ordinary terminal interrupt, not a tuicc keybind

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 to open resize mode: Tab/Shift+Tab/arrows pick which module you want to work on, and Enter on the active one starts actually editing it — arrow keys resize it one terminal cell at a time, m switches to moving it instead of resizing, Delete removes it entirely (asks y/n to confirm first), Enter commits the change and drops back to picking a module, Escape reverts just that change and does the same. Press Escape again once you're back at picking (not editing) to leave resize mode entirely. F6 lets you spawn a module that isn't currently on screen and drops you straight into editing it. F3 saves your current layout back to the preset you're using, overwriting it in place; F4 cycles to a different existing preset. 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.

Don't want to pick colors one at a time? Open the Colors page (F1, then 3) and press F4 — it cycles through 9 ready-made schemes (Dracula, Nord, Solarized Dark, Gruvbox, One Dark, Rose Pine, Catppuccin Mocha, Tokyo Night, and tuicc's own default), applying all 8 colors at once. Keep pressing F4 until one looks right, then still use Enter on any individual row afterward if you want to tweak just one color from there.

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