Wisp

Many tasks are better handled with AI assistance than complete delegation. Wisp makes that collaboration faster, more user-friendly, and more customizable as an open-source co-working platform.

Wisp gives you hotkey-driven AI that can read your selection, clipboard, app, browser, documents, or screen snip while you stay where you are. Press a hotkey, choose an action, and stream the answer into a small overlay or at your input cursor. It is completely open-source, cross-platform, extensible, permissively licensed, and 100% Python, so it stays easy to tinker with: the kind of openness that even billion-dollar products like Microsoft Copilot still do not offer.

Languages: English | 简体中文 | 繁體中文 | Français | Español

Website: Wisp Docs

Quick start | What it does | Demos | Configuration | Free APIs | Privacy

Overlay query: Press a hotkey, choose an action, and get a streamed answer without leaving the app you are already using.

Known Issues

Known issues

What Wisp Does

Wisp is for the moments when opening a chat app would break your flow.

Highlight text, press the general hotkey, hit one action key, and Wisp asks your configured model with only the context sources you enabled. Replies stream into a compact bubble next to the floating icon. Configure TTS for read-aloud, or enable auto-speak replies if you want answers spoken as they arrive.

Highlights

• Overlay first - a floating icon, action picker, and reply bubble stay on top without taking over your desktop.
• Full chat window - click the floating icon to open a persistent chat that remembers past conversations, keeps the context you captured in the overlay, and can expand a quick overlay reply into a longer back-and-forth.
• Live ChatGPT/Codex and Claude agents - choose Wisp, ChatGPT, or Claude Agent at the top of Settings, then choose whether conversation continuity stays with Wisp or transfers to the selected agent. The Codex CLI app-server and Claude Agent SDK can run behind Wisp with live reasoning summaries, replies, tool progress, approvals, and optional resumable sessions. Transcript pull/push/export remains available as an offline fallback.
• Privacy by default - Wisp has no hosted storage layer; data stays on your machine unless you send it to your chosen model, and privacy mode can warn or redact before sensitive context leaves.
• Highly customizable - every hotkey, action key, prompt, context source, paste-back behavior, model route, voice setting, and bubble dimension can be changed.
• Approachable GUI - Settings, setup checks, privacy reports, memory tools, and model warnings explain what is happening without requiring you to read the code.
• Context capture - Wisp can read selected text, clipboard text, focused UI, open documents, browser content, recent files, and optional screenshots, so it does not have to rely on screen grabs alone.
• Voice in and out - local STT via faster-whisper, plus on-device neural TTS (Kokoro, and GPT-SoVITS voice cloning) or cloud/compatible voices (Cartesia, ElevenLabs, OpenAI, any OpenAI-compatible server), with TTS and auto-spoken replies off by default.
• Vision snips - draw a region with Ctrl+Alt+Q and send the screenshot to a vision model.
• Rewrite and paste - use the rewrite hotkey to rewrite selected text with captured context and paste the result back into the active field.
• Bring your own provider - Groq, Anthropic, OpenAI, Google, DeepSeek, OpenRouter, Mistral, XAI, Together, Cerebras, Z.AI / GLM, NVIDIA, SambaNova, GitHub Models, Hugging Face, Chutes, Vercel, Fireworks, Cohere, AI21, Nebius, custom OpenAI-compatible servers, GitHub Copilot, and more.
• Local memory - optional short-term and long-term memory are stored locally, with a viewer for editing or deleting facts.
• Addons and MCP - extend Wisp with hooks, tray actions, settings, model-callable tools, actions, and hotkeys; a bundled MCP bridge turns any Model Context Protocol server into tools the model can call.
• Agent tasks - a sandboxed task framework exists for longer jobs that need decomposition, review, and artifacts.

Demos

Vision snip: The snip flow is for cases where visual context matters. Ctrl+Alt+Q lets you draw a region, send just that crop to a vision model, and keep the answer in the overlay instead of switching apps.

Context-aware rewrite: Wisp can gather useful app context without taking a screenshot, so the model knows what you are working on. Then the rewrite hotkey rewrites only the selected text and targets paste-back at the original field captured when you pressed the hotkey.

Sandboxed agent run: The agent task flow is for longer workspace jobs. Wisp can split a task across coordinator, builder, and reviewer roles, inspect project files, make a focused change, run checks, and leave behind a final report and artifacts for the run.

Workflow

Example flows:

Quick Start

There are two supported ways to start Wisp.

Option 1: Packaged App

Use this if you want the app without cloning the repo or managing Python dependencies.

1. Download the latest asset for your platform from GitHub Releases.
2. Unpack the archive and start the packaged app.
3. Open Settings to add your model provider keys, voice settings, and preferred hotkeys.

Release pages include SHA256SUMS.txt so you can verify the archive after
download. On Windows, run:

Get-FileHash .\Wisp-<tag>-windows-x64.zip -Algorithm SHA256

Compare the hash with the matching line in SHA256SUMS.txt. Windows may still
show a SmartScreen warning for unsigned builds from an independent open-source
publisher; the checksum confirms the file matches the release asset uploaded by
the project.

Option 2: Repo Launcher

Use this if you want to run from source, develop Wisp, or test the latest checkout.

Clone the repo:

git clone https://github.com/SunnyLich/Python-AI-assistant-overlay.git
cd Python-AI-assistant-overlay

Then start Wisp with the repo launcher for your platform:

The first launch provisions the Python environment and installs dependencies. Later launches go straight into the app.

To build your own packaged copy, see Building an EXE for local build commands and the tagged-release workflow.

Requirements:

• Python 3.12, pinned in .python-version
• Windows 10/11, macOS 13+, or Linux with X11 for the full hotkey/screenshot path
• At least one configured LLM provider key or local compatible server

For full runtime logs, use the matching debug launcher:

Start Wisp Debug.bat
Start Wisp Debug.command
Start Wisp Debug.sh

Configuration

Use the Settings window for normal setup. It can store provider keys, choose model routes, configure voice, run a setup check, explain missing optional features, and show warnings for unsupported model capabilities. Provider keys and OAuth tokens are saved in the OS keychain: Windows Credential Manager, macOS Keychain, or Secret Service/KWallet on Linux, not a plain-text config file.

ChatGPT / Codex and Claude CLI

The first App setting, Run conversations with, chooses the engine for both overlay queries and the full chat window:

Select ChatGPT or Claude Agent to see its login status and Sign in, Sign out, and Refresh actions. ChatGPT mode requires the Codex CLI; Wisp stores its Codex login and resumable sessions in an isolated local profile so they do not appear in your personal Codex history. Claude Agent uses the bundled SDK when available and authenticates through the Claude Code CLI.

Conversation goes to controls continuity. Choose Wisp to send the complete local Wisp history on every request without retaining a provider continuation link. Choose ChatGPT or Claude Agent to transfer the history once, store the returned session ID, and resume that provider session on follow-up prompts. Wisp always keeps a local display copy and keeps Wisp, ChatGPT/Codex, and Claude histories in separate namespaces so switching engines cannot append to the wrong conversation.

While an agent works, Wisp streams its reply plus every visible reasoning summary, plan, tool start, command or file status, and approval request the provider exposes. Private hidden chain-of-thought is not available. A provider badge below the floating icon opens live controls for the next turn: model, project, fast mode, reasoning effort, visible summaries, and one of three permission modes—ask, allow changes within the project, or plan-only read-only.

The project is either selected explicitly or inferred from the resumed session, attached files, and file context, then falls back to Wisp's current directory. Changing the project starts a clean provider session. Agent write access stays scoped to that project; Codex also runs without network access in its workspace sandbox.

Live agent sessions are the supported path. Experimental transcript pull/push/export is a local compatibility fallback: pull reads Codex and Claude JSONL history without contacting either provider; push requires confirmation, makes a full backup, and appends only Wisp-only turns; export requires confirmation and creates a new transcript without overwriting existing provider history. See the full live-agent guide.

For source builds and advanced setups, .env.example documents the available configuration keys. You usually do not need to edit those by hand.

For no-cost and free-tier model options, see Free Model API Sources.

Default Hotkeys

Every caller, hotkey, label, prompt, context source, paste-back setting, and UI dimension is configurable from Settings.

Addons

Deeply extensible, Wisp transforms with addons - new features, new workflows, new possibilities. Each addon lives in its own folder under addons/ with an addon.toml manifest, and runs in its own isolated Python host process, so a crash, a slow hook, or a bad dependency in one addon cannot take down the brain worker or any other addon. Capabilities are opt-in: an addon only gets what its manifest declares, and missing permissions are denied. Addons that need third-party packages get a dedicated virtual environment that you approve before it runs.

In portable packaged builds, Wisp creates an addons folder next to Wisp.exe
when that folder is writable. If the app is installed somewhere read-only, use
Addon Manager -> Open addons folder to open the fallback user-writable addon
directory.

An addon can hook into Wisp at several points:

• Context - read or rewrite the prompt and context before a query is sent.
• Tools - register model-callable tools the model can invoke mid-answer.
• Responses - observe completed responses to log, save, or forward them.
• Actions and hotkeys - add its own action rows and global hotkeys with custom prompts.
• UI - contribute tray actions, settings fields, and notifications.
• LLM actions - run its own capped model calls from a hook or hotkey.

What addons can do: because an addon can inject context, expose tools, and react to responses, the surface is broad. A few examples, and the hook each one uses:

If you can write it in Python and it fits one of the hook points above, you can wire it into the same hotkey-driven overlay you already use.

MCP Client and Server

MCP Client: use external servers inside Wisp

Wisp ships with an MCP bridge addon (addons/mcp_bridge) that acts as an MCP client: list any Model Context Protocol servers in its servers.json and Wisp exposes their whole toolkit to its model as Wisp tools. This lets the overlay use external MCP capabilities without leaving the desktop workflow. See the Addon guide for the full manifest and hook contract, or the Add-ons page in the Wisp documentation site.

MCP Server: Wisp Context Server

Wisp also ships a local MCP stdio server called Wisp Context Server. Trusted MCP clients such as Claude Desktop, Cursor, and Codex can launch it to read live desktop context; the Wisp app itself does not need to stay open.

It provides five read-only tools:

• get_selected_text — the text currently selected on the desktop.
• get_clipboard — clipboard text.
• get_active_window — the active app, window title, and browser URL when available.
• read_browser_page — text from the visible browser page.
• take_screen_snip — a screenshot of the primary monitor.

Connect a client

Start Wisp once, then copy the mcpServers entry from addons/mcp_bridge/claude_config_snippet.json into your MCP client's configuration. Wisp generates this snippet with the correct local path to its own Python interpreter and addons/mcp_bridge/context_server.py; do not substitute system Python. See the MCP Bridge server setup guide for platform notes and troubleshooting.

Only register the server with clients you trust: tool results can contain selected text, clipboard content, browser content, and screenshots from your desktop.

Privacy And Control

Wisp is designed as a local desktop assistant. Storage stays on your machine, and requests go directly to the model provider or local server you configure.

• Local data stays local: settings, chats, memory, privacy reports, and configuration are stored on your machine.
• Keys in your OS keychain: provider keys and OAuth tokens are stored in the secure password store built into Windows, macOS, or your Linux desktop.
• Direct requests: model requests go straight from your machine to the provider or local server you configured.
• You choose what is sent: your configured model provider receives only the prompt you send and the context sources selected or enabled for that caller.
• Previews stay local: Wisp may inspect available context locally to show token estimates, availability, and privacy redaction counts before you send. Previewing a source does not send it to the model provider or save it as chat/memory.
• External chat sync stays local: pulls are read-only and never contact provider services. Experimental push/export actions require confirmation; pushes back up and append to an existing transcript, while exports create a new transcript without overwriting provider history.
• Per-hotkey context control: ambient app context, clipboard, documents, browser pages, GitHub context, memory, and screenshots can each be disabled, attached up front, or exposed as model-fetchable context where supported.
• Separate tool permissions: allowed tools are separate from context controls and cover the remaining model-callable capabilities, such as local file tools and add-on tools.
• Privacy mode: privacy-first setup checks and warning behavior stay enabled, including redaction status before sensitive context is sent.
• Off until configured: optional voice, document reading, browser content, screenshots, GitHub Copilot, and addons stay inactive until you set them up.
• No surprise connections: cloud TTS, model providers, compatible servers, or GitHub Copilot are contacted only when you configure and use those features.
• Sandboxed addons: addons run in isolated Python host processes and must declare the capabilities they need.
• Lean setup checks: heavy provider, audio, and STT stacks are not imported unless the feature is enabled.

Advanced Privacy Mode

Choose Settings → App → Privacy mode to use one of three mutually exclusive modes: Off, Built-in (the default), or Advanced. Built-in mode uses local pattern matching for credentials, tokens, payment details, and other structured secrets. Advanced mode keeps those rules and adds the optional OpenAI Privacy Filter, running entirely on your computer for context-aware detection of names, addresses, email addresses, phone numbers, private URLs and dates, account numbers, and secrets.

The advanced model is an optional download of about 2.8 GB plus its dedicated local runtime. Wisp loads it into memory and warms it in the background when Wisp starts or after you enable Advanced mode. Warm-up may take tens of seconds on a CPU. If you send a request before it finishes, that request waits; later scans reuse the loaded model and are faster. Wisp replaces detected spans with stable placeholders such as [PERSON_1], can show a review before sending, and checks the redacted text again. If the advanced model is unavailable, detection fails, or sensitive text remains, Wisp blocks the cloud send.

Privacy filtering reduces accidental disclosure; it is not a guarantee of anonymization or regulatory compliance.

Platform Status

*This application was only tested on macOS during two weeks of major development, and I cannot test it afterward due to limited hardware access. If you find bugs on macOS, please create an issue on this repo and I will try my best to fix them. Better yet, if you can provide a solution, please create a pull request.

Feedback And Platform Help

Bug reports are welcome, especially for desktop behaviors that depend on OS permissions, window managers, audio devices, or display servers. If you hit a crash, missing permission, broken hotkey, capture issue, paste-back failure, or setup-check warning that looks wrong, please open an issue with your OS version, launcher, logs, and the action that triggered it.

Logs can be found under the build_logs/ folder.

We are currently working on Linux Wayland support, and help testing or improving it is especially useful. macOS support testing is also welcome; these platforms have the most native integration edge cases, so real-world reports from different machines, desktop environments, and permission states make Wisp better for everyone.

If you want to support this project and the broader mission, you can contribute to the development directly or make a donation here.

• Developer README - setup, runtime entrypoints, checks, and debugging notes.
• Code overview - subsystem ownership and runtime boundaries.
• Addon guide - addon manifest, permissions, hooks, tools, hotkeys, and packaging.
• Building an EXE - Windows packaging notes.

Free Model API Sources

Wisp is free, and you can keep your model costs at zero too. Several providers offer free-tier examples, free monthly credits, or no-cost rate-limited access. Wisp reaches most of them through its OpenAI-compatible client — a few have a dedicated provider value, and the rest work through the custom endpoint. Choose the provider and add the key in Settings → LLM.

These examples were reviewed on June 27, 2026 against provider docs, Z.AI docs, npm metadata, and OpenRouter's free LLM API comparison; OmniRoute was checked against its README on July 1, 2026. Free tiers change often, so confirm current limits, credit amounts, and eligibility on the provider's own pricing page before you depend on them.

Free tiers are rate-limited and change often, so add at least one fallback route, avoid sending sensitive context to providers that may train on your prompts, and treat trial, non-commercial, or agent-specific offers as evaluation-only unless the provider says otherwise. For the full how-to-connect guide and caveats, see the Free API sources page in the Wisp documentation site.

License

MIT