# Vervellum > [!IMPORTANT] > LLM disclosure: This codebase was written with substantial help from large language models: AI coding agents working from the [`AGENTS.md`](AGENTS.md) brief in this repo. A hotkey-summoned research panel for macOS and Linux. It looks things up, then shows its work. **Latest release:** v0.3.1 · [Download](https://github.com/L-K-M/Vervellum/releases/latest) ![Screenshot of Vervellum researching the claim that Julius Caesar's nose was three inches long](media-sources/screenshot.png) > [!IMPORTANT] > LLM Disclosure: Vervellum was built with substantial help from large language models. Press ⌃⌥⌘Space anywhere, even over another app's full-screen window, and a panel slides in at the edge of the screen. Type a question. Vervellum plans web searches, runs them, streams an answer that cites only what it actually found, and then grades its own claims against that same evidence. ## Why it's not a chat window Most floating LLM panels answer straight from the model's weights. Vervellum instead runs the searches and answers based on current sources. - **Only retrieved citations become links.** Vervellum owns the numbered source list. Answers cite `[1]` or `[2, 5]`; model-written URLs stay non-actionable and are flagged. A real citation still does not prove a claim. - **Claims get a separate assessment.** Findings are *supported*, *contradicted*, *mixed*, *not established*, or *opinion*. The first three require citations. Failed assessments retain the answer with a warning, not a verified verdict. - **A faulted answer is corrected, not just annotated.** When the check finds a claim the evidence contradicts or only half-supports, the answer is sent back once to be fixed against the same evidence — a correction of the sentences the findings name, not a rewrite. The first draft is kept, because the findings below grade the draft. A correction that never arrives, or that breaks the citation rule, is dropped and the draft stands with a warning. - **Finding nothing is a result.** *Not established* is a normal outcome, not an error state. It gives the model a place to put a claim the evidence doesn't support. - **You can watch it work.** What it decided to look up, what it searched for, how many sources it kept, how many the answer actually cites. The detail is visible while it runs and collapses to one line once it's done. - **It reads the pages, and says which ones.** Search results are summaries, and a citation to a page nobody read is the weakest link in the chain — so Vervellum fetches the pages behind the top few sources and gives the model their text alongside the summary. Each source row says which it was: **page read**, or search summary. A page that was fetched but didn't fit the model's context is listed as a summary, because that is what the answer actually had. ## Features - **Summon from anywhere.** A global shortcut that needs no permission and works over another app's full-screen window without switching Spaces. - **Threaded.** Follow-up questions carry the thread's context, including which earlier claims were left unsettled. Threads are searchable, and it's up to you whether they're kept at all, and how many are kept — older ones past the limit are deleted. Lowering the limit **in the app** takes effect at once rather than at the next question: on screen immediately, and on disk with the save that follows. Raising it again does not undo that — nothing restores a thread the list has dropped; it is re-read from a file that still has it. Lowering it **behind the app's back** — a hand edit, a sync tool, or upgrading from a build that had no setting — is the recoverable one: it trims in memory at the next launch and leaves the file alone, so raising the limit and relaunching brings the threads back. Be aware how small "until something is saved" is, though: asking one question writes the trimmed list, and that is what makes it permanent. The write rotates the previous file to `threads.json.bak` first, so there is one more chance after that and no more. Active turns are checkpointed; interrupted work reopens as incomplete, with its partial answer retained. - **Keyboard-first.** `Return` asks, `Esc` clears then closes, `↑`/`↓` walk back through earlier questions, `/` opens commands. Everything in the header is also a command. - **Ask while it's still working.** The composer never locks. A follow-up typed during a run waits its turn and starts on its own, listed above the composer and removable until it does. Stop cancels what is waiting too, and puts the text back in the composer rather than discarding it. - **Settings you can watch work.** The panel's edge, width, height and text size apply to an open panel as you change them. Opening Settings dismisses the panel — it would otherwise cover the window it was opened from — so **Settings ▸ General ▸ Preview** puts it back beside Settings while you adjust it. - **Research the selection.** An optional second shortcut opens the panel with whatever text you had selected, with credential-shaped values stripped out first. - **Paste a link and it reads it first.** A question carrying a URL has that page fetched *before* the searches are planned, so the plan is written against what the page actually says rather than against a guess from its address. The page becomes the turn's first numbered source, so the answer can cite it — and "summarise this" needs no search at all. Up to three links, and only while page reading is on; a link that is left unread says so on the turn. - **Attach a screenshot or a file.** Paste or drag an image or a text file onto the composer and it goes with the question: images as inline data, text files inlined into the payload. Up to four per question, 4 MB each; what a file *is* is decided by its bytes rather than its name. An attachment is sent on the turn it was attached to and on no other — later turns in the thread know its name, so the model can say it can no longer see it instead of inventing what was in it. Images are sent to the provider by default; a text-only endpoint that refuses one is retried without the picture, and the turn says the image was left out. Untick **Send attached images** for a provider that accepts the part and silently ignores it. Both front ends: ⌘V or a drag on macOS, Ctrl-V or a drag on Linux. - **One dial: how hard to look.** Four levels, shown in a selector above the composer with what each one does and what it may spend, and remembered until you change it. **No search** answers from the model alone and is badged as unsourced; **One pass** plans a round of searches, answers, then checks the answer against what it found; **Deep rounds** comes back up to three times for what the last round missed, putting every planned search to every configured engine whose argument schema can express it; **Agent loop** spends the same page and evidence allowance as Deep rounds, but the model picks one search or page read at a time and stops when it judges the question settled. Each is also a command — `/no-search`, `/one-pass`, `/deep-rounds`, `/agent-loop` — and typing one asks *that* question at *that* level without moving the selector. The older `/direct`, `/deep-research` and `/agent-research` still work. - **Bring your own providers.** An OpenAI-compatible Chat Completions endpoint, and for search an HTTP MCP server — recognized tools include z.ai, Brave, Tavily, Exa and SearXNG, and only recognized tool names are accepted — or a **SearXNG instance queried directly**, with no MCP bridge in between, or **Kagi** through the [`kagi` command-line tool](https://github.com/Microck/kagi-cli) you have already signed in with (macOS and native Linux installs; the Flatpak cannot reach host executables or their authentication files). Model replies must finish with `finish_reason: stop`; malformed or unfinished replies remain incomplete. On macOS, keys live in one login-Keychain item as an account-to-key dictionary. Writes also update legacy per-account items on a best-effort basis so an older build can still read keys after a downgrade. Deleting a key removes its legacy item first and only then updates the blob, so a downgraded build cannot read a key you have deleted. - **As many models as you want, chosen per question.** Configure several providers — a local server, a fast hosted model, a careful one — each with its own endpoint and its own key. Pick the one that answers next from the panel or with `/model`; every turn records the model that produced it. The refresh button beside a model field asks the endpoint which models it serves, so the name is chosen from a list rather than typed from memory — and the field stays typeable for a gateway that lists nothing. - **A failing provider hands the question on.** If the selected model doesn't respond, rejects its key, or errors, the next provider you configured is tried, then the one after it — so a rate limit somewhere else does not cost you the question. It is never silent: the turn says it happened and names the model that actually answered. Off in one switch, and a Stop is never re-sent to anyone. Two failures deliberately stop the turn instead of moving on, because they are Vervellum's rather than the provider's: a Stop, and a question too large to send — that limit is Vervellum's own and the same at every endpoint, so the next provider would refuse it in exactly the same way. - **Three ways to read a page.** **Snippets only** is the old behaviour. **Fetch directly** is the default: Vervellum requests the page itself, with no key, no cookie and no referrer — the only thing it does that contacts a site you didn't configure, so the site sees your address. **A reader service** ([z.ai's Web Reader MCP server](https://docs.z.ai/devpack/mcp/reader-mcp-server), or any MCP server with a compatible tool) fetches them instead, so the sites see the service and the service sees the URLs. Settings ▸ Providers ▸ Reading the page. - **Make it look like yours.** Ten themes — Ember, Paper, Midnight, Terminal, Solarized, Vapor, Bubblegum and more — and then every colour, the typeface, the corner roundness and the backdrop are yours to change, live, while the panel is open. A preset is a starting point, not a mode. Verdicts keep their symbols and their written labels whatever you do to their colours, so the worst you can make it is ugly. - **Native.** SwiftUI and AppKit, Liquid Glass on macOS 26, no dependencies. ## Getting started ### macOS 1. Launch Vervellum. It appears as a magnifier in the menu bar. 2. Open **Settings ▸ Providers** and fill in a model endpoint, a model name, and a web-search key. The panel offers this on first launch, because nothing works without it. **Add a provider** puts a second model beside the first; the panel and `/model` switch between them. 3. Press **⌃⌥⌘Space** and ask something. ### Linux (Ubuntu 24.04+) ```bash sudo apt install ./vervellum_0.1.0_amd64.deb vervellum --install-shortcut # binds ⌃⌥⌘Space in GNOME # or sandboxed (any distro with Flatpak): flatpak install --user ./vervellum-linux-amd64.flatpak ``` Configure a native `.deb` install by editing: ```text ~/.config/vervellum/settings.json ``` For the Flatpak, edit this file instead: ```text ~/.var/app/ch.lkmc.Vervellum/config/vervellum/settings.json ``` Flatpak gives the app its own configuration home and does not read the native path. The `ch.lkmc.Vervellum` directory is the application ID declared by the Flatpak manifest. Both files use the same JSON shape: ```json { "modelEndpoint": "https://api.example.com/v1", "modelName": "your-model", "searchEndpoint": "https://api.z.ai/api/mcp/web_search_prime/mcp" } ``` The behaviour toggles are the same keys the macOS Settings window writes: `historyEnabled`, `showProcessTrail`, `submitOnReturn` (booleans) and `textScale` (0.85–1.4). The file is read at launch. To search a SearXNG instance instead, set `searchProvider` and point `searchEndpoint` at the instance (its home page is enough — `/search` is appended): ```json { "searchProvider": "searxng", "searchEndpoint": "https://searx.example.org" } ``` For a native `.deb` install, Kagi search uses the [`kagi` CLI](https://github.com/Microck/kagi-cli). Install it, sign in once with `kagi auth`, and select it as the provider: ```json { "searchProvider": "kagi-cli", "searchEndpoint": "kagi" } ``` `searchEndpoint` is a command rather than an address here: leave it as `kagi` and it is found on `PATH` and in the usual install directories, or give the full path to the binary. The credential stays in the CLI — Vervellum never sees it, and needs no key of its own for this provider. The Flatpak cannot use the Kagi CLI backend: it neither bundles the program nor exposes host executables and their authentication files. Choose an MCP or SearXNG search provider in the Flatpak. The sandbox deliberately is not widened to run arbitrary host programs. Page reading is `pageReading`, one of `"off"`, `"direct"` or `"reader"` (default `"direct"`), with `readerEndpoint` for the reader service and its key in `VERVELLUM_READER_KEY` or the keyring under `reader-api-key`. > [!IMPORTANT] > A SearXNG instance must list `json` under `search.formats` in its `settings.yml`. > Most do not by default, and one that does not answers HTTP 403. SearXNG itself takes > no API key; store one only if your instance sits behind an authenticating proxy. `modelEndpoint` and `modelName` describe one provider, which is all the Linux build writes and the shape shown above. The macOS app can configure several and stores them under `modelProviders` (a JSON list) with `selectedModelProvider`; when that list is present it wins. The scalar `modelEndpoint`/`modelName` pair is kept for older builds: while a profile owns their fixed legacy Keychain account it mirrors that owner, and after the account is unowned and deleted it mirrors the selection. `/model` lists the profiles and switches between them on Linux too. Search providers follow the same rule: `searchProviders`/`selectedSearchProvider` hold the list, while `searchEndpoint`/`searchProvider` are the downgrade pair. Then store the keys in your login keyring, or export them: ```bash secret-tool store --label "Vervellum model-api-key" \ service ch.lkmc.Vervellum account model-api-key export VERVELLUM_MODEL_KEY=… VERVELLUM_SEARCH_KEY=… ``` No desktop at all? `vervellum --ask "your question"` runs the whole pipeline and prints the answer, its verdicts, and its sources. It needs no display and no session bus. Each level has its own flag — `--no-search`, `--one-pass`, `--deep-rounds`, `--agent-loop`, with `--direct`, `--deep` and `--agent` still working — and `--ask` is One pass, whatever the panel's selector is set to, so a script keeps costing what it did yesterday. `vervellum --help` prints what each level spends. The default level is `researchLevel` in `settings.json`, one of `"direct"`, `"research"` (the default), `"deep"` or `"agent"` — the levels' stored names, which are older and shorter than the command words above. A hand-written `"one-pass"` or `"deep-rounds"` is not recognised: it falls back to the default silently rather than failing, so nothing tells you it did nothing. The panel's selector writes this key. > [!NOTE] > On GNOME Wayland the Linux build is an ordinary window, not an edge-docked > overlay. A Wayland client can't position its own window or keep it above others, > and GNOME doesn't implement the layer-shell protocol that would allow it > (`gtk_window_move` and `set_keep_above` don't exist in GTK4 at all). The > shortcut, the pipeline, and the evidence UI all work; window placement is up to > the compositor. History now uses schema 2. **Do not downgrade with the same history file:** older releases can mistake new notices for corruption and overwrite it. Back up history before downgrading. See [SECURITY.md](SECURITY.md). ## Build & Run ### Linux Needs a **Swift 6.0+** toolchain (earlier ones lack the async `URLSession` methods on Linux) plus `libgtk-4-dev` and `pkg-config`. ```bash swift build -c release --product vervellum swift test --parallel # the shared core's tests packaging/build-deb.sh 0.1.0 # -> build/vervellum_0.1.0_.deb scripts/build-flatpak.sh build/vervellum_0.1.0_*.deb # repacks it -> dist/vervellum-linux-amd64.flatpak ``` ### macOS Requires **Xcode 26** (for Liquid Glass) and **macOS 14+** (Liquid Glass renders on macOS 26; older systems get a blurred fallback). ```bash # Build xcodebuild -project Vervellum.xcodeproj -scheme Vervellum -configuration Debug build # Release build xcodebuild -project Vervellum.xcodeproj -scheme Vervellum -configuration Release build # Run unit tests xcodebuild -project Vervellum.xcodeproj -scheme Vervellum -destination 'platform=macOS' test ``` `scripts/build.sh` does an incremental Release build through the shared `lkm-build` engine (`scripts/build.sh --clean` for a clean rebuild). ## Permissions **macOS: the core app needs none.** The global shortcut uses the system's own hotkey registration rather than a keyboard monitor, so it works the moment you launch the app. That matters in full screen, where the menu bar is hidden and the shortcut is the only way in. One optional feature needs one permission: **Research the Selection** reads the frontmost app's selected text through **Accessibility**. It's off by default, it explains itself before macOS shows its own prompt, and everything else works without it. > [!NOTE] > Release builds are ad-hoc signed (see Distribution). macOS ties an Accessibility > grant to an app's code signature, and an ad-hoc signature changes with every > build, so **every update resets this one permission**. Vervellum notices and > tells you what happened instead of failing quietly. Remove it from the > Accessibility list and add it again to restore the feature. ## Privacy There is no account system, telemetry or analytics. A question and its thread go to the selected model provider; if model fallback is enabled and that provider fails, the same request can go to the next configured model providers. **No search** makes no search or page requests, including for links pasted into the question. **One pass** uses the selected search provider, while **Deep rounds** sends each planned query to every configured search engine. Direct page reading also contacts up to three pages for One pass, or eight shared between pasted links and search results for Deep rounds and Agent loop; reader-service mode sends those URLs to the configured reader instead. Threads and preferences stay on your machine. API keys live in the Keychain on macOS. Linux reads explicit environment keys first, then the keyring, then an unencrypted mode-0600 file. Text captured by the macOS selection shortcut is scanned for credential-shaped values before it reaches the composer, and you're told how many were removed. See [PRIVACY.md](PRIVACY.md) for the complete per-stage account. ## Distribution Non-sandboxed and outside the Mac App Store, because the sandbox can't grant the Accessibility access the selection feature needs. CI publishes an **unsigned, un-notarized** build for each tag, ad-hoc signed only so it will launch on Apple Silicon. Gatekeeper will warn on first launch: ```bash xattr -dr com.apple.quarantine /Applications/Vervellum.app ``` Or right-click the app → **Open** → **Open**. The Linux `.deb` is unsigned as well. It's built in the official Swift container for Ubuntu 24.04, links the Swift runtime statically, and declares its remaining dependencies with `dpkg-shlibdeps` instead of a hand-written list. ## License Vervellum's own code is released under the [Unlicense](LICENSE). The macOS app bundles no third-party code: it links only system frameworks. The Linux `.deb` and Flatpak statically link the Swift standard library, Foundation and libdispatch (Apache License 2.0 with the Swift Runtime Library Exception) and ICU (Unicode License V3, plus the terms for its dictionaries and data) into the binary. These keep their own licenses. Their notices ship in `/usr/share/doc/vervellum/` (Flatpak: `/app/share/doc/vervellum/`) as `copyright` and `Third-Party-Notices.txt`.