Home

tuicc wiki

Honest disclaimer: this wiki is AI maintained. I revisit it at regular intervals to check facts and weed out anything that sounds like annoying AI-slop, but I still use claude code to push wiki updates — this is the price I chose to pay as the single maintainer for tuicc. Once refactoring slows down, I am committed to making this wiki as human-pleasant as possible.

Here lives the documentation for tuicc — the README covers what tuicc is and how to try it; this wiki contains more detailed info about architecture, decisions, exhaustive config info.. and directions about how to use tuicc or add new modules or providers!

Pages

• Getting Started — If you just thought "this is cool, and I wanna try it, but I'm new to all of this / don't really understand what's going on.." Don't worry, I care and wanna help you to use tuicc <3, click on this page! (There's a one-command Quick install now too, if you just want it running.)

• Your First Contribution — the other kind of "getting started": if you want to change tuicc's code (or config-driven behavior) for the first time, not just run it, this is where to go before CONTRIBUTING.md's rules make sense. Walks through one small real change end to end.

• Summoning tuicc — the full per-WM reference for the toggle-key setup (sway, i3, Hyprland, niri), including the by-hand snippets and the reasoning behind each line — Getting Started has the short version.

• Architecture — how the core (provider layer, layout engine, input routing) fits together, the RenderContext pattern, StatusWorker (one background poll thread shared by connectivity, audio, media, and every [[control.toggle]]), tuicc's persistent-process lifecycle (dismiss vs. quit), and what my thought process was behind certain design decisions (floating window handling, why spatial navigation was tried and then removed).

• Config Reference — everything config.toml - every accepted value, with examples, including the [[control.toggle]] contract for building your own system toggles (night light, power profiles, do-not-disturb, whatever your setup already has). If you're customizing tuicc and the inline config comments aren't enough, this is for you.

• Writing a WM Provider — an expansion to the README's version, including a step-by-step look at how I was building a provider against a real WM's IPC, and how to approach window layouts that don't map cleanly onto sway's model. (scrollable WMs are still haunting me in the depths of my backlog)

• Writing a Module — how to build your own modules: they plug into tuicc's core without the core ever needing to know they exist, using the sidebar/preview/quick_actions modules (and the two-level browsing/expanded pattern from sessions/media) as worked examples.

• Keybindings — every key name tuicc understands (including the optional vim-style h/j/k/l bindings), how Tab/Shift+Tab-driven navigation actually decides where to go, and how to remap everything.

Status

tuicc is meant to run as one long-lived process your WM summons and dismisses, not something you relaunch each time — see Getting Started for the setup. tuicc is also still early and actively changing — pages here reflect the project as of mid August 2026 (control toggles, the MPRIS-based media module with an optional cava audio visualizer, a per-window system monitor, VOL/BRI/BAT gauges (bars), and a real WiFi/Bluetooth D-Bus-agent connectivity overhaul — passphrase/pairing prompts, forget/hidden-network/radio-power controls, live connection diagnostics — have all landed since). If something here doesn't match what you see in the code, the code is right; open an issue and I'll fix the page.

Elsewhere

• Main README — quick start, status, architecture overview
• Issues — bugs, questions, provider requests