ClickUi: a Python desktop AI assistant with Whisper, Kokoro and a ctrl+k chat window

What ClickUi is for, and who it is aimed at

ClickUi is a desktop application that sits on top of your other windows and answers questions in a chat panel. The README describes two modes: Chat Mode, where you type a query and read a written reply, and Voice Mode, where you speak and the assistant speaks back through your local audio or a Sonos speaker. The project is written entirely in Python, and the README presents that as a deliberate choice rather than an accident: "It's 100% Python, and aims to be the best AI-computer assistant."

The audience is people who want an assistant on their own computer rather than in a browser tab. The dependency list backs that up. It includes the ollama package alongside openai, google-genai, and the soco library for Sonos control, so the intended setup covers both locally hosted models and paid API models. If you already have Ollama running, or you have API keys for OpenAI, Google, Claude, Groq, or OpenRouter, ClickUi is built to talk to what you already have instead of locking you into one provider.

The README also frames the project as unfinished and open to contributors. It asks for collaborators directly, asks for feature ideas to be submitted as checkboxes in the README, and states that pull requests should go to main. That is a useful signal about maturity: this is a working personal tool that the author wants other people to help shape, not a product with a support organization behind it.

How the chat window, hotkey and model routing fit together

The visible mechanism is a global hotkey. The description states that ctrl+k shows and hides the chat UI, and the README's roadmap confirms the intended flow: after launching with the hotkey, the cursor starts in the prompt area, and the plan is to let arrow keys move from there into settings or the conversation window. So the application is not a window you keep open. It is a panel you summon, type into, and dismiss.

Underneath, the architecture is a single Python entry point, clickui.py, supported by sonos.py for speaker output and a .voiceconfig file for voice settings. The GUI layer is PySide6, which explains why the roadmap item about merging windows exists: the README notes that two windows currently launch in the taskbar, one for each area. That is a visible consequence of how the interface is assembled rather than a design goal.

Model access is routed through provider SDKs rather than a single abstraction. The requirements file pins openai, google-genai, and ollama at specific versions, which means adding a provider is a code change rather than a settings change. The README says so plainly in its roadmap: one open item is to add model and engine selection to the settings widget, with the note that you "have to define in python right now to make available." For a reader deciding whether to adopt this, that is the most important architectural fact on the page. Configuration is partly in the UI and partly in source.

Web features are handled by two scraping stacks, Playwright and Selenium, plus BeautifulSoup and lxml for parsing. The README shows Google live search in its screenshots and the repository root contains redfin_icon.png and zillow_icon.png, which points at property lookups as a built-in use case. Running two browser automation frameworks in one application is heavy, and it is the kind of choice that shows the project grew by addition rather than by pruning.

Installing ClickUi and getting one real answer out of it

The repository gives you a requirements.txt for the general case, a requirements_mac.txt for macOS, a conda_packages.txt, and an Install.bat for Windows. Mac_Prerequisites.txt covers the macOS side. There is no packaged installer: the README's roadmap explicitly lists providing executables for Windows, Mac, and Linux as an open item, so installation today means a Python environment you manage yourself.

Start by creating an environment and installing the pinned dependencies. The requirements file pins versions such as PySide6==6.8.2.1, openai==1.65.4 and ollama==0.4.7, so use the file rather than installing packages by name.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On macOS, use the platform-specific file instead, and read Mac_Prerequisites.txt before you start.

pip install -r requirements_mac.txt

On Windows, the repository ships Install.bat, which is the intended path there.

Install.bat

Before the first run you need two things configured: the API keys and engine or model information for whichever provider you plan to use, and the voice models if you want Voice Mode. The README is direct about the second point. Whisper and Kokoro "are loaded into the global scope" and "must be installed and properly configured before running the AI Assistant," with the stated consequence that failure results in runtime errors. If you do not want voice, the README gives an explicit escape hatch: comment out the Whisper and Kokoro loading, and Voice Mode will not work but the rest will run.

Then launch the application and press ctrl+k to bring up the chat UI. Type a question into the prompt area and send it. With a local Ollama model or a configured API key, you should get a reply in the conversation window. If you left the voice models commented out, do not expect the microphone path to respond; that is the documented trade-off, not a bug.

The voice pipeline is the part most likely to break

Voice Mode is the feature the README leads with, and it is also the least settled. The global-scope loading of Whisper and Kokoro is the first constraint: these are large models, and the README treats their presence as a precondition rather than something the application manages for you. That means startup cost and memory footprint are yours to plan for, and a missing or misconfigured model surfaces as a runtime error rather than a friendly prompt.

The roadmap is candid about the state of the loop. One open item is to "Fix/Revise Voice mode start/stop toggling & related resets," with the specific failure described: clicking to exit voice mode during transcription or audio playback "sometimes quits entire program." Another open item is interrupt capability, so that speaking during Kokoro playback stops the current output and returns to recording. Neither is implemented according to the README's own checkbox list. If your use case depends on a reliable push-to-talk loop, this is the wrong tool today.

There is a second limitation that has nothing to do with bugs. The roadmap lists tests for prompt input, reply input, and conversation history validation as an unchecked item. Combined with a single-file entry point and pinned dependencies, that means upgrades are manual and regressions are discovered by using the application. The README does not document a rollback path for a bad upgrade, and no releases were retrieved, so there is no versioned artifact to fall back to. You would be tracking main.

ClickUi compared with a terminal client like aichat or llm

The closest alternatives are command-line assistants such as aichat or Simon Willison's llm, which also let you talk to local and hosted models from your own machine. The difference is where the interface lives. Those tools live in a terminal and compose well with pipes, scripts, and shell history. ClickUi lives in a PySide6 window that floats over whatever you are doing, which is the point of the ctrl+k hotkey: you never leave the application you are working in.

That choice buys convenience and costs composability. A terminal client can be scripted, diffed, and run over SSH. ClickUi cannot, because its value is the GUI and the global keyboard hook, and the pynput dependency exists precisely to make that hook cross-platform. The README records that the older keyboard library "has issues with Mac/Linux," which is why pynput replaced it. If your work happens in a terminal, a CLI client will fit better. If your work happens in a browser, an editor, or a spreadsheet, the hotkey panel is the feature you are actually buying.

A second difference is scope. ClickUi bundles speech recognition, speech synthesis, Sonos control, and two browser automation stacks into one application. A terminal client typically does one thing and expects you to pipe in the rest. ClickUi's breadth is why the dependency list is long and why the roadmap still has open items about settings, hotkeys, and window management. You are trading a small, sharp tool for a large, uneven one.

Licence, maintenance and what an upgrade costs you

ClickUi is licensed under AGPL-3.0. The practical consequence for most readers is that if you modify it and let other people interact with it over a network, the licence's source-availability terms are designed to reach your modified version. Running it locally for yourself is the ordinary case and is unaffected. If you plan to embed it in a product or expose it as a service, read the licence text in LICENSE.txt and get your own advice, because the obligations depend on how you deploy it.

The repository is not archived, and the last push was on 2026-09-07. That is recent enough that the project is being worked on, but the README's own checkbox list is the better guide to maturity than any activity signal: voice toggling, tests, model selection in settings, multi-file attachment, token tracking, and packaging are all open. The roadmap also notes that file attachment is currently limited to one file, and that the settings widget does not yet expose temperature, top-p, or repeat penalty.

Upgrade cost follows from that. Dependencies are pinned exactly, including PySide6, openai, and ollama, so a manual upgrade means re-resolving a long list against your Python version and CUDA setup. The project has no releases to pin to, so "upgrade" means pulling the current state of main. Budget for reading the diff, because the README documents no migration steps and no rollback.

Editorial conclusion

Adopt ClickUi if you already run Python on your own machine, want a hotkey-summoned chat window over your desktop, and are willing to install Whisper and Kokoro yourself or comment out the voice path. Skip it if you need a packaged installer, a stable voice loop, or a project with tests, because the README lists none of those and the author is explicitly asking for collaborators. Before installing, verify that your Python environment can build openai-whisper and kokoro from requirements.txt, and confirm whether you want the voice dependencies at all.

Frequently asked questions

Official sources

1. CodeUpdaterBot/ClickUi on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README