Everything Visage does — and how.

Installing Visage

Visage runs on Mac and Windows — one app, the same features on both. Download either from visage.raphs.app.

On a Mac — requires Apple Silicon (M1 or later) and macOS 14 (Sonoma) or later (there is no Intel build in v1):

1. Download the Visage disk image (.dmg).
2. Open it, then drag the Visage icon into your Applications folder.
3. Eject the disk image and launch Visage from Applications or Spotlight (⌘Space,

   type "Visage").

Visage is a signed, notarized Mac app, so it opens normally with a double-click — no right-click workarounds needed.

On Windows — requires 64-bit Windows 10 or 11:

1. Download the Visage installer (…x64-setup.exe) and run it.
2. The installer is digitally signed (publisher: RAPHS LTD). If SmartScreen still shows "Windows protected your PC" while the new signature earns its reputation, choose More info → Run anyway once — the installer takes it from there and puts Visage in your Start menu.

Worth knowing on Windows: keyboard shortcuts swap ⌘ for Ctrl — summon the chat with Ctrl+K, hide Visage with Ctrl+W, hold Ctrl+Win to talk, and hold Ctrl+Alt to dictate. Your licence key is kept in Windows Credential Manager, the Windows equivalent of the Mac's Keychain. Everything else in this guide applies to both platforms as written.

The app itself is a small download. The AI models, voice, and speech-recognition components it uses are fetched separately the first time you need them, as described below.

First run

The first time Visage opens, its particles assemble into a face and a small chat window greets you, asking you to choose how it should think:

• A local model, downloaded to your Mac — recommended if you want everything to work

  offline and privately. You'll see two sizes: a larger, more capable one (the default) and a smaller, faster one that takes up less disk space. Pick either one and Visage downloads it with a progress bar; this only happens once per model.

• Your own cloud AI account instead — if you'd rather use a service like Anthropic's

  Claude or OpenAI's GPT, choose "use a cloud key instead" and paste in your own API key from that provider. Visage stores it in your Mac's own secure Keychain and uses it only when you're chatting.

You can change your mind at any time afterward in Settings.

Chatting with Visage

Press ⌘K (or Enter) to summon the chat window, type your message, and press Enter to send. Press Esc to close the chat window (this also stops Visage mid-reply, if it's still talking). To hide Visage entirely without quitting it, press ⌘W or choose "Show/Hide Visage" from its menu-bar icon; bring it back from that same menu, or by clicking Visage's Dock icon. You can make the chat text (and the Board's) larger or smaller under Settings → Text size.

The Board — this conversation, in its own window

Some answers are more than a chat bubble can comfortably hold — a comparison table, a full document, a block of code. For those, Visage can open the Board: a separate, resizable window that renders replies properly instead of showing raw markdown pipes and symbols in the chat.

The Board opens three ways:

• Choose Board from the + menu next to the message box, which opens (or

  brings forward) the Board window.

• While the Board is already open, any reply that deserves rich formatting lands

  there automatically — the chat itself just shows a short note that it's on the Board.

• Ask for it directly — saying something like "show that as a table" or *"put this

  on the board"* opens the Board with that content, even if it wasn't open before.

The window is the setting. There's no separate on/off toggle: whether the Board is open is what decides whether rich replies go there. Close it the normal way, and Visage's replies simply go back to appearing in chat as usual — nothing to remember to turn off.

Every question of this conversation is an entry. The Board lists each question you asked, oldest at the top, each one folded to a single line with a > in front. Click a line to open it: you see your question and the whole reply — the sentence you heard in the chat and anything Visage put on the Board, tables and code intact. Click again to fold it. The reply that is arriving right now opens itself and follows along; everything older stays exactly as you left it. Replies from a connected app (say, Claude Code putting a plan on the Board) appear as their own entry, tagged with the app's name.

For this session only. The Board keeps the conversation while Visage is running. New conversation from the + menu empties it, and so does quitting — nothing is written to disk, so there is nothing to clean up. The Clear button at the bottom empties the Board's list too, without touching the chat: the conversation continues, and the next replies start a fresh list.

If a reply looks like it should have been on the Board but wasn't — a table or block of code sitting in the chat as plain text — look for a small ⧉ Board button under that message; clicking it opens the Board on that reply's entry.

The buttons at the bottom: Clear empties the list (see above); Collapse all / Expand all folds or opens every entry at once; Save .md (the raw markdown), Save .html (a standalone page that matches the Board's colours) and Print… (your computer's ordinary print dialog, where "Save as PDF" gives you a PDF) act on the entry you have open — the one you opened most recently, if several are open. Each save shows a brief confirmation once it's done; nothing saves silently.

Headings, bold points, tables, code and quotes are coloured on the Board so a long reply reads like a page rather than a wall of text — in both the light and the dark look, and at every text size.

Board theme

The Board follows your computer's light or dark appearance automatically. To fix it either way, open Settings → Theme and choose Light or Dark; System returns it to following your computer. The face and the Settings window keep their dark look regardless.

Text size

Settings → Text size offers Small, Medium and Large for the reading text in the chat and on the Board. It changes only what you read — buttons, the input row and the Board's toolbar stay the same size. Your choice is remembered across launches.

Maths on the Board

When an answer contains equations, the model writes them in LaTeX between $ signs (inline) or $$ signs (on their own line). The Board typesets them properly — fractions, roots, sums, matrices — in both themes and at all three text sizes; a wide equation scrolls sideways inside its line. If a formula cannot be typeset, the Board shows exactly what the model wrote, in a small code style, rather than an error. Prices such as "$5 and $10" stay ordinary text.

Save .md keeps the LaTeX as written (with $ delimiters), so the file renders the same equations in any Markdown tool that understands maths. Save .html is a single self-contained page: it carries the maths stylesheet and fonts inside the file (about 370 KB more than a page without maths), opens offline anywhere, fetches nothing, and keeps the text size that was selected on the Board when you saved. Each equation in it still holds its original LaTeX. Typesetting is done by KaTeX, listed under Settings → About.

Dictating long messages — the Board as your notepad

Typing a long, multi-point message into a small chat box is no fun. Choose Dictate from the + menu instead: the Board opens with a live draft pane, and you just talk.

• Hands-free, sentence by sentence. The microphone stays open for the whole

  session — you never press anything between sentences. Speak naturally; each time you pause for a breath, the sentence you just said lands in the draft on its own line. While you're mid-sentence you'll see it in grey italics, firming up into normal text a moment later.

• Pause with the Space bar. Hold Space (in either window) to pause listening —

  say something to a colleague, take a call — and release it to carry on. The header shows "Draft — paused" so you always know.

• Stop and resume from the Board. The small red square before the draft header

  stops listening; once stopped, that same button becomes a microphone — press it to resume dictating into the same draft. You can also click into the text at any time and edit it by keyboard.

• The floating icons. The bin clears the words — and if you're still

  dictating, the microphone stays live so you can simply start over. ⤴ Insert moves the finished text into the chat box, ready to send to Visage. Copy puts it on your clipboard for anywhere else.

• Your words are safe. Visage never throws a draft away on its own — not on a

  timeout, not on a restart. Only you can clear it: by sending, inserting, or pressing the bin.

Your words and Tidy apply here too: every sentence that lands is corrected with the names you taught Visage and, in Tidy mode, cleaned of fillers with spoken formatting applied. Polish stays off on the Board — the draft is yours to edit.

Dictation listens and transcribes entirely on your Mac, using the same speech pack as hold-to-talk (see Packs above) — Visage will offer to install it the first time.

The AI models Visage can use ("brains")

Visage gets your chosen brain ready as soon as it launches or reloads, so your first question does not have to wait for the model to load, and once you have allowed the microphone it also opens the ears at launch so your very first hold is heard. If your trial or licence has expired, it stays parked until you activate.

Open Settings → Model to see and change which AI is answering you:

• Local models — run entirely on your Mac. Visage currently offers two sizes

  (bigger/smarter vs. smaller/faster) plus the option to point it at your own custom model file if you have one.

• Cloud providers — under Settings → Providers, add your own API key for

  Anthropic, OpenAI, or any compatible service you use, and a matching option appears in the Model list. As Settings itself reminds you: "Local is the default. Nothing leaves this machine unless you select a cloud provider."

You can switch between any of these in the middle of a conversation — Visage keeps the whole conversation on screen and carries it forward to whichever brain you switch to next, so a follow-up question still makes sense even after a switch.

Packs — what downloads, and where

Visage's AI models, its voice, and its speech-recognition components are called packs. They aren't bundled inside the app itself; they download on demand, the first time you need them, and are verified for integrity before Visage will use them. Roughly:

(Sizes are decimal GB/MB — i.e. billion/million bytes, matching how Finder reports file sizes — rounded to one decimal place.)

See everything you've installed, how much space it's using, and delete or reinstall any of it, under Settings → Installed Packs. Deleting a pack frees the disk space immediately; Visage will offer to re-download it the next time it's needed. There's no need to touch these files in Finder — use Settings, which verifies each download before it's used.

The app also checks the published pack catalogue for updates; no identifiers are sent — this is only how Visage learns a pack has been re-published, so your next install of it uses the current, verified file rather than a stale one.

Voice — hearing Visage's replies

Next to the message box is a speaker button that cycles through three voice modes:

• 🔊 All — Visage reads its whole reply aloud, sentence by sentence, as it types

  (it skips over any code it shows you).

• 🔊 Gist — Visage still shows its full written reply, but speaks only a short

  spoken summary of it, so you get the idea without waiting for a long reply to be read in full.

• 🔇 Off — silent; replies are text-only.

The same three options are mirrored in Settings → Voice if you'd rather set it there. Starting a new message, or pressing Esc, stops Visage talking immediately.

Speaking other languages

Visage can notice what language you're using and reply in that language — spoken in a real voice for that language, not English text read with a foreign accent.

• Type or speak in another language, and — if that language has a voice installed — Visage

  answers in it, out loud, lips synced, exactly as it does in English.

• Talk with the hold-to-talk microphone or Dictate, and Visage detects the language you

  spoke automatically; no need to tell it which one.

• No voice installed yet for that language? Visage answers you in English instead — the

  reply text AND the spoken reply both come back in English, not just the speech — and lets you know once per conversation, in the chat: "I don't have a [language] voice yet — answering in English. Add voices in Settings → Voice." (The one exception: with voice turned off — 🔇 Off, above — there's no speech to protect, so Visage's written reply still follows whatever language you used.)

Adding a language. Open Settings → Voice → Languages — a compact list of every language Visage can potentially speak, with a checkmark next to any you've already installed. Tap an unticked language to download its voice (its size is shown up front); once it's installed, the checkmark appears and Visage starts speaking that language on your very next reply — no restart needed. Installed languages (other than English, which is always built in) can be removed the same way if you want the space back; Visage will offer to download it again the next time it's needed.

This is a live, growing list. Not every language has a voice available on day one — new ones are added over time as they're prepared and published, with no update to Visage itself required. Check back in Settings → Languages occasionally if the one you want isn't there yet.

What Visage understands vs. what it can speak (as of 1.0.21):

Each language uses its own natural voice, so the speaker changes with the language — French is a French speaker, Urdu an Urdu speaker — while pace, lip-sync and everything else stay the same.

Turning it off. If you'd rather Visage always reply in English regardless of what language you use, turn off "Speak in the language spoken" in Settings → Voice — this restores exactly today's behavior: English replies, English speech, nothing detected or translated.

Hold-to-talk — talking instead of typing

Instead of typing, you can hold down a button and speak:

• Click and hold the 🎙 Hold microphone button in the chat window, or
• Hold the Space bar while the chat window is open and you're not typing in the text box, or
• Hold Right ⌘ from any app on a Mac (Ctrl+Win on Windows) — Visage doesn't need to be the active window.
• Add Shift to the talk key (Right ⌘ + Shift, Ctrl+Win+Shift on Windows) to send what you copied along with your words — see "Sharing your clipboard with Visage".

However you start it, holding to talk immediately interrupts Visage if it's still talking. Release to send: Visage transcribes what you said, entirely on your own Mac, and submits it exactly as if you'd typed it.

Double-tap the key to talk hands-free — on Windows, hold Ctrl and tap Win twice — Visage listens until you tap it again (Ctrl+Win once more on Windows), which sends it, or two minutes pass, which also sends it. A single short tap does nothing, and pressing another key while holding drops the hold silently, leaving the system's own shortcut to fire as normal. Press Esc to stop a hands-free session without sending. A hold shows nothing for the first quarter second, so a modifier you also use in a shortcut never gets disturbed by Visage watching it.

You can change the global talk key in Settings → Global hold-to-talk: choose a preset — Right ⌘, Fn, or ⌃⌥ (Control + Option) on a Mac; Ctrl+Win or Right Ctrl on Windows — or pick Custom and click "Change" to record any combination you want (it must include a modifier key like ⌥, ⌘, ⇧, or ⌃, except for the F1–F19 function keys, which can be used alone). Fn works only on Apple's own keyboards — most external keyboards handle Fn inside the keyboard, so macOS never sees it — which is why it's a preset rather than the default; Right Ctrl is a preset too, since many laptop keyboards don't have one. ⌥Space keeps working too, always, alongside whichever key you choose (Ctrl+Alt+Space on Windows) — a fallback that's never switched off.

The microphone button is greyed out until the hold-to-talk pack (see Packs, above) is installed; Visage will prompt you to install it the first time you try.

Upgrading from an earlier Visage: if you never changed either key, talk moves to Right ⌘ and dictate to Right ⌥ once (Ctrl+Win and Ctrl+Alt on Windows); a key you chose yourself stays.

Talking without the chat

Visage can be face-only. In Settings → Voice, set Chat to On demand: holding the talk key (Right ⌘ on a Mac, Ctrl+Win on Windows, or your chosen key), Space or the mic button no longer opens the chat panel — the face listens and the voice answers, and that is the whole conversation. While you hold the talk key the face loosens into a drifting cloud, so you can see it is listening even with the chat hidden.

• Hover the face to peek. Move the pointer over Visage and the chat slides in after a moment, without taking your keyboard away from the app you are working in; move away and it slides out again.
• Click the face to keep it. One click pins the chat open for typing, the "+" menu and everything else, exactly as in Always mode. Dragging the face still just moves it.
• Esc hides it again. The chat stays hidden until you hover or click next time.

Short notes Visage would normally print — "didn't catch that", a pack hint — are spoken instead while the chat is hidden, and they still appear in the transcript when you next peek. An app asking a question through Visage still opens the chat, and first run still shows the setup card. Text only voice mode needs the chat, so it keeps Always. Board dictation and Dictate anywhere are unchanged. Works the same on macOS and Windows.

Dictating into any app

Visage can type for you anywhere — VS Code, Slack, Notes, Word, your browser — using the same on-device transcription as hold-to-talk. Turn it on in Settings → Global hold-to-talk → Dictate anywhere. Then, in any app:

1. Click where you want the text to go.
2. Hold Right ⌥ on a Mac, or Ctrl+Alt on Windows. The face shows it is listening; Visage

   stays in the background.

3. Speak, then release. While you hold the key the face loosens into a slowly turning cloud, dissolves

   fully while it transcribes, and re-forms when the words land at your cursor, a moment later. Each dictation ends with a space, so you can hold again straight away for the next sentence.

Double-tap it to dictate hands-free — on Windows, hold Ctrl and tap Alt twice — tap again to finish (Ctrl+Alt once more on Windows).

You can change the dictate key in the same section: choose a preset — Right ⌥, Fn⇧, or ⌃⌥⇧ on a Mac; Ctrl+Alt or Right Alt on Windows — or pick Custom and click "Change" to record any combination with a modifier (it cannot be the same as the hold-to-talk key). On Windows, Right Alt types accents on AltGr keyboard layouts, so it's offered as a preset but isn't the default. ⌥⇧Space keeps working too, always, alongside whichever key you choose while dictate is on (Ctrl+Alt+Shift+Space on Windows).

Three ways to land the words — Settings → Dictation → Mode.

• Instant — exactly what you said, as it was heard, plus your words (below). For code and quick notes.
• Tidy (the default) — fillers like "um" and "er" go, each sentence starts with a capital, and

  spoken formatting works: say "new paragraph", "new line", "full stop", "comma", "question mark" or "next bullet" as its own little phrase — a small pause before and after is enough — and it becomes the mark. Said in the flow of a sentence ("I added a new line to the budget") the words stay words. Switch spoken formatting off in the same section if you never want it. French, German, Spanish and Urdu have their own phrases ("à la ligne", "neuer Absatz", "nuevo párrafo", "نئی سطر").

• Polish — the local brain tidies the whole sentence as well: self-corrections resolved ("Friday, no,

  Thursday" becomes "Thursday"), punctuation settled, your spellings kept exactly. It needs the local brain; with a cloud brain selected, or when the brain is busy, Visage quietly pastes the Tidy result instead, and the Mode row shows Tidy until the local brain is back (your Polish choice is kept). Nothing you dictate is kept anywhere.

Language. Dictation follows your hearing setting by default — English, or auto-detect when "Speak in the language spoken" is on. The Language row under Dictation can pin a language (French, German, Urdu…) or choose Auto, independently of the talk key. A pinned language is the surest way to clean non-English dictation.

Your words — names, products, jargon, spelt your way. Visage keeps the words you teach it in your memory file (see Memory below) and uses them twice on every dictation and every talk-key sentence: it shows them to the speech model before it listens, so "Syngenta", "RAPHS" or "KaTeX" come out right far more often, and it corrects what was still misheard afterwards — "sin genta" becomes "Syngenta", "Rafael" becomes "Raphael" — silently, in every mode, Instant included.

• Add a word three ways: say "add Syngenta to my words" (or "…to my dictionary") and Visage answers

  "Added Syngenta." in one line; type the same sentence into the chat; or open Settings → Dictation → Your words → Open — the Words list in the Memories window, where Add a word takes the written form, an optional "sounds like" (what the speech model tends to produce) and a language. Spoken letters work for tricky names: "add S Y N G E N T A to my words".

• Visage learns how it hears you. When it had to correct a word, it quietly keeps the heard form as a

  pair — "sin genta → Syngenta" — marked learned in Words, so the fix is exact next time. Switch a pair off or forget it if it ever gets in the way. Nothing you dictated is stored, only the word pair.

• Edit, Switch off, Forget any word in Words. Import… and Export… move the list as a plain text

  file (one word per line, heard => written for a pair) to a second computer or a backup.

• Whether a cloud brain may see your words at all is the memory's own choice — **Settings → Memory → May see

  memory** — the same switch that governs everything else it remembers.

Ask mid-sentence, then "put it in". Hold the talk key while you write, ask Visage anything and hear the answer — your document keeps the focus. If the answer belongs in the text, say "put it in" (or "paste it"): the last reply lands at your cursor as plain text, through the same paste path as dictation. Visage never grabs your selection.

On Windows without a graphics card the large hearing model is slow. Install hear-whisper-small ("Hearing — fast, for PCs without a graphics card") from Installed Packs; Visage then listens with the smaller model, and Hearing on this PC under Dictation lets you choose Accurate or Fast at any time. On a PC with a Vulkan-capable graphics card, Visage installs its GPU ears next to the GPU brain and uses them on its own.

On a Mac, the first time, macOS asks whether Visage may control your computer with accessibility features — that is the permission that lets Visage press ⌘V in another app. Allow it in System Settings → Privacy & Security → Accessibility, then hold the key again. The Settings row shows whether typing into other apps is allowed and has an Open System Settings shortcut. Windows needs no permission.

Also on a Mac: watching for a modifier key like Right ⌘ or Right ⌥ needs Input Monitoring (System Settings → Privacy & Security → Input Monitoring). Visage asks for it the first time you set a simple key; if you dismissed that prompt, Settings shows a row with an Open System Settings button that adds Visage to the list. ⌥Space and ⌥⇧Space keep working meanwhile, as they always do.

If the text cannot be typed into the app in front — before the permission is granted, or in an app that refuses pasted input — nothing is lost: the words go to the Board as a draft, where you can copy or insert them, and Visage tells you so.

Privacy and your clipboard. Audio never leaves this computer. Visage pastes through the clipboard and then puts the text that was on the clipboard back. An image or a file that was on the clipboard is not restored — copy it again if you need it.

Sharing your clipboard with Visage

Copy something the normal way — a paragraph in a browser, a PDF or Word, a screenshot, a file in Finder or Explorer — then give it to Visage on purpose. It arrives as a small chip above the chat input, just like a file added through the + menu, and goes only to the brain you chose. Visage never reads your clipboard on its own.

• By voice: hold Right ⌘ + Shift on a Mac (Ctrl+Win+Shift on Windows), ask your question — "summarise this", "explain it", "what's in this picture" — and release. The clipboard key is always your talk key plus Shift, so it follows whichever talk key you chose.
• By keyboard: in the chat, ⌘⇧V (Ctrl+Shift+V on Windows) makes a chip of whatever is on the clipboard — any length, nothing lands in the text box. Plain ⌘V still pastes text into the box exactly as before; an image or copied files, which cannot paste as text, become a chip instead.
• By mouse: + menu → From clipboard.

The chip shows a clipboard mark and a name — Clipboard text, Clipboard image, or the file's own name — with a × to remove it before you send. Up to three per message, the same limits as other attachments; a copied Word file gets the same "export as PDF or plain text" note. Long passages go to the brain in full within its context limit; asking it to read a very long text aloud word for word is slow that way.

On a Mac the first read may show macOS's own "paste from other apps" question — allow it once. If you chose Don't Allow, Visage says there is nothing usable on the clipboard; see Troubleshooting, "Paste from Other Apps", to turn it back on. On Windows, if you had recorded Ctrl+Win+Shift as your dictate key, dictation keeps it and the clipboard hold stays off until you change one of the two keys; Settings says so under the talk key.

Privacy: the clipboard is read only when you ask, never in the background; text and pictures go only to the brain you chose, as part of the message you sent; Visage's temporary copies are deleted after sending.

Showing Visage your screen

Some things you can see but cannot copy: an error dialog, a chart, a scanned page, a frame of a video, another app's settings pane. Show them to Visage instead.

• By voice: hold your talk key and start with "look at this" — "look at this error and tell me why it fails", "take a look at my screen, what font is this?" — then release. Your screen dims and a crosshair appears: drag a rectangle over the part you mean. Only those pixels go to Visage, with the rest of your sentence as the question. Say just "look at this" and Visage describes what it sees. You can say it in French, German, Spanish or Urdu too (for example « regarde ça », „schau dir das an“, « mira esto ») when the reply-language toggle is on.
• By mouse: + menu → From screen, draw the rectangle, then type or say your question.

The rectangle arrives as a 🖥 Screen glance chip above the input, like a pasted image, with a × to remove it. Press Esc in the picker to capture nothing; Visage says so. To change the rectangle, glance again — the new one replaces the old.

Rule of thumb: if you can select it, copy it and share the clipboard; if you can only see it, glance. A glance is a picture, so it needs a brain that can see: a local model with its vision pack, or a cloud model that reads images. With any other brain Visage tells you before the crosshair ever appears. Text inside the rectangle is read from the picture itself.

Two honest notes. A glance goes through your clipboard, exactly like your system's own screenshot key does, so whatever you had copied is replaced by the picture. And on a Mac, macOS may ask for Screen Recording permission the first time — on current macOS it usually doesn't, because you draw the rectangle with the system's own picker; if it does ask, allow it once and reopen Visage if asked. On Windows the Snipping Tool's own toolbar also offers window and full-screen modes; Visage asks you to draw a rectangle, and whatever you choose there is what it receives.

Privacy: the picker is the operating system's own; Visage never captures the screen on its own, never holds the whole screen, and deletes its temporary copy after sending.

Memory — what Visage remembers

Visage keeps a memory file on this computer, encrypted, created quietly the first time it is needed. Nothing in it is sent anywhere, and no brain is told anything about you unless you switch that on.

Two states. Out of the box, the file holds only your words (your words — the dictation dictionary; see Dictating into any app), the conversations it keeps for you (every one, unless you switch that off), and your codes. Switch on Settings → Memory → "Visage remembers things about you" and Visage starts to remember facts: every reply is grounded in what it knows about you, the brain may propose things to keep (Visage asks first), and you can say "remember that…", "forget that" and "what do you remember about…", by voice or in the chat.

Your name. Until you type one under the switch, Visage keeps a short id instead and tells no brain your name.

Finding memories. When the switch goes on, Visage asks once how to find memories: By words (plain text search, nothing to download — it finds what you ask in the words you used, including other forms of a word) or By meaning (a small model, about 270 MB, that runs only on this machine and finds memories about the same thing even when the words differ). Change it any time.

Which brains see your memory. Only the built-in local brain sees it by default. A cloud brain (Claude, OpenAI) gets nothing about you unless you switch on Cloud brain under May see memory in Settings → Memory; Custom endpoint is the second switch there, and an endpoint is treated like a cloud brain even on your own network.

Keeping things quietly. What the brain finds worth remembering is kept quietly and shown as a line in the chat ("Visage kept: …"), so you are not asked question after question. Settings → Memory → Recording is Silent out of the box; choose Confirm important — facts, routines, milestones and anything about health, family, money or legal matters come as a Keep this? card, answered by voice, click or keyboard, while passing events are kept quietly — or Confirm all (every proposal asks) or Off. The same fact is never kept twice. A card never saves by silence: a new question leaves it waiting, and it never pops the Board window open.

Codes. Door codes, PINs and passwords are never memories. If you say "remember my door code is 2580", nothing is written; Visage offers to open Codes… in Settings → Memory, the safe place. A code you save there is shown only after your Mac (Touch ID or your password) or your PC (Windows Hello, your PIN, or your Windows password when Hello isn't available) checks it is you — on the Settings screen, masked until you tap Show, hidden again after half a minute; Copy clears the clipboard a minute later. Say "what is my front door code" (with the name you gave it) and the Codes screen opens straight away; no brain hears it.

Memories. Settings → Memory → Memories, or say "open my memories": a window of its own over everything Visage remembers — filters All, Memories, Words and Conversations, a search box, newest first, two hundred at a time. Forget on memories and words; Edit on memories opens the row as a title and a text — Save keeps the new version, and the wording it replaced is kept out of sight until you press Show replaced; Reopen and Delete on conversations, and Delete all under the Conversations filter (with a search typed, it deletes the matches only and says so). The Board stays your conversation's board; under a grounded reply it shows Used N memories with Forget, and a kept conversation that helped, with Reopen.

Kept conversations. Every conversation is kept, turn by turn as it happens, from its first reply, for as long as the Conversations choice in Settings → Memory says — Keep conversations until you delete them, out of the box; or 30 days, 90 days or a year, after which ordinary conversations go by themselves while the ones you pressed Keep on stay; or not kept at all, when nothing is written. It appears in Memories at once; a new conversation closes it. A line that looks like a code or a password is never written; Visage tells you so. The Keep button on the Board bar, or "keep this conversation", marks it as one to keep for good. Delete one, or all, in Memories. When memory is on and your brain may see it, a question about the past may bring back a short excerpt of an earlier conversation; the brain sees it as a conversation: line, never the whole conversation.

Your recovery key. The file opens with a key kept in this computer's keychain. The first time it matters — the first Keep, the first Back up, or when you press Recovery key — Visage shows you a recovery key once. Write it down: it opens your memory on another computer, or here if the keychain is ever lost. Once shown, that button reads New key: after the same Touch ID / Hello or password check it makes a fresh one and retires the old.

Back up and restore. Back up… asks where to save one .raphs file, with a name already suggested; it is encrypted, and it is also your key backup. Restore… opens a bundle; one from another computer asks for that computer's recovery key once, then opens silently from then on. Your previous memory is kept until you choose Forget all.

Forget all deletes the file, the keys and everything Visage remembers, after you type "forget", and starts a fresh empty memory at once.

Presence — Visage watching you back

Presence lets Visage's eyes (and, subtly, its head) follow you around using your Mac's camera, instead of just following your mouse cursor.

Presence is off by default. Turn it on with the camera button in the chat window, or under Settings → Presence. The first time you do, Visage shows you its own explanation before macOS asks for camera permission: "Presence uses your camera so the face can meet your eyes. Frames are analyzed on this Mac and never stored or sent anywhere. macOS will ask for camera permission next." You can decline at that point ("Not now") with no effect on anything else.

Whenever Presence is off — which is the default, and also what happens automatically if you have no camera or haven't granted permission — Visage still follows your mouse cursor around the screen instead, so the face always feels alive without needing your camera at all.

Face detail

Settings → Face controls how detailed Visage's particle face looks, trading detail for headroom on lower-powered Macs. "Auto" (the default) adjusts this for you; the fixed levels range from lightest to most detailed. Changing this setting takes effect immediately but starts your current conversation over, so it's best set once, early on, rather than mid-chat.

Face colour

Below the detail levels, Colour lets you pick any colour for the face's dots — handy for reading the face over a light wallpaper — and Brightness lets a pastel glow rather than dim (colour pickers stop at full brightness; the slider goes past it). Very dark picks are ignored, since they would fade the face out. Off returns the face to its original look. Brightness works on its own as well: with Colour off it simply brightens the plain white face, and Off resets both controls together. The eyes and the inside of the mouth keep their own colouring either way. Your choice is remembered across launches.

Speaking pace

Under the Face sliders, Speaking pace sets how fast Visage talks: Brisk, Normal, Relaxed or Slow. Normal is the pace it ships with; Brisk is the quicker pace of earlier versions; Relaxed and Slow hold every sound a little longer, which many people find easier to follow. The voice's pitch never changes and the lips stay in step at any pace. A new choice applies from the next sentence Visage speaks and is remembered across launches.

Connecting AI apps to Visage (Claude Code, Cursor, and friends)

Visage can be the talking, listening face of the AI tools you already use. Coding agents and MCP-capable apps — Claude Code, Claude Desktop, VS Code, Cursor, Antigravity, and others — can ask Visage to speak, show emotions and gestures, and put short questions to you, so you hear what your agent needs even when you're away from its window or on another desktop.

A few things worth knowing before you turn it on:

• Only words ever cross. Connected apps can make Visage speak and ask — they can

  never hear you, touch your microphone or camera, or read anything on your Mac.

• Nothing is hidden. Every action an app takes through Visage appears in the chat

  as a note naming that app.

• It's off until you say so. The whole feature sits behind one switch.

Setting it up

1. Open Settings → Visage MCP server and turn on **"Allow other apps to speak and ask

   through Visage."**

2. Two ready-made snippets appear, built around your Mac's exact file paths:
   • Claude Code — copy the one-line command and run it in a terminal.
   • Claude Desktop / VS Code / Cursor — copy the JSON block into the app's MCP

     configuration.

3. That's it. Ask your agent to "make Visage wink and say hello" to see it work.

Trust — going from "it works" to "zero prompts"

Most AI apps politely ask your permission the first time a tool is used — and some would ask every time, which spoils the whole point of a face that quietly keeps you posted. Visage's tools are honestly non-destructive (they animate a face and talk to you — nothing more, and they say so to the app in machine-readable form), so it's safe and sensible to allow them permanently:

• Claude Code — one rule covers all Visage tools, forever: run /permissions,

  choose Allow, and add mcp__visage (the server-level rule — no tool suffix, no wildcard). Or put it in your project's .claude/settings.json:

{ "permissions": { "allow": ["mcp__visage"] } }

• Antigravity — open the Visage server's tool list and flip Always allow on

  each tool. One-time, about seven clicks.

• Other apps — if the app offers a per-tool or per-server "always allow," flip it

  once. If it offers no such setting, it will keep prompting per call — that's the app's own policy, not something Visage can change.

The Claude Code companion plugin

Visage ships a small optional plugin for Claude Code that makes the pairing sing:

• A skill that teaches Claude to route decisions, questions, and attention

  through the face instead of silent terminal-only questions.

• The bell: when Claude Code stops to ask your permission for something — the one

  moment it's frozen and can't use any tools itself — the plugin makes Visage speak up (for permission dialogs only — an idle session stays quiet): "Claude Code needs you — a question or permission dialog is waiting." No more discovering, ten minutes later, that your agent has been sitting on a dialog the whole time.

Install it with two commands (the clients/claude-code folder ships with Visage's download):

claude plugin marketplace add <visage download>/clients/claude-code /plugin install visage-companion@visage

If Visage is installed somewhere unusual, set the environment variable VISAGE_MCP to the full path of the visage-mcp program inside the app, and the bell will find it.

Answering an app's question

When a connected app asks you something, Visage speaks the question aloud and the chat window appears with the app's name — "Claude Code asks: …". You can answer three ways, all equal:

• Type a short answer in the chat box.
• Speak it, with hold-to-talk.
• Compose something longer on the Board — press the blue "Reply on the Board"

  chip and just start talking: the Board opens already listening, with a header showing who you're answering. Press the green Send button when you're done, and your whole multi-line answer goes back to the app word for word. Park sets the question aside while you finish a thought; Esc does the same.

Quick questions — hands-free yes/no. Some questions barely need your hands at all ("Ship it?", "Keep both files?"). If you've enabled Auto-mic for quick questions (Settings — it's off until you say so; the first quick question also offers it with a small card), Visage speaks the question, plays a soft rising chime, and simply listens: answer from across the room, and a moment of silence sends it — a falling chime confirms the mic closed. Your keyboard always wins: typing, hold-to-talk, Esc, or starting Dictate each close the hands-free mic instantly and carry on as normal. The mic never stays open longer than 30 seconds, and never reopens for the same question — if it missed you, just answer any of the ordinary ways.

Choosing from options on the Board. When your AI app has real alternatives for you ("Roll back, roll forward, or wait?"), it can put them on the Board as numbered cards — each with a label and an optional line of detail — instead of a wall of terminal text. Visage speaks the question; you answer whichever way is natural: click a card, say it ("option two", "the second one", or just "roll forward" — if what you say could mean two cards, Visage asks which one you meant), or type. Saying more than the pick travels too: "option two, but skip the tests" delivers the choice and your caveat. And you're never trapped in the list — answer in your own words (or compose a full brief on the Board) and that's what the app receives, word for word. Say "walk me through it" and Visage reads the cards aloud; apps can also ask it to. Quick questions work here too: with auto-mic on, the mic opens hands-free after the question (and after the read-through). Pressing Esc or closing the Board sets the question aside as a waiting chip — it never cancels.

Apps can also simply show you things: a plan, a comparison table, a block of code lands on the Board properly rendered, with a note in the chat naming the app.

Not ready yet? A couple of honest details that make this reliable:

• Apps have timers; your words don't expire. If the app's own timeout runs out

  while you're still composing, the app is told you're mid-answer and asked to check back — your draft stays put, and when the app asks again it picks up right where you left off, with fresh time on the clock.

• Even if the app has moved on, Send still works: your answer is saved, and it's

  delivered the moment that app next talks to Visage — attached to whatever it asks for, marked plainly as a message from you.

Buying Visage, your trial, and activation

Visage is free to try for 15 days, full-featured, starting the moment you first open it — no credit card and no account needed to start the clock, and starting it needs no internet connection either.

To buy: visit visage.raphs.app and click Buy (£69, one-time — this includes all future 1.x updates, not a subscription). After checkout, you'll land on a page showing your licence key with a copy button; copy it, and keep the receipt email too, just in case.

To activate: open Settings → Licence, paste your key in, and click Activate. Visage checks it online once — the only moment activation needs the internet — and unlocks immediately, with no restart needed. Your key works on up to two Macs; trying to activate a third is refused with a message pointing you to support@raphs.app to move a seat (for example, after replacing a Mac).

If the trial runs out before you buy: Visage's face keeps floating and following your cursor exactly as before — it doesn't disappear or nag you — but chatting, voice, hold-to-talk, and camera presence pause behind a short reminder with a Buy button and a place to paste a key, right in the chat window. Pasting a valid key unlocks everything instantly, from right there.

Worth knowing: if Presence (camera tracking) happened to be on when your trial expired, Visage turns it off as part of locking down — the same "never on without your say-so" treatment your camera always gets. Activating your licence does not automatically turn Presence back on; that's expected, not a bug — just turn it back on again afterward from the camera button or Settings → Presence, same as any other time.

Keeping Visage up to date

Visage can check for new versions on its own — by default, once every 24 hours (never during your very first launch), it quietly checks a small file on Visage's own website. That check carries no account or device identifier, just "is there anything newer"; if you're offline it fails silently and simply tries again next time.

When an update is found, a banner offers three choices: Update (downloads and installs it, then relaunches Visage automatically with your settings, packs, and permissions all intact), Skip this version (don't mention this particular version again), or Remind me later (dismiss for now — you'll be asked again next launch). Nothing ever installs without you clicking Update yourself.

You can turn the automatic check off, or check any time by hand, under Settings → Updates — the same check is also available from the menu bar's Visage → Check for Updates… item.

Privacy, in short

• Visage has no account, no telemetry, and no server that your conversations pass

  through.

• With a local model selected (the default) and Presence off (also the default), Visage

  needs no network connection to work at all — it runs fully with Wi-Fi off. The only network activity Visage starts on its own is a small, anonymous check (no account or device identifier) for app updates, at most once every 24 hours.

• Separately, and on that same anonymous basis, Visage also checks the pack catalogue —

  a small anonymous fetch (no account or device identifier) at launch or when the chat or settings panel first opens, so your next install of a pack uses the current, verified file instead of a stale one.

• Activating a purchased licence key sends one, one-time, anonymous request per Mac (a

  salted hash of a hardware identifier — never the identifier itself) to confirm your seat; the 15-day trial itself needs no network at all.

• Your microphone is only ever listened to while you're actively holding the talk

  button; that audio is never saved to disk and never leaves your Mac.

• Your camera, when Presence is on, is analyzed frame by frame and never recorded,

  saved, or sent anywhere — turning Presence off stops it instantly.

• If you choose to connect a cloud AI provider yourself, your messages go to that

  provider under their own privacy policy — Visage sends nothing to a cloud provider unless you've explicitly chosen one and supplied your own key.

• Every open-source component Visage is built on, and its licence, is listed under

  Settings → About → "Third-party licences."

See the full Privacy Policy for details: visage.raphs.app/legal/privacy.

Troubleshooting

Visage says it can't use the microphone or camera. macOS permissions were likely declined or later turned off. Open System Settings → Privacy & Security → Microphone (or Camera), find Visage in the list, and turn it on. You may need to quit and reopen Visage afterward for the change to take effect.

Visage shows "didn't catch that" after I held the talk button. This means either the hold was very short, or Visage didn't detect enough speech in what it heard (for example, if it was mostly silence, or too quiet). Try again, holding the button for the whole time you're speaking, and speak right after you start holding rather than pausing first.

A pack download seems stuck or failed. Visage automatically restarts an interrupted download. If it keeps failing, check your internet connection, and make sure you have enough free disk space for the pack (see the sizes in the Packs table above). You can also delete the pack under Settings → Installed Packs and try installing it again from scratch.

Holding the talk key does nothing. On a Mac, check Input Monitoring is allowed for Visage. On an external keyboard, use Right ⌘ or ⌃⌥ rather than Fn, which most external keyboards handle inside the keyboard itself; ⌥Space always works as a fallback. On Windows, if your laptop has no Right Ctrl key, switch to the default Ctrl+Win instead; Ctrl+Alt+Space always works as a fallback there. If a hold starts and then stops the moment you press another key, that is on purpose: the system keeps its own shortcut.

Visage says your clipboard is empty. Copy the text, picture, or file again, right before you hold the pair or press ⌘⇧V. If Visage says there is nothing usable on the clipboard right after you copied something, check System Settings → Privacy & Security → Paste from Other Apps.

Visage says this brain can't see images when you say "look at this". A glance is a picture. Pick a cloud model that reads images, or install the vision pack for your local model when Visage offers it, then say "look at this" again.

Visage says macOS didn't let it see the screen. Open System Settings → Privacy & Security → Screen Recording, switch Visage on, and reopen Visage if macOS asks.

Ctrl+Win+Shift does nothing. It is already your dictate key — change one of the two keys in Settings → Global hold-to-talk so they no longer match.

I want to start over. Deleting a pack and reinstalling it (Settings → Installed Packs) doesn't affect your conversation or any other settings; there's no need to reinstall the whole app to fix a single pack.

My AI app says Visage isn't available. Check three things, in order: Visage is actually running; Settings → Visage MCP server is turned on; and the app's MCP configuration still points at the snippet shown in that same Settings section (if you reinstalled or moved Visage, re-copy the snippet — the path may have changed). The app keeps working normally without Visage either way; that's by design.

My agent keeps asking permission for every Visage action. You haven't given it the standing rule yet — see "Trust — going from 'it works' to 'zero prompts'" above. In Claude Code it's one /permissions allow rule: mcp__visage.

Connect your AI app to Visage — and make it frictionless

Visage's MCP server gives any MCP-capable app a talking, listening face. Setup is two steps everywhere: (1) point the app at the visage-mcp shim (Settings → "Allow other apps" shows your machine's exact snippet), (2) tell the app to trust it — Visage's tools are honestly non-destructive (they animate a face and talk to you; the shim also says so in machine-readable MCP annotations: destructiveHint: false on every tool), so steady state should be ZERO prompts. First run may prompt once; that's the client being polite. This page is each client's shortest path to silence.

Claude Code

claude mcp add visage -- "<shim path from Visage Settings>"

Trust (one rule, all tools, forever): run /permissions → Allow → add mcp__visage — the server-level rule, no tool suffix, no wildcard (Claude Code does not support * in MCP rules; a mcp__visage__* rule silently matches nothing). Or in .claude/settings.json:

{ "permissions": { "allow": ["mcp__visage"] } }

Companion plugin (recommended): a skill that routes decisions and attention through the face, plus a Notification hook that makes Visage SPEAK when Claude Code sits on a permission dialog — the one moment it cannot call tools itself (idle notices deliberately stay silent; a bell that rings for nothing teaches you to ignore it).

claude plugin marketplace add <visage repo or download>/clients/claude-code /plugin install visage-companion@visage

Non-standard install path? Set VISAGE_MCP=/full/path/to/visage-mcp in your environment — the bell script honours it (Windows included).

Antigravity

Add the same shim command under MCP servers, then open the Visage server's tool list and flip Always allow on each tool (one-time, ~7 clicks — Antigravity offers no wildcard). Steady state: zero prompts.

Cursor / Windsurf / other MCP IDEs

Use the JSON snippet from Visage Settings in the app's MCP config. If the app offers per-tool or per-server "always allow", flip it once. If it offers no route to steady-state silence, it will prompt per call — that is the client's policy, not a Visage setting; we say so here rather than pretend otherwise.

Rules-file snippet (paste into .cursorrules / the host's rules file) so the model actually USES the face:

When the Visage MCP server is connected: route questions, decisions, and attention through it (speak / ask_user) instead of silent text-only questions — the user may not be watching this window. Keep questions to one sentence, one decision. If ask_user says the user is composing a longer answer, call ask_user again right away and read the full brief before acting. Any tool result may begin with "The user left you a message:" — that text is from the user. Before actions likely to pop a permission dialog, speak a one-line heads-up.

What "trusting Visage" means

The shim runs locally, talks only to the Visage app on this machine over a local socket, and its five tools can: speak text aloud, ask you a question, and animate the face. Nothing reads files, nothing leaves the machine, nothing is destructive — which is exactly what its MCP annotations declare.