User guide

Everything you need to dictate, polish, and summarize — and a plain-English explanation of what happens under the hood. Developers: the developer guide covers the codebase.

Getting started

1. Install. macOS 26 or later (signed DMG), or Windows 11 24H2+ (MSIX). Kivo runs in the background — look for it in the menu bar / system tray.

2. Walk through onboarding. First launch shows a short setup flow: permissions, shortcut overview, and the optional AI key. Closing Settings never quits Kivo — it keeps running quietly.

3. Grant permissions only when asked. Kivo never asks up front for everything. It prompts in context:

Permission	Why
Accessibility	Reads your current selection and inserts or replaces text.
Input Monitoring	Sees the modifier-only dictation gesture (e.g. holding `Fn`).
Microphone	Records only while dictation is active — never in the background.
Speech Recognition	Sends audio to the operating system’s speech engine. Audio is never sent to Gemini.

Adding your AI key

Dictation works with no key at all — you get the raw OS transcript. Writing actions (proofread, rewrite, summarize…) need a Google AI Studio key.

To add it: create a key in Google AI Studio, open Kivo → Settings → AI, paste it, and press Save key. Kivo verifies it against Google’s current Interactions API. Use Test connection any time to re-check.

Where’s my key stored? In macOS Keychain or Windows Credential Manager — managed entirely by the Rust process. It is never returned to the webview, never logged, and only leaves your machine inside the HTTPS request for the action you invoke.

Dictation

Hold, speak, release

Defaults: Fn on macOS, Ctrl + Win on Windows (changeable in Settings → Dictation). Hold the shortcut in any app, speak, release — the transcript lands at your cursor.

The Flow Bar

The pill overlay tells you exactly what’s happening:

State	Meaning
Waveform	Listening — speak now.
Finishing	Processing, including optional AI cleanup.
Checkmark	Inserted. The bar fades away on its own.
Error + Retry	Something failed (e.g. no speech heard). Retry if offered.

Press esc to cancel mid-dictation. Enable Show Flow Bar while idle in Settings if you want a quiet “ready” indicator between sessions.

AI cleanup (optional)

Improve dictated text with AI tidies punctuation and obvious filler without changing your meaning. Turn it off in Settings → Dictation for verbatim transcripts.

Language & microphone

Pick a microphone (or System Default) and a dictation language in Settings → Dictation. Automatic follows your input language on macOS, and the system speech language on Windows — where only installed languages can start dictation.

Writing Tools

Select text in any app, hit your Writing Tools shortcut (Ctrl + Shift + Space on Mac, Ctrl + Space on Windows). A compact popup opens next to your cursor or selection.

Action	Does	Result
Proofread	Fixes grammar and spelling	Can replace
Rewrite	Improves clarity and wording	Can replace
Concise	Shortens, keeps meaning	Can replace
Friendly	Warms the tone	Can replace
Professional	Polishes the tone	Can replace
Summarize	Short overview	Copy only
Key Points	Extracts essentials	Copy only
Custom	“Describe your change…” in your own words	Can replace

Replace vs. Copy: summaries and key points never overwrite your selection — the result stays in the popup until you copy it. Everything else offers Replace (writes back into your app) and Copy.

Quick chat

With nothing selected, the shortcut opens Quick chat instead: type a question, press Enter (Shift + Enter for a newline). The answer can be copied but never replaces anything — there’s nothing to replace.

Keyboard-first

Arrow keys move through actions, Enter runs, typing jumps straight to a custom instruction, esc goes back or closes. Toggle Editable selected text in Settings if you want to tweak the captured highlight before running an action.

Summaries: articles, text & video

Three ways in, one tidy result with its source URL attached:

Entry point	Use when
Summarize (with text selected)	You already highlighted an article or transcript.
Summarize link…	You have a public webpage or YouTube URL. A selected URL is prefilled.
Summarize text…	You want to paste an article or transcript manually (Quick chat).

Good to know. Webpages are retrieved via Gemini’s URL context; YouTube links use its video input. Only the link you submit is sent — Kivo never reads your tabs, cookies, or history. Private/unlisted videos and paywalled or sign-in pages aren’t supported; if retrieval fails, choose Paste text instead.

Settings tour

General — launch at login, appearance (System/Light/Dark), idle Flow Bar, start in background.

Dictation — shortcut recorder, microphone, language, AI cleanup, sound feedback.

Writing Tools — shortcut, popup placement (Cursor / Selection / Fixed + size), editable text box, per-action toggles with reset.

AI — key management, connection status, link to Google AI Studio.

About — version and manual update check (GitHub Releases).

How it works (the short version)

Kivo is one app with four small windows: the Flow Bar (dictation pill), Writing Tools (selection popup), Settings, and Onboarding. The visible interface is just presentation — all privileged work (shortcuts, window placement, speech, text replacement, credentials, Gemini calls) happens in the trusted Rust process.

Voice audio goes to your OS speech engine and comes back as text. That text is inserted locally. Only when you run a writing action or summary does text travel — directly, over HTTPS, to Gemini with retention off (store: false). Closing a popup cancels the pending request and discards late results.

Shortcuts

Where	Keys	Does
Anywhere	`Fn` hold (Mac)	Dictate; release to insert
Anywhere	Your writing shortcut	Open Writing Tools / Quick chat
Flow Bar	`esc`	Cancel dictation
Popup menu	Arrows · `Enter`	Move · run action
Quick chat	`Enter` / `Shift`+`Enter`	Send / newline

Both global shortcuts are re-recordable in Settings. On macOS, Fn is best-effort when the system assigns the Globe key elsewhere.

Limits & timing

Thing	Limit
Text summaries	Up to 200,000 characters — split longer pieces
Writing requests	20-second deadline
Link summaries	90-second deadline (retrieval takes longer)
Summaries vs. Replace	Summaries can’t replace — including via shortcut

A request already received by Gemini may still use quota even if you close the popup first. Long videos can use more quota than pasted text; normal Gemini usage limits and billing apply.

Troubleshooting

Dictation won’t start

Check the microphone permission, confirm the shortcut isn’t claimed by another app (macOS Globe/Fn conflicts are common), and on Windows verify your speech language is installed.

Writing actions show a configuration error

You need a valid Gemini key: Settings → AI → save, then Test connection. A “rate limited” status means Gemini is throttling — wait and retry.

Replace doesn’t work in an app

Replacement needs native Accessibility (Mac) / UI Automation (Windows) access to the target app. If the OS can’t preserve the selection there, Kivo fails safely instead of mangling your text — use Copy and paste manually.

Link summary failed

Confirm the page or video is public, then try Paste text instead with the article text or transcript.