diff --git a/README.md b/README.md index 821533de..1a252cd2 100644 --- a/README.md +++ b/README.md @@ -6,16 +6,12 @@ Thuki: a private, local AI secretary overlay for macOS

- -

A floating AI secretary for macOS. Double-tap Control to summon a spotlight-style overlay anywhere, even over fullscreen apps. It runs entirely on your Mac with its own built-in engine: private, with no cloud and no API keys.

- Free and open source. Local inference costs you nothing, no per-query fees, ever. + Free and open source.

@@ -38,126 +34,46 @@ --- -**No API keys. No subscriptions. No cloud. No telemetry.** - 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 - -Double-tap Control ⌃ to summon Thuki from anywhere, even over fullscreen apps. Highlight text first and it opens with your selection pre-filled as a quote. Ask a question, attach your screen with `/screen`, get an answer, and dismiss without ever leaving what you're doing. - - - - -https://github.com/user-attachments/assets/b321725e-860d-4177-8309-f78a0eb26261 - - - - - ## Install on macOS -Install the app, pick a model during onboarding, and start asking. - -> **Requirements:** macOS 13.4 (Ventura) or later, on Apple Silicon (M1/M2/M3/M4/M5). - -### Recommended: one-line install +> **Requirements:** macOS 13.4 (Ventura) or later, Apple Silicon (M1-M5). ```bash curl -fsSL https://thuki.app/install.sh | sh ``` -This downloads the latest `Thuki.dmg` over HTTPS, verifies its RSA-4096 signature with the `openssl` already on your Mac, and installs it to `/Applications`. Because the download arrives without a quarantine flag, Thuki opens cleanly: no Gatekeeper "Apple could not verify" prompt and no manual `xattr` step. - -#### Nightly (separate app, side by side with stable) - -```bash -curl -fsSL https://thuki.app/install.sh | THUKI_CHANNEL=nightly sh -``` - -Same script URL; the `THUKI_CHANNEL=nightly` env (or `sh -s -- --nightly`) installs **Thuki Nightly.app** beside stable `Thuki.app`. Nightly uses a different bundle id (`com.quietnode.thuki.nightly`), so data, Keychain secrets, and TCC grants stay separate. Not for production. Do not run both at once: they both claim double-tap Control and will fight over the hotkey. - -Want to read the script before running it? Visiting [thuki.app/install.sh](https://thuki.app/install.sh) downloads it; open the saved file in a text editor to review it first. Or read it in the terminal without saving anything: - -```bash -curl -fsSL https://thuki.app/install.sh | less -``` - -

-Manual install (download the DMG) - -Prefer to download by hand? Grab the DMG and clear the quarantine flag yourself. - -1. Download `Thuki.dmg` from the [latest stable release](https://github.com/quiet-node/thuki/releases/latest), or grab the bleeding-edge build from the [`nightly`](https://github.com/quiet-node/thuki/releases/tag/nightly) channel, rebuilt automatically from `main`. -2. Double-click `Thuki.dmg` to open it, then drag the app onto the `Applications` folder shortcut. Stable ships as `Thuki.app`; nightly as `Thuki Nightly.app`. -3. Eject the disk image (drag it to Trash in the Finder sidebar, or right-click and choose Eject). -4. **Before opening for the first time**, run this command in Terminal (use the path that matches the channel you installed): - - ```bash - # stable - xattr -rd com.apple.quarantine /Applications/Thuki.app - - # nightly - xattr -rd com.apple.quarantine "/Applications/Thuki Nightly.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](https://support.apple.com/en-us/102445). The one-line installer above handles this for you. - -5. Open the app. It will appear in your menu bar. - -
- -
-Build from source - -**Prerequisites:** [Bun](https://bun.sh) and [Rust](https://rustup.rs) - -```bash -# Clone and install dependencies -git clone https://github.com/quiet-node/thuki.git -cd thuki -bun install - -# Launch in development mode (hot-reload frontend) -bun run dev -``` - -See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development setup guide. - -To produce a standalone app instead of running the dev server, build it and open the bundle directly: - -```bash -bun run build:all -open src-tauri/target/release/bundle/macos/Thuki.app -``` - -
+Downloads the latest `Thuki.dmg` over HTTPS, verifies its RSA-4096 signature with the `openssl` already on your Mac, and installs it to `/Applications`. -> **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 Settings → Models → Discover. +Other paths: [inspect the script](docs/install.md#inspect-the-install-script) · [manual DMG](docs/install.md#manual-install-download-the-dmg) · [Nightly](docs/install.md#nightly-side-by-side-with-stable) · [build from source](docs/install.md#build-from-source). ## Why Thuki? -Most AI tools require accounts, API keys, or subscriptions that bill you per token. Thuki is different: +**Most local AI tools are a place you go. Thuki is a key you press.** -- **It works everywhere.** Double-tap Control ⌃ and Thuki appears on your desktop, inside a browser, inside a terminal, and even in fullscreen apps. Your favorite AI chat apps can't do that. -- **100% free local AI.** You run the model on your own machine, so there is no per-query cost, ever. -- **Private by design.** No remote server, no cloud backend, no analytics, no telemetry. Conversations live in a local SQLite database on your machine and nowhere else. -- **Works offline.** Once your model is downloaded, inference runs without an internet connection. Downloads and web search still need the network; turn off Auto search in Settings → Behavior to keep chat fully offline. +- **It arrives knowing what you were looking at.** Highlight text in any app, double-tap Control ⌃, and your selection is already quoted. One gesture, no copy-paste round trip. +- **Nothing to install, pay, or configure first.** Thuki ships its own llama.cpp engine and browses Hugging Face in-app, so any open model is a click away. No terminal, no separate server, no API key, no license fee. +- **It sees your screen, not just your clipboard.** `/screen` attaches your whole desktop as visual context for any vision-capable model. +- **Free and open source, running only on your machine.** No accounts, no per-query cost, no telemetry. Your conversations stay in a local database and nowhere else. +- **Works offline.** Once a model is downloaded, inference needs no connection. Only downloads and web search use the network, and Auto search is one toggle from off. ## 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 selection pre-filled as a quote. -- **Built-in AI engine and model library:** Thuki bundles a llama.cpp inference engine and lets you download curated Staff Picks, or any GGUF straight from Hugging Face, browse your Library, and switch the active model from the ask bar, all from inside the app. -- **Instant follow-ups:** Thuki can keep your model warm in memory between messages, so replies start right away instead of stalling to reload the model on every ask. -- **Image input and screen capture:** paste or drag images directly into the chat, or type `/screen` to capture your entire screen and attach it as context. -- **Read text in images, on any model:** commands like `/extract`, `/explain`, `/tldr`, and `/translate` pull the _text_ out of an attached image with on-device macOS Vision OCR, so they work on screenshots and documents even when the active model has no vision capability. They read text, not scenes: describing a textless image (say, a photo of the sky) still needs a vision model. See [docs/ocr-commands.md](docs/ocr-commands.md). -- **Built-in web search:** With Auto search on (Settings → Behavior, default), Thuki may search the web when a plain message needs current information. Turn it off to stay fully local and use `/search` only when you want an on-demand look-up. Keyless; answers are grounded in retrieved sources with inline citations. See [docs/built-in-web-search.md](docs/built-in-web-search.md), [docs/search-privacy.md](docs/search-privacy.md), [docs/privacy.md](docs/privacy.md), [docs/commands.md](docs/commands.md) (`/search`), and [docs/configurations.md](docs/configurations.md) (`auto_search` and built-in search constants). -- **Slash commands:** built-in shortcuts for search and prompt actions: `/search`, `/extract`, `/explain`, `/translate`, `/rewrite`, `/tldr`, `/refine`, `/bullets`, `/todos`. -- **On-demand reasoning:** on models that support reasoning (not every model does), add `/think` to any message to make it work through the problem step by step before answering. It is off by default, so everyday asks stay fast. -- **Cross-model continuity:** swap models mid-conversation and Thuki sanitizes history and filters capabilities (vision, reasoning) to whatever the new model supports. + + + + + + + + + + + + + +
Always one keystroke away
Double-tap Control from any app, even fullscreen.
Highlight, then ask
Select text, double-tap, it arrives as a quote.
Capture your screen
/screen attaches your whole desktop as context.
Built-in web search
Keyless and cited. /search forces a lookup.
On-device model library
Download any GGUF, switch from the ask bar.
Just a slash, zero menus
Every task is a verb. No dropdowns, no settings.
Thuki slash commands
## Models & providers @@ -172,7 +88,7 @@ A bundled llama.cpp `llama-server` that Thuki spawns, supervises, and shuts down Thuki can also run inference through an external provider instead of the built-in engine. - **Ollama.** Prefer your own [Ollama](https://ollama.com) install? Switch to it anytime from Settings. -- **Your own OpenAI-compatible server (coming soon).** Support for pointing Thuki at any OpenAI-compatible endpoint you run yourself (a local or self-hosted server) is on the [roadmap](#whats-next-for-thuki). +- **Your own OpenAI-compatible server (coming soon).** Support for pointing Thuki at any OpenAI-compatible endpoint you run yourself (a local or self-hosted server) is on the [roadmap](#roadmap). See [docs/models-and-providers.md](docs/models-and-providers.md) for the full model library and provider guide. @@ -182,34 +98,7 @@ Inference runs on-device, so your prompts, context, and replies never leave your ## Architecture & security -
-Click to expand - -Thuki is a [Tauri v2](https://v2.tauri.app/) app: a Rust backend with a React and TypeScript frontend. - -| Layer | Technology | -| -------- | ------------------------------------ | -| Shell | Tauri v2 | -| Backend | Rust (stable) | -| Frontend | React 19, TypeScript, Tailwind CSS 4 | -| Engine | Bundled llama.cpp `llama-server` | -| Storage | SQLite (bundled) | - -### Process model - -Two processes, with a narrow boundary between them: - -1. **App (Tauri/React).** The UI runs in 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. **Engine.** The default engine runs as a separate `llama-server` process that Thuki spawns, supervises, and kills on quit, 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 checked against a pinned Hugging Face revision before install. - -### Window lifecycle - -The app starts hidden. The hotkey or tray menu shows it. The window close button hides the window rather than quitting; quit is only available from the tray. `ActivationPolicy::Accessory` hides the Dock icon, and `macOSPrivateApi: true` enables the NSPanel that lets Thuki float above fullscreen apps. - -For the engine internals (sidecar lifecycle, Keep Warm, the spawn line, model store), see [docs/models-and-providers.md](docs/models-and-providers.md). For the full security posture and how to report an issue, see [SECURITY.md](SECURITY.md). - -
+Tauri v2 (Rust backend, React and TypeScript frontend) with a bundled llama.cpp `llama-server` engine bound to `127.0.0.1` and killed on quit. The pinned engine release is sha256-verified at build time and every model download is checked against a pinned Hugging Face revision. See [docs/models-and-providers.md](docs/models-and-providers.md) for engine internals and [SECURITY.md](SECURITY.md) for the full security posture. ## Configuration @@ -219,34 +108,13 @@ See [docs/configurations.md](docs/configurations.md) for the full schema, [docs/ ## Contributing -Contributions are welcome! Read [CONTRIBUTING.md](CONTRIBUTING.md) to get started. Please follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -## Community ports +Contributions are welcome! Read [CONTRIBUTING.md](CONTRIBUTING.md) to get started, and follow the [Code of Conduct](CODE_OF_CONDUCT.md). -Thuki is macOS-only, but the community has been busy bringing it to other platforms. Huge shoutout to these contributors 🎊🚀! +Community-maintained Windows ports: [ThukiWin](https://github.com/ayzekhdawy/thukiwin) and [Mate](https://github.com/M31i55a/windowsMate-Thuki). -| Platform | Repo | Author | -| ------------- | ---------------------------------------------------- | -------------------------------------------- | -| Windows 10/11 | [ThukiWin](https://github.com/ayzekhdawy/thukiwin) | [@ayzekhdawy](https://github.com/ayzekhdawy) | -| Windows 10/11 | [Mate](https://github.com/M31i55a/windowsMate-Thuki) | [@M31i55a](https://github.com/M31i55a) | - -> Each port is independently maintained by its author. For issues or questions about a specific port, head to that repo directly. - -## What's next for Thuki - -Thuki is just getting started. Here's where it's headed: - -- **Connect your tools:** integrate via [MCP](https://modelcontextprotocol.io/) with Gmail, Slack, Discord, Calendar, and more, so you can draft a reply, summarize a thread, or schedule a meeting without leaving your current app. -- **Type with your voice:** press a key, speak, and get clean text in any app. -- **Notes from any meeting:** live transcripts and summaries of any meeting. -- **Automate the routine:** teach Thuki multi-step tasks and run them on a word. -- **More providers:** bring your own OpenAI-compatible server (a local or self-hosted endpoint) alongside the built-in engine and Ollama. - -Whatever comes next, the aim stays the same: a local-first secretary that runs open models on your own machine. Network use stays minimal and user-controlled, from Auto search (on by default, one toggle away from off) to any future integration. - ---- +## Roadmap -Have a feature idea? [Open an issue](https://github.com/quiet-node/thuki/issues) and let's talk about it. +MCP tool integrations (Gmail, Slack, Calendar), voice input, meeting notes, task automation, and bring-your-own OpenAI-compatible server. Have an idea? [Open an issue](https://github.com/quiet-node/thuki/issues). ## Founder note diff --git a/docs/assets/slash-commands-v2.png b/docs/assets/slash-commands-v2.png new file mode 100644 index 00000000..de8b1fab Binary files /dev/null and b/docs/assets/slash-commands-v2.png differ diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..24be6a6a --- /dev/null +++ b/docs/install.md @@ -0,0 +1,77 @@ +# Installing Thuki + +**Requirements:** macOS 13.4 (Ventura) or later, Apple Silicon (M1-M5). + +## Recommended: one-line install + +```bash +curl -fsSL https://thuki.app/install.sh | sh +``` + +This downloads the latest `Thuki.dmg` over HTTPS, verifies its RSA-4096 signature with the `openssl` already on your Mac, and installs it to `/Applications`. Because the download arrives without a quarantine flag, Thuki opens cleanly with no Gatekeeper prompt and no manual `xattr` step. + +On first launch macOS asks for two permissions: **Accessibility** (the global hotkey that summons Thuki from any app) and **Screen Recording** (the `/screen` command). Grant both once; they persist across restarts. Onboarding then downloads a starter model right inside the app. + +The sections below cover the alternative paths. + +## Inspect the install script + +Read it in the terminal without saving anything: + +```bash +curl -fsSL https://thuki.app/install.sh | less +``` + +Or visit [thuki.app/install.sh](https://thuki.app/install.sh) to download it and open the saved file in an editor first. + +## Nightly (side by side with stable) + +```bash +curl -fsSL https://thuki.app/install.sh | THUKI_CHANNEL=nightly sh +``` + +Same script URL; the `THUKI_CHANNEL=nightly` env (or `sh -s -- --nightly`) installs **Thuki Nightly.app** beside stable `Thuki.app`. Nightly uses a different bundle id (`com.quietnode.thuki.nightly`), so data, Keychain secrets, and TCC grants stay separate. Not for production. Do not run both at once: they both claim double-tap Control and will fight over the hotkey. + +## Manual install (download the DMG) + +Prefer to download by hand? Grab the DMG and clear the quarantine flag yourself. + +1. Download `Thuki.dmg` from the [latest stable release](https://github.com/quiet-node/thuki/releases/latest), or grab the bleeding-edge build from the [`nightly`](https://github.com/quiet-node/thuki/releases/tag/nightly) channel, rebuilt automatically from `main`. +2. Double-click `Thuki.dmg` to open it, then drag the app onto the `Applications` folder shortcut. Stable ships as `Thuki.app`; nightly as `Thuki Nightly.app`. +3. Eject the disk image (drag it to Trash in the Finder sidebar, or right-click and choose Eject). +4. **Before opening for the first time**, run this command in Terminal (use the path that matches the channel you installed): + + ```bash + # stable + xattr -rd com.apple.quarantine /Applications/Thuki.app + + # nightly + xattr -rd com.apple.quarantine "/Applications/Thuki Nightly.app" + ``` + + > **Why is this needed?** Thuki ships outside the Mac App Store, so Gatekeeper blocks it until this one-time command clears the quarantine flag. It is safe and [documented by Apple](https://support.apple.com/en-us/102445). The one-line installer does this for you. + +5. Open the app. It will appear in your menu bar. + +## Build from source + +**Prerequisites:** [Bun](https://bun.sh) and [Rust](https://rustup.rs) + +```bash +# Clone and install dependencies +git clone https://github.com/quiet-node/thuki.git +cd thuki +bun install + +# Launch in development mode (hot-reload frontend) +bun run dev +``` + +See [CONTRIBUTING.md](../CONTRIBUTING.md#development-setup) for the full development setup guide. + +To produce a standalone app instead of running the dev server, build it and open the bundle directly: + +```bash +bun run build:all +open src-tauri/target/release/bundle/macos/Thuki.app +```