Thuki - WIP

A floating AI secretary for macOS. Fully local, completely free, zero data ever leaves your machine.

---

No API keys. No subscriptions. No cloud. No telemetry. Free forever.

Thuki (thư kí - Vietnamese for secretary) is a lightweight macOS overlay powered by local AI models running entirely on your own machine, built for quick, uninterrupted asks without ever leaving what you're doing.

See It in Action

Basic Usage

Double-tap Control ⌃ to summon Thuki from anywhere. Ask a question, get an answer, and dismiss. Use /screen or the screenshot button to capture your screen and attach it as context.

thuki_demo_1.mp4

Overlay Mode

Thuki floats above every app, including fullscreen ones. Highlight text anywhere, double-tap Control ⌃, and Thuki opens with your selection pre-filled as a quote, ready to ask about.

thuki_demo_2.mp4

Why Thuki?

Most AI tools require accounts, API keys, or subscriptions that bill you per token. Thuki is different:

• 100% free AI interactions: you run the model locally, there is no per-query cost, ever
• Zero trust by design: no remote server, no cloud backend, no analytics, no telemetry
• Works completely offline: once your model is downloaded, Thuki runs without an internet connection
• Your data is yours: conversations are stored in a local SQLite database on your machine and nowhere else
• Most importantly: it works everywhere. Double-tap Control ⌃ and Thuki appears on your desktop, inside a browser, inside a terminal, and yes, even in fullscreen apps. Your favorite AI chat apps can't do that!

Features

• Always available: double-tap Control ⌃ to summon the overlay from any app, including fullscreen apps
• Context-aware quotes: highlight any text, then double-tap Control ⌃ to open Thuki with the selected text pre-filled as a quote
• Throwaway conversations: fast, lightweight interactions without the overhead of a full chat app
• Conversation history: persist and revisit past conversations across sessions
• Ships its own local AI engine: Thuki bundles a llama.cpp-based inference engine and downloads a starter model for you during onboarding; no API keys, no accounts, no cost per query
• Optional providers: prefer your own server? Switch to a local Ollama install or any OpenAI-compatible server (LM Studio, Jan, llama-server) at any time
• Image input: paste or drag images and screenshots directly into the chat
• Screen capture: type /screen to instantly capture your entire screen and attach it to your question as context
• OCR on text-only models: /extract, /explain, /tldr, /translate, /rewrite, /refine, /bullets, and /todos read attached images via macOS Vision OCR, so they work even when the active model has no vision capability
• Agentic search: type /search to run a fully local, multi-step search pipeline (SearXNG + Trafilatura reader) with a live trace of every query, fetch, and judgement step
• Slash commands: built-in commands for live search and prompt shortcuts: /search, /extract, /explain, /translate, /rewrite, /tldr, /refine, /bullets, /todos. Highlight text anywhere, summon Thuki, type a command, and hit Enter
• Extended reasoning: type /think to have the model reason through a problem step by step before answering
• Math rendering: LaTeX expressions in responses render as formatted equations via KaTeX
• In-app model library: download curated starter models (or any GGUF straight from Hugging Face), browse what's installed, and switch the active model from the ask bar without ever opening a config file
• Cross-model continuity: swap models mid-conversation and Thuki sanitizes history and filters capabilities (vision, thinking) to whatever the new model supports
• Settings panel: a native window (⌘,) covering providers and models, prompt, window, behavior, and search settings, including a log-scale context-window slider and a tunable image-attachment cap (up to 20)
• Contextual tip bar: lightweight in-overlay hints surface the right shortcut or command at the right moment
• Privacy-first: zero-trust architecture, all data stays on your device

Getting Started

Thuki ships its own local AI engine, so there is nothing to set up first: download the app, pick a model during onboarding, and start asking.

Install Thuki

Download (Recommended)

1. Download Thuki.dmg from the latest stable release, or grab the bleeding-edge build from the nightly channel which is rebuilt automatically from main.

2. Double-click Thuki.dmg to open it. A window appears showing the Thuki app icon next to an Applications folder shortcut.

3. Drag Thuki onto the Applications folder shortcut.

4. Eject the disk image (drag it to Trash in the Finder sidebar, or right-click and choose Eject).

5. Before opening Thuki for the first time, run this command in Terminal:

   xattr -rd com.apple.quarantine /Applications/Thuki.app

   Why is this needed? Thuki is a free, non-profit, open-source app distributed directly and not through the Mac App Store. Apple's Gatekeeper automatically blocks any app downloaded from the internet that has not gone through Apple's paid notarization process. This one-time command removes that block. It is safe and officially documented by Apple.

6. Open Thuki. It will appear in your menu bar.

First launch: macOS will ask for two permissions. Accessibility is required for the global keyboard shortcut that lets you summon Thuki from any app. Screen Recording is required for the /screen command and the screenshot button. Grant both once; they persist across restarts.

Pick a model: onboarding offers a curated set of starter models sized for different Macs and downloads your pick right inside the app. Model files are large (roughly 2-9 GB), so the first download can take several minutes; you only do it once. Add more models anytime, including any GGUF from Hugging Face, from the Providers section of Settings.

Build from Source

Prerequisites: Bun, Rust, and optionally Docker

# Clone and install dependencies
git clone https://github.com/quiet-node/thuki.git
cd thuki
bun install

# Launch in development mode
bun run dev

See CONTRIBUTING.md for the full development setup guide.

Optional providers

The built-in engine covers the default experience. If you would rather run models through your own server, Thuki also speaks to two alternatives; switch between providers anytime from Settings.

Ollama

Ollama runs AI models directly on your Mac. Install it from ollama.com or via Homebrew (brew install ollama), pull a model (ollama pull gemma4:e2b; any model in the Ollama library works), and select the Ollama provider in Thuki's Settings. Thuki connects to it at http://127.0.0.1:11434 by default, and you can point it at another machine instead.

Any OpenAI-compatible server

LM Studio, Jan, a self-managed llama-server, or anything else that serves the OpenAI /v1 API can be added from the Providers section of Settings: give it a label and a base URL, optionally save an API key (stored write-only in the macOS Keychain, never written to config.toml), and flag whether its model accepts images. Prefer editing by hand? Add a provider with kind = "openai" in config.toml instead; see docs/configurations.md for the provider schema.

Optional: Enable /search

The /search command runs a fully local agentic search pipeline backed by two Docker services (SearXNG + a Trafilatura reader). It is not bundled with the .dmg: enabling it currently requires cloning this repository to run the local services. Every other Thuki feature works without it. First-class, out-of-box /search support is on the roadmap.

See docs/agentic-search.md#setup for the setup steps.

Architecture & Security

Click to expand

Thuki is a Tauri v2 app (Rust backend + React/TypeScript frontend). Its default inference engine is a bundled llama.cpp llama-server that Thuki spawns, supervises, and kills on quit; it can instead talk to a locally running Ollama instance or any OpenAI-compatible server.

Isolation Layers

1. Frontend (Tauri/React): Operates within a secure system webview with restricted IPC. Streaming uses Tauri's Channel API; the Rust backend sends typed StreamChunk enum variants, and the frontend hook accumulates tokens into React state.

2. Built-in Engine: Runs as a separate process bound to 127.0.0.1 only, with its web UI disabled, so nothing outside your Mac can reach it. The pinned llama.cpp release is sha256-verified at build time, and every model download is fetched from a pinned Hugging Face repo revision and sha256-checked before install.

Window Lifecycle

The app starts hidden. The hotkey or tray menu shows it. The window close button hides (not quits); quit is only available from the tray. ActivationPolicy::Accessory hides the Dock icon. macOSPrivateApi: true enables NSPanel for fullscreen-app overlay.

Configuration

Thuki reads a single typed TOML file at ~/Library/Application Support/com.quietnode.thuki/config.toml, seeded with sensible defaults on first launch. The in-app Settings panel (⌘,) writes to the same file, so you can edit by hand or click through tabs, whichever you prefer.

See docs/configurations.md for the full schema covering the [inference], [prompt], [window], [quote], and [search] sections (active provider, system prompt, context window, image cap, agentic-search timeouts, and more).

See docs/commands.md for the full slash command reference, and docs/tuning-context-window.md for guidance on picking a num_ctx value.

Contributing

Contributions are welcome! Read CONTRIBUTING.md to get started. Please follow the Code of Conduct.

Community Ports

Thuki is macOS-only, but the community has been busy bringing it to other platforms. Huge shoutout to these contributors 🎊🚀!

Platform	Repo	Author
Windows 10/11	ThukiWin	@ayzekhdawy
Windows 10/11	Mate	@M31i55a

Each port is independently maintained by its author. For issues or questions about a specific port, head to that repo directly.

Author

Reach out to Logan on X with questions or feedback.

What's next for Thuki

Thuki is just getting started. Here's where it's headed:

Secretary Superpowers

The big leap: from answering questions to taking action.

• Tool integrations via MCP: connect Thuki to Gmail, Slack, Discord, Google Calendar, and any other MCP-compatible service; ask it to draft a reply, summarize a thread, or schedule a meeting without ever leaving your current app

Better AI Control

More flexibility over the model powering Thuki.

• Multiple provider support: shipped; alongside the built-in engine, Thuki speaks to your own Ollama install or any OpenAI-compatible local server
• Custom activation shortcut: change the double-tap trigger to any key or combo you prefer

Richer Context

Give Thuki more to work with.

• Voice input: dictate your question instead of typing
• Auto-capture screen context: activate Thuki and have it automatically read the active window or selected region as context (partial: /screen captures the full screen today; targeted region capture is next)
• File and document drop: drag a PDF or text file directly into Thuki as context for your question

---

Have a feature idea? Open an issue and let's talk about it.

License

Copyright 2026 Logan Nguyen. Licensed under the Apache License, Version 2.0.