Vulpine.app, the desktop app
Vulpine.app is the desktop app on the Mac (bundle id com.voidfab.vulpine, productName in src-tauri/tauri.conf.json). Glyph is its look: an ambient overlay that sits on screen beside your work.
Living doc, checked against the code 2026-10-06
On this page “Glyph” means the app as it draws in that look; menus and logs still say Glyph. The app runs as a Tauri shell whose windows are moving to GPUI one surface at a time. It connects to the gateway and draws a swappable body (the chassis, ADR 0036) around a swappable face, the Visual Theme: Orb, Cast (textmode.js engines), LED (the scanner face) or SVG. The frontends overview lists the other ways to talk to Vulpine.
Architecture
Glyph Tauri shell
-> @voidfab/vulpine-voice-client
-> vulpine-voice-gateway WebSocket
The gateway owns STT, TTS, turn authority and the brain. Glyph owns shell integration, microphone capture, audio
playback and visuals. There is no local STT, TTS or LLM path: run vulpine-voice-gateway before you start Glyph.
First launch and the control socket
Give a newly installed Glyph its first launch from Finder. If macOS asks, click Open Anyway in System Settings →
Privacy & Security. A first launch from ssh or launchctl kickstart is refused (OS_REASON_CODESIGNING), because the
signing identity is not notarized. After one Finder launch, launchd and ssh launches of the same bundle work.
Glyph and vulpine-glyphctl talk over glyph.sock, under $XDG_RUNTIME_DIR, else under $TMPDIR (socket_path in
src-tauri/src/ipc.rs). The socket’s directory must be owner-only (0700), or Glyph refuses to start. Once the socket is
bound, Glyph writes its path to a pointer, ~/Library/Application Support/com.voidfab.vulpine/glyph.sock.path (0600).
vulpine-glyphctl tries --socket <path> or $VULPINE_GLYPH_SOCKET first (that path alone), then the pointer, then the
pointer under each earlier bundle id’s folder (crates/vulpine_bundle_move/src/legacy.rs), then this shell’s own path.
It uses the first that answers, and a stale pointer falls through (src-tauri/src/ctl_socket.rs). So a
vulpine-glyphctl in Terminal reaches a Glyph opened from the Dock, whatever TMPDIR the terminal exports.
If vulpine-glyphctl still says connection refused, find the socket with lsof -U -c glyph and run vulpine-glyphctl
with the same directory, for example TMPDIR="$(getconf DARWIN_USER_TEMP_DIR)" vulpine-glyphctl status.
A gateway on another Mac. Operations → Connection & privacy → Gateway on another Mac runs the relay
(scripts/glyph-gateway-relay) as a login agent. Name the gateway Mac’s ssh alias; it is written to [hosts] mini in
~/.config/vulpine/fox9.toml. The relay is an ordinary ssh command hop, not ssh -L. It needs
tools/gateway/glyph_gateway_remote_proxy.py installed on the gateway host as
~/.cache/fox9/runtime-relays/gateway-remote-proxy.py. The card shows the route, the relay’s state, its last hop error
and the loadout the session bound.
Configuration
Glyph reads config.toml from $XDG_CONFIG_HOME/glyph, else ~/.config/glyph (config_dir in
src-tauri/src/config.rs), and writes defaults on first run.
[glyph] chassisis the launch body until a live switch is saved. After that Glyph launches with the last body picked; an unknown id falls back toclassic. A fresh install writeschassis = "halo"and shows the Cast face in its Seal variant until a face is picked.[glyph] labs(defaultfalse) is the one Labs switch. Off, the Labs orb styles (Bricks and Voxel) are not offered in Look → Orb style, a pick of one is refused, and a remembered one draws Classic.- Gateway settings live under
[vulpine]. A file that says[foxline]is still read, with one launch line on stderr naming the new table;[vulpine]wins when a file has both.
[vulpine]
url = "ws://127.0.0.1:8780"
agent = "operator"
persona = ""
workspace = "catalog/agents/operator"
loadout = "default"
# ADR 0021 client speech-hint floor as the voice-client bargeInMinimumLevel
# (0, 1]; a mic frame during assistant playback corroborates a barge when its
# residual RMS clears level / 14. 0.18 = -37.8 dBFS (a laptop's built-in mic).
# A desk interface and microphone measured a conversational overlay at -43 dBFS
# and echo-only frames under -45 dBFS (ADR 0026 Pass 2), so it runs 0.07 (-46 dBFS).
barge_in_min_level = 0.18
workspace is the brain’s working directory on the gateway host, not a path on the Glyph’s machine. A Mac that
talks to a gateway on another Mac names the absolute directory on the gateway host, for example
<checkout>/catalog/agents/operator. An empty
workspace becomes catalog/agents/<agent>, and start_session fails if that relative path does not exist on the
gateway host.
Glyph sends no project root, cwd or Git path. When the loadout enables owned attention, the gateway resolves the project root from the agent workspace and refuses the session if that repository is unsafe or unavailable.
Hold-to-talk on the Globe key
global_shortcuts.hold_to_talk is the dictation key: hold it, speak, let go. It is absent by default. A chord table
([global_shortcuts.hold_to_talk] modifiers = […] key = "D") uses the Carbon hotkey path. The Globe (fn) key has no
scancode there, so hold_to_talk = "Globe" uses a small listen-only helper, globectl:
[global_shortcuts] # TOML allows this header after the sub-tables
hold_to_talk = "Globe"
# globe_helper = "~/.local/bin/globectl" # default: beside the Glyph binary, then ~/.local/bin
[global_shortcuts.hold_to_talk_fallback] # optional: used only when the Globe key cannot run
modifiers = ["CommandOrControl", "Alt"]
key = "D"
Glyph runs globectl (tools/globe/globectl.swift) as a supervised child. If the helper or its grant is missing, Glyph
logs why, registers the fallback chord if one is set, and still launches.
The helper ships inside Vulpine.app at Vulpine.app/Contents/MacOS/globectl, the first place Glyph looks, signed with
the app’s identity. A bundled Glyph needs no globe_helper line. For glyph-dev, build it with just build-globectl
or point globe_helper at a copy.
One-time setup on each Mac:
- System Settings → Keyboard → “Press 🌐 key” → Do Nothing. The helper only listens and cannot swallow the key, so any other setting also opens the emoji picker or switches input source.
- System Settings → Privacy & Security → Input Monitoring → enable Vulpine. macOS judges the responsible
process, which is the app when it spawns the helper. Until the grant is on, the helper prints
no_input_monitoringand retries every 5 s. After you install a new bundle, check this row again: a re-signed app can need its row toggled off and on. tools/globe/globectl --probereports both:input_monitoring(granted/denied) andfn_usage(do_nothingis the one wanted;unsetis the system default, not Do Nothing).
Two gestures sit on top of the hold:
- Double-tap for hands-free. Two Globe taps whose presses are inside 400 ms (each tap under 300 ms, no other key during it) open a dictation that keeps listening with the key up. It ends on the next tap, on Esc, or after 2.5 s with no new words in the partials (6 s to start talking). The first tap is an empty hold the gateway drops.
- Esc discards. Esc during a hold or a hands-free dictation ends it and nothing is typed. The tap only listens, so the Esc also reaches the focused app.
Both keys wait for the microphone to settle. A microphone plugged in, unplugged or made the default sends a burst of Core Audio notifications. A press inside that burst waits for it to end, at most 1.5 s, before it opens the mic.
Where the words land, and review mode
Glyph types a held dictation (dictation.v1 source: hold). It asks the screen agent over its socket
(~/.local/state/vulpine/screen/screen.sock; screen_agent_socket overrides) to type the words into the app that had
the focus at key-down. It relays the agent’s insert proof, which “scratch that” erases by.
The target is pinned. Every write carries the key-down app’s pid and bundle id, and the screen agent refuses to type if
the front app changed, so words never land in another app. A refusal shows on the chip as APP CHANGED — NOT TYPED
(NOT TYPED — <reason> otherwise), with no Scratch that beside it.
Trailing capture (hold_to_talk_trailing_capture, default true). A key-up while you are still speaking keeps the
microphone open until 250 ms of quiet, never past 1.5 s. false ends the capture at key-up. The Trailing capture
switch sets the key (below).
hold_to_talk_literal = false turns on review mode (default true: type at release). Nothing is typed at release.
The chip shows the raw words and, beside them, the tidy the gateway returns behind its deletion-only guards
(dictation_tidy). Then:
| choice | key | say (after the wake) | types |
|---|---|---|---|
| send it | Return | “send it” | the tidy |
| say it plain | Shift+Return | “say it plain” | the raw words |
| scratch that | Esc | “scratch that” | nothing |
The three keys are system-wide only while a review is open. A tidy the guard refused is never offered: the chip says “plain only” and Return types the raw words. After ten seconds with no choice nothing is typed, and the chip says so.
hold_to_talk_style picks the tidy’s style (clean, email, chat, code), and the dictation_tidy_request carries
it. With no style set (the default, “auto” in the tab), the gateway picks one for the app the hold went down on: the
loadout’s [dictation.styles], then its built-in table, then plain. The chip names the style applied: the gateway’s
dictation_tidy.style when its reply carries one, else the style Glyph sent, else auto.
[global_shortcuts]
hold_to_talk = "Globe"
hold_to_talk_literal = false # review mode; absent or true = type at release
# hold_to_talk_style = "clean"
# screen_agent_socket = "~/.local/state/vulpine/screen/screen.sock"
Glyph reads ~/.config/glyph/config.toml at launch, so a relaunch applies a hand edit. The gateway side needs the
screen agent running. The gateway admits holds unless the bound loadout says [dictation] hold_to_talk = false.
Dictation controls: Voice → Hold-to-talk, the chip and vulpine-glyphctl
Every control below takes the path its key or spoken verb takes. Nothing new crosses the wire.
- The chip. During a review it shows Send / Plain / Scratch (the Return / Shift+Return / Esc path).
After an insert it shows
TYPEDwith a Scratch that button for 6 s. A click on the chip never takes the focus from the field the words went to. - Operations → Voice → Hold-to-talk: the switch, the key’s live route and any setup still unmet, Literal / Review, the tidy style (review mode only), a read-only stream line, Scratch that, and, while a call is recorded, a meeting line with Opt out and Forget…. Meeting minutes are on the Admin’s Meetings page.
- Settings persist. The switch, the mode, the style and the key choice apply at once and are written to the
[global_shortcuts]keys of~/.config/glyph/config.toml. Every other line keeps its bytes, and the first write of a session keeps aconfig.toml.bak. The writer refuses a missing, symlinked, unwritable or unparsable file, and says so. A key choice takes effect at the next launch. - Scratch that erases the last insert inside the gateway’s 120 s window. Keep that has no button: say it, or
run
vulpine-glyphctl keep-that.
vulpine-glyphctl dictation hold [--literal|--review] [--style clean|email|chat|code|auto] # opens the mic; nothing spoken
vulpine-glyphctl dictation release
vulpine-glyphctl dictation hold --source remote # mic stays closed; PCM comes from `dictation feed`
vulpine-glyphctl dictation feed [--from <path|->] [--edges <path|->] [--rate 16000] # a hold on outside PCM (remotectl, a FIFO)
vulpine-glyphctl dictation review send|plain|scratch # an open review, as its keys
vulpine-glyphctl dictation erase-last # "scratch that" for the last insert
vulpine-glyphctl dictation status # hold, mode, style, key route, last insert — no words
vulpine-glyphctl dictation mode --literal|--review [--style s|auto] # persisted; auto = the gateway picks per app
vulpine-glyphctl dictation on|off # the switch, persisted (off removes hold_to_talk)
vulpine-glyphctl keep-that # the gateway answers aloud
vulpine-glyphctl recall --at 15:00 [--minutes 20] | --from 14:00 --to 14:30 | --last 15 [--session current]
vulpine-glyphctl meet status | opt-out [<call_id>] | forget [<call_id>]
vulpine-glyphctl meet minutes [<call_id>|last] # the typed minutes on one line — prints model text
vulpine-glyphctl enroll start [--seconds 30] | status | discard # real-voice enrollment from this mic
Each verb prints one JSON line ({"ok": …, "verb": …}) and exits 1 on a refusal. meet minutes is the one verb that
prints model text; every other verb prints counts, ids and reasons. enroll start records a speaker embedding from this
mic (10 to 60 seconds; only the averaged embedding is kept, the audio is deleted) when [speaker] enrollment_from_mic
is on and this Glyph is the voice owner.
Operations
The status capsule stays visible in every Visual Theme. Open it to see the live link, phase, session, model, capture, startup configuration and the bounded diagnostic log. When the current continuity has agent attention or settled background work, the closed capsule also shows category counts (current counts, not unread state).
Operations offers the runtime controls; authority stays in the gateway:
- microphone on/off and the exact capture device;
- the body (Classic, Island, Halo, Familiar, Ribbon, Printer) and the Visual Theme (Orb, Cast, LED, SVG; Cast engines: Seal, Sigil, Corona, Hyphae, Beat);
- window dragging from the overlay or its move handle;
- transient assistant subtitles (Look);
- the Halo’s and the Island’s glances (Voice → Glances): Level meter, the mic and Vulpine’s voice as two 8-segment
bars from the Glyph’s own analyzers (
apps/glyph/src/plugins/levelMeter.ts), and Agent attention, how many herdr panes wait and which agent waited last (apps/glyph/src/plugins/glances.ts). Each is dark when there is nothing to show, still under reduced motion, and never a click target; - Persona and Voice Profile, as the gateway reports them. When a Persona has no voice assets of its own, the deployment voice stays visible and voice switching is off;
- the model, as the gateway advertises it;
- interrupt, new session and reconnect;
- copy and clear the diagnostic JSON.
The five groups, the face mirror and the look
Operations opens on five groups:
- Look: the body (Halo; Classic, Island, Printer, Familiar and Ribbon with Labs on, and a saved one is still drawn), face and face variant, mood color, face opacity, ring light, panel look and the glances. With Labs on, also Fox follows replies and the portrait.
- Voice: microphone on/off, capture device, Persona and voice, subtitles, and hold-to-talk (key, Literal / Review, tidy style, Scratch that, the meeting line; above).
- Conversation window: its switch, Show / hide, Cards open in, Open on a show and the Capture button.
- Connection & privacy: pairing (Connect to your gateway), the gateway on another Mac, the session (interrupt, new session, reconnect, connect), model, room, Share the front app with the brain, Permissions and microphone access.
- App: the version and the updates (Sparkle on or why off, an update found, the last offer the update guard checked and its verdict, and Check now), Relaunch and Quit, the shortcuts (Mic on or off, and Show or hide: Cmd-Opt-Space), Command line, a line naming what lives in the Admin (live sessions, the events log, latency and meeting minutes), and the Labs switch. With Labs on, the collapsed Labs & diagnostics group holds the read-outs: live state with Copy diagnostics (this Glyph’s own client events, redacted, as JSON), the effective configuration, the conversation window’s health lines, Shell, Footprint, Owner export, hold-to-talk’s Trailing capture and stream line, and the Herdr attention and background-work cards.
A config that still names the face keys show_scanner or show_orb loads, and Glyph logs once that they are ignored.
Above the groups, a face mirror draws the current face small, with the body, the face, the mood and a one-line look summary (opacity, ring light, subtitles). The Voice group shows a badge while a dictation review waits, and the App group the attention count. A finalized transcript that waits to be saved shows its Retry save above every group.
The look controls apply to every face:
- Mood color: Auto follows the mood Vulpine sets as it talks. A color pins that mood.
- Face opacity: 20 to 100 percent, so you can see your work through the face.
- Ring light: an on/off switch.
- Fox follows replies (Labs): on by default. After each reply the gateway’s decision model picks a face or a
gesture for the fox (the motion plan,
[decision_shadow] motion_plan). Off asks the gateway to stop for this Glyph’s session (motion_plan_switch). The position is the webview’s own preference, notfaces.json.
A body picked in the Look group switches live. Glyph moves and resizes the window and saves the choice to chassis.txt
in its state directory. Face picks and the look are saved to faces.json in the same directory, so glyphctl, the
Admin and a fresh webview read the same choices. Subtitles are not saved.
glyphctl drives the same controls:
vulpine-glyphctl chassis <classic|island|halo|familiar|ribbon|printer>
vulpine-glyphctl face <orb|cast|scanner|phonogram> [variant] # vulpine-glyphctl face lists the variants
vulpine-glyphctl look [--opacity N] [--ring on|off] [--mood <mood>|auto]
vulpine-glyphctl subtitles <on|off>
look needs at least one option. --opacity takes 60, 60% or 0.6. --mood takes auto or one of steady, wry, sassy, earnest, reflective, hushed, menace, playful, lively or dreamy. vulpine-glyphctl status prints the chassis, face, look and subtitles.
Glyph starts with the microphone off. Turn it on from Operations or the audio shortcut. vulpine-glyphctl audio enabled|disabled returns only once capture has really changed. vulpine-glyphctl room <name> sets the room Glyph
declares at hello ([vulpine] room; room none clears it). Subtitles show only the current turn and are never saved.
The Herdr attention and background-work cards show ids and states only, never transcript, output or paths.
Owner, playback and reads from vulpine-glyphctl
vulpine-glyphctl owner [--json] # the ADR 0024 owner: attachment, owner id, lease generation, hello mode
vulpine-glyphctl playback [--json] # the last played segments (≤ 16, newest first)
vulpine-glyphctl read <url> [--restart] [--timeout <secs>] | --text <text> | pause|resume|next|previous|restart|stop|where
owner and playback exit 1 until the webview has reported one, and the resume token is never printed. A read
command waits for the gateway’s answer, at most 70 s.
See docs/frontend-interfaces.md for the complete Vigil and Glyph interface inventory and authority boundary.
Diagnostics and Session cards, Relaunch, and [owner] export
Operations shows these read-outs:
- Labs → Shell: what
vulpine-glyphctl doctorprints, from inside this Glyph (thedoctor_reportcommand): the socket path, whether it answers vulpine-glyphctl now, the pid, the launch (Finder, the Dock or launchd; a shell’s TMPDIR; XDG_RUNTIME_DIR), the launch TMPDIR, the requests in flight and the WebGPU word. Refresh reads it again. - Labs → Footprint: main, WebKit, helpers, total and lifetime max from the reporter’s read, the read’s age, and “Reported to the gateway N s ago (session …)” or why not. Read now reads it here.
- Labs → Live state: the draw loop (parked, drawing or stopped) and its idle poll.
- Labs → Owner export: the Phone can answer switch. On, the owner receipt is exported for a phone to
answer this Glyph’s dialogs (“Phone can answer: clients/foxline-glyph/owner.json · gen N”); off removes the
file and stops the export. The switch is written to
config.tomland read at launch:
[owner]
export = false # absent or true = the phone can answer
- Relaunch Glyph (Operations → App): Glyph quits and reopens its bundle with the same launch environment, so the
socket path and vulpine-glyphctl stay valid. A dev build outside an app bundle refuses.
vulpine-glyphctl relaunchdoes the same from a shell.
The welcome window: the privacy grants
The welcome window has one row per macOS privacy grant the Glyph uses: what it is for, its live status and one button. The rows are numbered steps, required first, and only the current row’s button is live. Nothing asks at launch. “All set” shows once every needed row is on.
- Microphone (required) uses macOS’s own prompt.
- Input Monitoring is for the Globe key’s helper, required only when
hold_to_talknames the Globe key. While no hold key is set, the row offers Use Globe, which writeshold_to_talk = "Globe"and starts the key with no relaunch, and Not now. - Accessibility is required while the conversation window is on, so its ⌥⇧Space does not also reach the app in front. Screen Recording joins while the window’s Capture button is on.
- For a list grant, Open System Settings opens the exact pane with a drag card: drag the Vulpine.app row into the list. A grant that needs a relaunch makes the window relaunch the Glyph, at most once in two minutes.
Typing and screen capture need no grant of the Glyph’s own: the screen agent holds them. The window opens by itself on
the first launch and whenever a required grant is missing; its switch is saved as auto_show in
~/Library/Application Support/<bundle id>/welcome.json. vulpine-glyphctl onboarding opens it, and
vulpine-glyphctl status prints one Grant line per grant (Grant microphone: granted (required)). Other ways back:
the right-click menu’s Finish setup… (only while a required grant is missing), Operations → Connection & privacy →
Permissions → Review, and the Admin’s Glyph section.
Launch the showcase: vulpine-glyphctl showcase
vulpine-glyphctl showcase [--tile <id>] opens the native visuals showcase on the Glyph’s Mac, one at a time. The
showcase must be installed beside the Glyph binary or in ~/.local/bin. The verb prints one JSON line: opened,
already_open, or a refusal (not_installed, old_build, unknown_tile, bad_tile, spawn_failed). The brain can
ask for it too (brain_frontend_control, action: "showcase"), for an owner-local caller only.
vulpine-glyphctl on the PATH: App → Command line
vulpine-glyphctl ships inside the bundle. Install vulpine-glyphctl in PATH (Operations → App → Command line) writes
a small shim that finds the installed app each time it runs, so it survives upgrades. It writes into the first folder
on your login PATH among /opt/homebrew/bin, /usr/local/bin, ~/.local/bin and ~/bin that you can write to, else
~/.local/bin. Install in /usr/local/bin… uses macOS’s administrator prompt; Glyph never runs sudo. Remove
deletes only Glyph’s own shim. The card also shows the bundle id this Glyph runs under (com.voidfab.vulpine).
Trailing capture and footprint reporting as switches
Two switches each write a config key. A switch applies to this session at once and is saved to config.toml through
src-tauri/src/config_writer.rs, the one writer, behind its guards (the operator’s own regular file, a .bak once per
session, an atomic write, only the owned key touched). A refused write holds for this session only, and the card says
so:
- Trailing capture (hold-to-talk) writes
[global_shortcuts] hold_to_talk_trailing_capture. - Labs → Footprint → Report to the gateway writes
[footprint] report. Off stops the once-a-minute reports to the gateway (the Admin then shows no “Glyph footprint, reported” for this Glyph), across binds. Read now still reads here.
[global_shortcuts]
hold_to_talk_trailing_capture = false # absent or true = on
[footprint]
report = false # absent or true = on
The webview publishes both, and screen_context_share (Connection & privacy’s front-app switch; absent = on), as
switches.json in the state dir, beside faces.json and panel-look.txt (the set_glyph_switches command, booleans
only). The Admin’s Glyph section shows them as the Trailing capture, Footprint reporting and Front app to
the brain rows, after the Panel look. Until a Glyph publishes, the rows say “on (Glyph default, nothing published
yet)”.
The conversation window as the Glyph’s sidecar
The conversation window runs as the Glyph’s sidecar process (ADR 0046), drawn in GPUI (convo-gpui). The freya window
(convo-freya) is frozen and stays the fallback.
- Operations → Conversation window: an on/off switch. On, the Glyph starts the window once it knows its session
(
<window> --observe <[vulpine] url> --session <id> --sidecar --hidden-start). The window observes this Glyph’s session read only and follows it across reconnects. It quits with the Glyph. - Show / hide slides the window in and out; its own ⌥⇧Space does the same. On the Halo, the level meter on the display’s edge is a 44 px button that opens and closes the window.
- Cards open in: the conversation window (the default) or the corner card, saved as
[conversation_window] cards. Open on a show (on by default) reopens a closed window when a card arrives. - Crashes. A window that exits unexpectedly starts again after 1 s, then after 4 s. A third crash in a row gives up, and the card says “Conversation window stopped” until Show / hide or the switch starts it again.
vulpine-glyphctl doctorprints the window’s health and a signing line.matchesormatches_shapekeeps the macOS privacy grants;cdhash(an ad-hoc build),drifted(another bundle id or team) andlocal_identity(a local certificate) say why macOS asks again. The release gate reads the samebundle-identity.json.- The binary:
[conversation_window] path, else[conversation_window] binary(a bare name), elseconvo-gpuiand thenconvo-freya, each beside the Glyph binary and then in~/.local/bin; never PATH. - What the window draws is fed through the sidecar envelope
(sidecar-envelope.v1, draft;
crates/sidecar_envelope).
[conversation_window]
enabled = true # absent or false = off; the switch writes it
# binary = "convo-freya" # optional: one window by name (default: convo-gpui, then convo-freya)
# path = "~/.local/bin/convo-gpui" # optional: one window by path; the switch writes neither
# avatar = true # the Avatar portrait (Look → Portrait writes it); absent or false = off
# avatar_model = "~/Live2D/me/me.model3.json" # the Live2D model it draws, or a .vrm; absent or "" = the built-in fox
# ascii_camera = true # Look → Portrait → ASCII camera: the fox window opens on its Camera look
# (the camera starts only on its Start camera button; the welcome window's Camera row asks)
# avatar_hood = false # Look → Portrait → Hood: absent or true = the avatar wears its hood
# (when its model has a hood parameter); false starts the window with --avatar-hood off
Look → Portrait → Avatar (Labs; off unless avatar = true) opens a fox window beside the conversation window on a
Live2D or VRM portrait, puppeted by avatar-puppet.v1. The Model field names a .model3.json or a .vrm on this Mac,
read in place. The portrait’s mouth follows the played audio and the reply’s words, and its face and gaze follow the
session’s avatar actions.
The orb drawn natively, the web page kept as an option
The overlay’s Classic disc is drawn by orb-gpui, a native GPUI window one level over the overlay, placed on the
face’s stage, with the mouse passing through to the face’s button. It uses 27.7 MiB at rest and draws nothing while the
face is still; the WebKit orb measured 72 MiB.
- Operations → Look → Orb drawing: “Native (lighter)” (the default) or “Web page”, saved as
[overlay_orb] drawn_by. - The page draws the disc whenever the native orb cannot: another look than the Classic disc, the binary not found, a failed start, three unexpected exits in a row, or “Web page” chosen.
- The binary:
[overlay_orb] pathwhen set, elseorb-gpuibeside the Glyph binary and then in~/.local/bin; never PATH. The orb never dials the gateway.
[overlay_orb]
drawn_by = "native" # or "web"; absent = native; Look → Orb drawing writes it
# path = "~/.local/bin/orb-gpui" # optional: one orb by path
The right-click menu
The right-click menu opens at the pointer: Show / Hide conversation window, Settings…, Finish setup…, Check for Updates…, Quit Glyph. It closes on Escape, on a press outside it (in another app too), on the hide shortcut, and when the Glyph loses focus. Show / Hide conversation window is grayed, with the reason, when no window runs and a press could not start one. The status pill is a toggle: its second click closes Operations.
Panels on every body
A render frame from the brain or a tool (pi_show_render: a card.v1 such as Forecast or Fleet status, or one of the
five chart kinds) draws as the panel kit’s card in the body’s panel place (src/panels/GlyphPanels.tsx, the chassis’s
renderCard slot). The place belongs to the body, so every face gets it. Each body puts the card where it never covers
the status pill or the error toast:
| Body | Where the panel goes | Most room (pt, as of 2026-10-18) | Fit | Dismiss |
|---|---|---|---|---|
| Classic (250 × 280, floating) | Over the disc, above the lip; the chip column stays over it | 234 wide, 176 tall | line | ×, Esc*, its ttl (held while the pointer is on it) |
| Island (560 × 520, top center) | A sheet below the island: under the capsule, its pill and its toast, centered | 420 wide; to 8 pt above the window’s foot (about 435 tall at rest, 345 while it speaks) | full (brief while it speaks) | ×, Esc*, its ttl (held) |
| Halo (the display) | Lower right, over the toast and pill, clear of the summoned face and the dock | 400 wide; from 36 pt under the top to 140 pt over the pill | full | ×, Esc*, its ttl (held) |
| Familiar (the display) | Lower right, over the toast and pill; lower left while the familiar itself sits lower right | 400 wide; from 36 pt under the top to the toast | full | ×, Esc*, its ttl (held) |
| Ribbon (display width × 520, bottom edge) | Above the strip’s right end, over the toast and pill | 400 wide; from 12 pt under the window’s top to the toast | full | ×, Esc*, its ttl (held) |
| Printer (280 × 480, floating) | Under the case, across the window, over the oldest slips | 264 wide; from 104 pt down to the toast | brief | ×, Esc*, its ttl (held) |
- Fit:
fullis the card as sent,briefits header, headline and summary,lineits header and summary. Every fit keeps the summary the reply says aloud. When the room shrinks (the Island while it speaks), the card steps down one fit before it paints, and back up when the room grows. A card is never cut off behind a hidden scroll. - Dismiss: the ×, a click on the card, or the frame’s ttl (five minutes when it sets none). Up to two older cards wait under the top one. Esc dismisses only where the page has the keys (the showcase, a browser): Vulpine.app never takes the keys from the app you work in.
- The look: Operations → Look → Panel look (Match theme, Graphite, Field kit, Porcelain) applies on every body. Show a sample panel draws the forecast with no gateway.
Themes: Porcelain, Night glass, Tidewater and Brass
Four Glyph Themes ship in apps/glyph/src/theme/themes/: Porcelain (warm and light: bone, lacquer, one red
listening light, a still matte orb), Night glass (dark: violet with cyan and magenta, a holographic orb),
Tidewater and Brass (warm brass and cream on a near-black case, the look before the default became the Gateway
app’s). Brass is built into the app (src-tauri/src/theme.rs), so it binds with no install. Every text pair in Porcelain,
Night glass and Tidewater meets WCAG AA.
just apps::glyph-themes-install --dry-run # what it would copy, and where
just apps::glyph-themes-install # into $XDG_CONFIG_HOME/glyph/themes (else .config/glyph/themes at home)
A file already there that differs is kept unless --force. Then Operations → Look → Theme lists them; picking
one binds it (as vulpine-glyphctl theme porcelain does), and default goes back. The chassis showcase takes
?theme=porcelain or ?theme=night-glass.