A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
Gentle Dot — Design
Gentle Dot is an always-available personal assistant. It floats on the macOS desktop, is summoned from the menu bar or a global shortcut, and is also reachable from a browser. Behind it runs Gentle Shell (Pi + Gentle extensions + Engram), hidden from the user.
Status: design for local development. The VPS deployment is documented, not performed.
1. Goals and non-goals
Goals:
- One assistant, always on, reachable from the desktop (floating Dot, menu bar, global shortcut) and from a web page.
- The agent behaves exactly like Gentle Shell: same tools, ODD workflow, skills, Engram memory, and subagents. Subagents reach connectors only through the daemon's MCP proxy, like the engine itself, and load the approval guard too (S25.4; §4, Connectors).
- The user never sees Gentle Shell: no Gentle branding, commands, or terminal in the product surface.
- Everything runs locally first; the same daemon can later run on a VPS (HostGator) with Docker.
Non-goals for this version:
- Multi-user accounts, sharing, or teams.
- Calls, Slack, scheduled jobs.
- Pi Durable. Recovery relies on persisted Pi sessions plus Engram (see section 7).
- Actual deployment to HostGator.
2. Architecture
┌──────────────────────────────┐ ┌───────────────────────────┐
│ Desktop app (Tauri 2, macOS) │ │ Browser │
│ tray icon · floating Dot · │ │ http://127.0.0.1:4317 │
│ global shortcut · webview │ │ (same React UI) │
└──────────────┬───────────────┘ └─────────────┬─────────────┘
└────── WebSocket /ws + token ────┘
│
┌─────────────────────────────▼─────────────────────────────────┐
│ dot-daemon (Node 24) │
│ gateway: HTTP (static UI, /health) + WebSocket protocol v1 │
│ white-label layer: identity prompt, event sanitizer │
│ agent supervisor: spawns and restarts the agent process │
└─────────────────────────────┬─────────────────────────────────┘
│ stdin/stdout JSONL (Pi RPC)
┌─────────────────────────────▼─────────────────────────────────┐
│ gentle-shell --mode rpc --session-dir ~/.gentle-dot/sessions │
│ Pi + Gentle extensions + Engram (unchanged, configured auth) │
└───────────────────────────────────────────────────────────────┘
Repository layout (pnpm workspace):
packages/protocol shared TypeScript types for protocol v1 (client <-> daemon)
packages/daemon supervisor, gateway, white-label layer, CLI `gentle-dot`
packages/ui React + Vite web UI (served by the daemon, embedded by Tauri)
apps/desktop Tauri 2 shell (Rust) for macOS
docs/ design, deployment guide, security checklist
Why these choices
- Pi RPC subprocess, not the SDK in process. Gentle Shell is a launcher with its own home, auth, and extension loading. Spawning
gentle-shell --mode rpcreuses all of it unchanged and isolates crashes from the daemon. Verified on 2026-10-08: the RPC process loads the Gentle extensions (82 commands) and answersget_state. - One daemon, many faces. The desktop app and the browser are thin clients over the same WebSocket protocol, so the VPS story is "run the same daemon in Docker".
- Tauri 2. Native webview (small app), shares the React UI with the web, and has first-class tray, always-on-top windows, and global shortcuts.
3. Agent supervisor
- Spawns the bundled engine (
node <gentle-pi>/bin/gentle-shell.mjs --home <dataDir>/agent --mode rpc --session-dir <dataDir>/sessions --append-system-prompt <identity file>) withcwd= the assistant's own workspace,<dataDir>/workspace, so the engine never reads a.piproject config from the user's home. A customworkspace(config orGENTLE_DOT_WORKSPACE) is never used ascwdand nothing is written there; it is passed as one more--append-system-prompttext: "The user's preferred working folder is - Engine home (S35.3, #13): gentle-shell runs its first-run setup (the companion packages) only in a
--homeit created: one that did not exist, or that holds its marker.gentle-shell-home. The daemon writesauth.jsonandmcp.jsonthere before the engine's first start, so at every start, before writing anything there, it writes that marker into the default<dataDir>/agentin gentle-shell's own format ({"createdBy":"gentle-shell","version":"<gentle-pi version>"}; gentle-shell only checks that the file exists) unless one is already there. A clean install then runs the setup, and an install left without it recovers on the next start. A home chosen withGENTLE_DOT_AGENT_HOMEis never marked. Because the folder exists before the engine runs, gentle-shell's own bootstrap (the TUI'stuiModeand theme insettings.json) is skipped; RPC mode uses neither. - Isolation (S12): the child runs with its own
HOME=<dataDir>/home(0700) andXDG_CONFIG_HOME,XDG_DATA_HOME,XDG_CACHE_HOME, andXDG_STATE_HOMEunder it, plusGENTLE_PI_CONFIG_HOME=<dataDir>/gentle-ai.PATHis kept, andGIT_CONFIG_GLOBALpoints at the user's real~/.gitconfigwhen it exists, to keep their git identity. InheritedPI_CODING_AGENT_DIR,GENTLE_PI_AGENT_HOME, andGENTLE_SHELL_CONFIGare removed, and so are a parent subagent run's variables (GENTLE_PI_AGENTS_CHILD,GENTLE_PI_AGENTS_OWNED_IPC,GENTLE_PI_AGENTS_PARENT_PERMISSION_FD) andGENTLE_PI_AGENTS_PI(a command line the engine's children would run instead of the engine).GENTLE_PI_AGENTS=1turns Gentle Shell's subagents on (subagent_*andorchestrator_*tools) whatever the user's own setting;GENTLE_DOT_SUBAGENTS=off(or0,false) givesGENTLE_PI_AGENTS=0instead (§4, Connectors, Subagents). The engine's first run otherwise writes into the real~(~/.gentle-shell,~/.pi/agent/pi-pretty,~/.gentle-ai), which--homealone does not prevent. - Memory (S23): the engine uses the user's global Engram, always in the project
gentle-dot. The memory plugin accepts a server only whenengram instance-id(read from the Engram data folder, by default$HOME/.engram) matches the server's/healthinstance_id, so the child getsENGRAM_DATA_DIR=<real ~/.engram>(the inheritedENGRAM_DATA_DIRwhen set; overrideGENTLE_DOT_ENGRAM_DATA_DIR) and keeps the user's ownENGRAM_PORTandENGRAM_URL(default server 7437). If the global Engram is not running, the plugin starts it with that data folder, as Gentle Shell does. The project comes from Engram's per-folder setting: the daemon writes<dataDir>/workspace/.engram/config.json({"project_name":"gentle-dot"}) at every start, and Engram reads it before any other detection (sourceconfig). The plugin has no per-client project override (ENGRAM_PROJECTonly applies to the Engram process itself, which is the user's shared server). Memories the assistant saved earlier in its private memory (<dataDir>/home/.engram) are not moved.GENTLE_DOT_ENGRAM=privaterestores a private memory: noENGRAM_DATA_DIR,ENGRAM_URLremoved,ENGRAM_PORT=7438(overrideGENTLE_DOT_ENGRAM_PORT), data under<dataDir>/home/.engram. The memory server the engine starts there outlives the engine, so when nothing listened on the private port as the daemon started, the daemon stops it when it closes: the PID listening on that port (lsof), only when its/healthinstance_idmatches<dataDir>/home/.engram/.instance-id. - Connectors (S18): before every spawn (first start, restart, respawn) the supervisor's
prepareSpawnhook puts back the connector files from the daemon's in-memory state (§4, Connectors), then pointsmcp.jsonat the daemon's MCP proxy with a fresh key for this launch (S25.4; the previous key stops working), then hands the approval guard its policy, also from memory, in the child's environment (GENTLE_DOT_CONNECTOR_POLICY, JSON: the turned-on connectors, their modes and curated read-only tools, which of them the proxy fronts (proxied), and the protected files). The engine cannot change its own environment, so the policy cannot be edited by the assistant. The assistant's own engine loads the guard with-e packages/daemon/src/extensions/approval-guard.ts(TypeScript loads as is). - Parses stdout with strict LF framing on a byte stream. Never Node
readline(it splits on U+2028/U+2029, which are valid inside JSON). - Correlates commands by
id; stdout records withoutidare session events. - Reads stderr only as diagnostics (logged, never parsed).
- On unexpected exit: state
restarting, exponential backoff (1s, 2s, 4s, max 30s), then respawn andswitch_sessionto the last active session file. - On daemon shutdown: closes child stdin, waits up to 5s, then SIGTERM.
- The executable is configurable (
GENTLE_DOT_AGENT_BIN) so tests can use a fake agent that speaks the same JSONL protocol.
4. Protocol v1 (client <-> daemon)
Transport: WebSocket at /ws. The first message must be {"type":"hello","token":"…","protocol":1}; otherwise the socket closes with code 4401.
Client to daemon:
| type | fields | maps to Pi RPC |
|---|---|---|
send |
text, requestId |
prompt (with streamingBehavior: "steer" while busy); a repeated requestId is ignored |
steer |
text |
steer |
abort |
— | abort |
ui_response |
requestId, value | confirmed | cancelled |
extension_ui_response |
new_conversation |
— | new_session; refused with conversations_off unless the conversations list is on |
list_conversations |
— | daemon reads the session dir |
open_conversation |
conversationId |
switch_session; refused with conversations_off unless the conversations list is on |
get_history |
— | daemon reads the chat's session files (one get_state round trip first); waits for the agent to be ready instead of failing |
get_earlier |
before (id of the oldest message the window shows) |
daemon reads the page before it, from the open session file and then the earlier files of the chain |
auth_list |
— | daemon ModelRuntime.getProviders() and getProviderAuthStatus() |
auth_login |
providerId, method (oauth | api_key) |
daemon ModelRuntime.login(); one flow at a time |
auth_reply |
flowId, value | cancelled |
answers the flow's current prompt |
auth_logout |
providerId |
daemon ModelRuntime.logout() |
connectors_list |
— | daemon connectors.json (each sign-in is a reference to its item in the app's secure store) |
connector_connect |
connectorId |
adds or turns on the connector (new mcp.json, agent restart when idle), then the daemon's OAuth sign-in when not signed in |
connector_signin |
connectorId |
the daemon's OAuth sign-in (pi-mcp); one flow at a time |
connector_disconnect |
connectorId |
turns it off (the sign-in stays); agent restart when idle |
connector_mode |
connectorId, mode (read_only | read_write) |
new mcp.json; agent restart when idle |
connector_remove |
connectorId |
mcp logout <id>, then forgets it; agent restart when idle |
Daemon to client:
| type | meaning |
|---|---|
ready |
agentState, conversationId, model (display name only), features (conversations: the list and new conversation are on; default off); the current queue, pending asks, and an interrupted notice follow it |
user_message |
a user message entered from any client |
agent_state |
starting | idle | thinking | working | needs_you | restarting | error |
message_delta |
assistant text delta for message messageId |
message_done |
final assistant message; stopped: true when the user stopped it (Stop, or a switch), error with a plain-language explanation when it failed (shown inline in the chat, not as a toast) |
queue |
steering and followUp: the complete lists of messages sent while the assistant works and not taken yet (from Pi's queue_update); empty lists clear it, and it is cleared when the run settles or the agent restarts |
ask_resolved |
an ask was answered or timed out |
conversations |
conversations (id, title, updatedAt) and activeId |
interrupted |
the agent restarted while a run was active |
activity |
messageId plus sanitized tool activity: id, kind (read, edit, run, search, memory, delegate, other), title, status |
ask |
sanitized extension_ui_request dialog: requestId, method (select, confirm, input, editor), title, message, options, timeoutMs |
toast |
sanitized notify |
history |
the most recent messages (100 by default, GENTLE_DOT_HISTORY_PAGE), hasEarlier; messages from earlier sessions of the chat carry earlier: true, and the UI draws an "Earlier messages" divider after the last one |
earlier |
before, one page of messages before it, hasEarlier; message ids are s<file index>-<turn> in the chain |
error |
code, message safe for the user |
auth_providers |
providers with methods, oauthName, configured, source; open: true when the user typed /login |
auth_prompt |
flowId, kind (text, secret, select, manual_code), message, options — sent only to the window that started the flow |
auth_event |
auth_url, device_code, progress, or info |
auth_done |
ok, plain-language message on failure or cancellation |
connectors |
connectors (id, name, reads, sends, added, enabled, mode, status: off | needs_signin | connected | error); open: true when the user typed /connectors |
Sign-in (S10) and own instance (S12)
The daemon runs the Gentle Shell bundled as its gentle-pi dependency, with --home ~/.gentle-dot/agent and GENTLE_PI_CONFIG_HOME=~/.gentle-dot/gentle-ai, so nothing is shared with a Gentle Shell the user may have installed. /login is a terminal-only command in Pi, so sign-in runs in the daemon through Pi's ModelRuntime on that same home (same auth.json format, file locking, mode 0600). Typed answers are never logged. After new credentials, the daemon refreshes every window's account list and restarts the agent once it is idle, so the new models appear. Typing /login in the chat opens the accounts screen.
Every daemon message carries seq (monotonic per connection) so the UI can detect gaps and request get_history.
Connectors (S18)
- Catalog (
packages/daemon/src/connectors.ts): Notionhttps://mcp.notion.com/mcp, Linearhttps://mcp.linear.app/mcp, and Atlassianhttps://mcp.atlassian.com/v2/mcp, each remote OAuth with one click; then three guided connectors (L36), each with in-app steps shown before "Connect" and a curated list of read-only tools (fail closed):- Discord: the community server
npx -y @pasympa/[email protected](MIT, monthly releases, declaresreadOnlyHinton its tools; Discord has no official server), with the bot token inenv.DISCORD_TOKEN. The guide covers the application, the bot, the Message Content and Server Members intents, and the invite (scopebotwith read, send, and react permissions). - Slack: the official
https://mcp.slack.com/mcp(no dynamic client registration) with the user's own Slack app:oauth.clientId, an optionaloauth.clientSecret, and the fixed redirecthttp://localhost:38417/callback(oauth.callbackUrl, sent exactly as written). Slack accepts a loopback redirect only with PKCE turned on, which makes the app a public client (refresh tokens last 30 days), so the secret may be left empty; the guide lists the user token scopes. - Gmail: the official
https://gmailmcp.googleapis.com/mcp/v1(Developer Preview) with the user's own Google Cloud project: the Gmail API and Gmail MCP API enabled, the consent screen in testing (refresh tokens last 7 days), and a Web application client with the redirecthttp://localhost:38418/callback;oauth.scopeasks forgmail.readonlyandgmail.compose.gmail.composecan also send mail, so the copy says so: drafting and sending ask for approval each time, and read only hides them. Each guided connector's copy describes only what its guide's permissions allow (Slack: send and schedule messages withchat:write; Discord: send messages and reactions).
- Discord: the community server
- Typed values (S18, S19): a connector's
fieldsare asked one at a time with sign-in prompts (auth_promptsecretortext, flow idconnector-setup-*,optionalwhen the answer may be empty), in the window that started them. A catalog connector is added only when every required value is there (cancel changes nothing); an approved draft or an import is added first and staysneeds_setupuntil its values are typed. A secret value (a field markedsecret) goes to the app's secure store (below, Secrets) and only its reference stays in memory andconnectors.json; other values (a client id) stay inconnectors.json(protected). Values fill the real server in the daemon's memory in place of${input:<key>}placeholders (never the engine'smcp.json) and are never sent to a window or logged. Env values, headers, andoauth.clientSecretfollow the engine's syntax (a leading!runs a shell command and$NAMEexpands), so typed and imported literals are escaped ($→$$,!→$!); the proxy resolves them the same way before it sends them upstream, so a typed value arrives exactly as typed.clientId, the command, its arguments, and URLs are used as written.connector_setupasks again (a new token). A connector whose value is missing isneeds_setupand is left out ofmcp.json. - Drafts (S19): the approval guard registers
propose_connector({name, description, transport, command?, args?, url?, env_names?, needs_oauth?}), with secrets by name only. Its result to the model is only "The user will review this connector in the app". The draft travels to the daemon asctx.ui.setStatus("gentle-dot:connector-draft", <json>): a fire-and-forget record on the engine's own RPC output, which only the daemon reads (the agent's commands cannot write to it, and no file, socket, or key is added that the agent could reach). A typed value (${input:NAME}) may only stand for an env value (or an http server's header): anywhere else (the command, its arguments, the URL) it would put the secret into the command line or an address the model chose, so the guard answers the model "Secrets can only go into environment variables." and sends nothing, and the daemon refuses such a draft as well. The daemon checks it (lengths,httpsor loopback URLs, env names, typed values), keeps the newest five (MAX_CONNECTOR_DRAFTS; the windows keep the same five and take the waiting list again after eachready), and shows every window a card (connector_draft) with the command or URL and the secret names.connector_draft_replydecides: declining forgets it; approving adds the server (origin"Drafted by the assistant"), turned on, read only with every tool hidden (no curated list, so the proxy shows none, and in "Read and send" every call asks), then asks for each secret in the app and signs in whenneeds_oauth. The assistant still cannot writemcp.jsonor runmcp add(guard), so the card is the only way in.connectors.jsoncan hold a server of the user's own (a command), so it is signed (Integrity, below): with the app, a file edited while the daemon is not running is set aside instead of loaded. - Import (S20,
packages/daemon/src/connector-import.ts): "Import my MCP servers" (connectors_scan) reads, never writes, the configs below the user's home (GENTLE_DOT_IMPORT_HOMEin tests): Claude Desktop (Library/Application Support/Claude/and.config/Claude/claude_desktop_config.json), Claude Code (.claude.jsonmcpServers, itsprojects[*].mcpServers, and each project's.mcp.json), Cursor (.cursor/mcp.json), VS Code (User/mcp.jsonwithserversandinputs, macOS and Linux), Windsurf (.codeium/windsurf/mcp_config.json,serverUrl), OpenCode (.config/opencode/opencode.json,mcpwith command arrays andenvironment), and Gentle Shell (.gentle-shell/agent/mcp.json). Each entry maps to the engine's schema:${VAR}(Claude Code),${env:VAR}(VS Code, Cursor, Windsurf), and{env:VAR}(OpenCode) become${VAR};${userHome}becomes the home folder; a VS Code${input:id}becomes a value the user types after the import; everything else is a literal. SSE servers (type: "sse", or an address ending in/sse) are listed as not importable. The list (connector_imports) shows the name, the source apps, the command or address (summary), and env and header names only; values stay in the daemon. The summary, also shown for a custom connector in the Connectors list, is masked by structure, not by a word list: an address (an argument or the server URL, any scheme) keeps its scheme, host, and path, loses its user and password and its fragment, shows its query keys with every value as•••, and masks long opaque path segments (20 or more letters, digits,_, or-, mixing digits or cases); the argument after--header/-H, the value of--header=, and anyName: valueargument whose name looks like a credential (Authorization, Cookie,*key*,*token*,*secret*, and so on) keep only the name; the argument after a flag named like a credential (/token|secret|key|pass|auth|cred|bearer/i) and the value ofname=valueforms of the same are masked; known token prefixes (ghp_,sk-,xoxb-,AKIA,glpat-, and others) and long opaque words are masked. Values the engine resolves at start are noted before the import (notes): "Runs a command on your computer to get this value." for a leading!(the command is not shown), and "Reads the environment variable NAME." for$NAME/${NAME}. Duplicates (the same command without npm versions, or the same URL) of a connector the user has, or of a catalog entry, are marked and cannot be imported.connector_importcopies the chosen entries, read only with every tool hidden, and never touches the source files; their header and environment values go to the app's secure store (below, Secrets), with references inconnectors.json. A credential inside an imported address or command-line argument stays where it is (masked when shown; a documented limit). - The daemon holds the approved connector state (each connector's
enabledandmode) in memory. It reads<dataDir>/connectors.jsononce, when it starts; after that the state changes only through the Connectors screen. The daemon is the only writer ofconnectors.jsonand<agentHome>/mcp.json, both rendered from memory, atomically, mode 0600; neither holds a secret. The engine's policy (below) also comes from memory, never from the files. The files are watched (folder watches plus a check every second, because file events on macOS can be missed right after a watch starts), and they are also checked before every agent start and after every run. A change made by anything else is put back, a project<workspace>/.pi/mcp.jsonis removed (a.pilink loses the link, never its target), and every window gets "A change to your connectors was blocked." A change made toconnectors.jsonwhile the daemon is not running is caught by its signature at the next start with the app (Integrity, below);mcp.jsonis always rewritten from memory. Every server isexposure: "direct"(the assistant turns codemode off). Read only is enforced by the proxy (above). - MCP proxy (S25.4,
packages/daemon/src/mcp-proxy.ts): the engine's<agentHome>/mcp.jsonlists every connector as{url: "http://127.0.0.1:<port>/mcp/<id>", headers: {Authorization: "Bearer <proxy key>"}, exposure: "direct", timeout: 300}(plusenabled: falsewhen turned off) and nothing else: no real address, token, environment, or command. The key is random, kept only in memory, and new for every engine launch; the proxy accepts it only in theAuthorizationheader (401 otherwise, never from the address) and refuses any request with anOrigin. It answers JSON-RPC 2.0 as plainapplication/jsonover POST, like the computer helper (GET is 405, notifications 202):initialize,ping,tools/list,tools/call,resources/list,resources/read,resources/templates/list,prompts/list, andprompts/get. Upstream, the daemon keeps one pi-mcpMcpClientper connector, connected on first use: streamable HTTP for a remote server, with its headers and the stored sign-in (sent as a bearer token and refreshed after a 401 with the stored refresh token, never a new browser sign-in), or stdio for a server the daemon runs itself, with the engine's environment plus the server's values. A dropped connection is made again on the next request; turning a connector off, removing it, or changing its server or values closes it, and so does the daemon's shutdown. Every request reads the connector's state from the daemon's memory, so a mode change applies at once, without an engine restart (the engine still restarts to list newly allowed tools). Policy:tools/listshows in read only only the tools that declarereadOnlyHint: trueAND are on the curated list (the sameisReadOnlyToolrule the guard uses), and every tool in "Read and send";tools/callrefuses a hidden or unknown tool with a JSON-RPC error however it is called, taking the annotations from the server's own list, never the caller; a sending action (any tool that is not read-only) is forwarded only after the user approves its preview (connector, action, and every argument, key fields first) in the desktop app's native dialog, asked over the app channel (below;DotBridge.askInApp); windows only show an informational card. Declining, no answer (the app declines after 120 s, the daemon gives up at 130 s), no app to ask, the app quitting while it asks, an answer that is stopped, or a connector changed while it was asked refuses it with a JSON-RPC error that says nothing was sent. An Allow given at or after the app's 120 s is refused too, even when the app only reads it later; an Allow given before then still counts when the app reads it after the 120 s. Resources and prompts are reads: they are shown in "Read and send", and in read only only for a connector with a curated read-only list (the catalog's); a server of the user's own in read only exposes no resources or prompts, like its tools. Errors from the server are passed on with their code and message; a refused sign-in says to sign in again in Connectors; anything else says the connector could not be reached (the log masks addresses). - Secrets (S25.5,
packages/daemon/src/secret-source.ts): bot tokens, client secrets, imported header and environment values, and OAuth sign-ins live in the desktop app's secure store (macOS: Keychain items the signed app creates, servicedev.gentleman.gentle-dot.connectors;apps/desktop/src-tauri/src/secure_store). The daemon asks for them over the app channel (secret_get,secret_put,secret_delete,secret_list, below) and keeps them in memory only, until the channel closes; no secret is written to a file or a log.connectors.jsonholds{"secretRef": "<id>"}in each secret's place, with idsconnector/<id>/value/<key>,connector/<id>/env/<NAME>,connector/<id>/header/<Name>,connector/<id>/client-secret, andconnector/<id>/signin(pi-mcp's OAuth state as JSON). In a server of the user's own, every environment value, header, andoauth.clientSecretis treated as a secret unless it only names a typed field. Before the proxy uses a connector it reads the secrets it refers to; the daemon only reads ids it recorded after its ownput. Without the app (a daemon started from a terminal such aspnpm dev, the web), a connector that needs a secret fails closed with "Open the Gentle Dot app to use this connector." (the proxy answers it to every request), and a connector without secrets keeps working; there is no file fallback. Removing a connector deletes its items. - Migration (once, when the app's channel is there): text secrets still in
connectors.json, then the sign-ins of the old sign-in home (<data>/connector-signin/mcp-auth.json, the daemon's own, which win) and of the engine's old<agentHome>/mcp-auth.json(keyedmcp__<id>|<url>), are stored, read back, and compared before they leave the files; if one fails, the files stay as they were and the next start tries again. A sign-in for a connector that is no longer added is dropped (counted in the log). The old sign-in home (itsmcp.jsonheld the real servers) is removed. A 0-byte sign-in file holds nothing: it is removed and the removal is logged. One that cannot be read or is not a list of sign-ins may hold secrets: it is left as it is and reported, the other files still move, and the migration is not marked done, so the next start tries again (L117 A2).connectors.jsonthen saysversion: 2, and a sign-in file that appears afterwards is reported once and left alone, never imported (L114 N1). Until a text secret has moved it stays in the file and is not used. Nothing secret is logged. - Integrity (S25.6,
packages/daemon/src/connector-integrity.ts): every write ofconnectors.json(a change, a migration, a put-back) carriesmac, the lowercase hex HMAC-SHA256 of the textgentle-dot/connectors.json/v1\nfollowed by the record withoutmacin canonical JSON (no whitespace; every object's keys sorted by UTF-16 code unit; arrays in order; strings, numbers, booleans, and null asJSON.stringifywrites them). The key is 32 random bytes, kept as hex in the app's secure store underintegrity/connectors, created on the first start with the app, and held only in memory; it is never written to a file or logged. At start the daemon listens (so the app's health check answers), then checks the file as it was read before anything rewrites it, watches it, migrates secrets, answers the app, or starts the engine. With the app: a file that was signed before (it has amac, or the key already existed) whosemacis missing or wrong was changed while Gentle Dot was closed; it is moved to<data>/connectors.rejected-<UTC time>.json(0600; a planted link is moved as a link), the daemon starts with no connectors and a fresh signed record, the log says so once, and every window of that run gets the warning toast "Connectors were changed while Gentle Dot was closed, so they were set aside. Review them in Connectors." The Keychain items are not touched (a reference in the set-aside file is never read). The first start after T23e (an unsigned file and no key) creates the key and signs the file without refusing it. Without the app, the file cannot be checked: it is loaded as it is, the log says it was not verified, connectors that need a secret stay locked, and a signed file is put back byte for byte so its signature survives until a daemon the app launches checks it. With the app but a key that cannot be read or stored, the check fails closed: the file stays as it is, no secret is read, and every window gets "Gentle Dot could not check your connectors, so the ones that need a secret stay locked. Restart Gentle Dot to try again." A signed file deleted while Gentle Dot was closed (the key exists, the file is gone) starts with no connectors and every window gets "Your connectors file was removed while Gentle Dot was closed. Add your connectors again in Connectors." While running, a change is put back as before, signed. Limits: the signature has no counter, so putting back an older signed version of the file (for example one with a connector the user removed since) is accepted; sending actions still need the user's native approval. A same-user process that deletes the key's Keychain item and also removesmacmakes the next start sign the file as a first start. Aconnectors.jsonwritten without the app (a migration rename of acomputerentry) is unsigned and is refused at the next start with the app once the key exists; the key's Keychain item has the same limits as any other (§8). - Sign-in (S25.5,
packages/daemon/src/connector-oauth.ts) runs in the daemon with pi-mcp's OAuth, as the engine'smcp logindid (the CLI is no longer run): a stored refresh token signs in again without the browser; otherwise the authorization code flow (PKCE, dynamic client registration or the user's own client) against a loopback callback (127.0.0.1, a random port, or the connector's fixed redirect such as Slack'shttp://localhost:38417/callback). The whole flow keeps its state in memory; only the result is stored, once, withsecret_put, and a refresh after a 401 stores the new tokens the same way. The daemon relays the authorization URL to the window that started it (auth_eventauth_url, which opens the browser) and offers amanual_codeprompt: when the browser cannot reach the loopback callback, the user pastes the address it ended on, and the daemon takes the code from it only when it is this sign-in's loopback address (port and path) with itsstate; nothing is fetched. Cancel closes the callback. Flow ids start withconnector-, soauth_replyreaches the right flow; typed text and codes are never logged (URLs are masked). - Status:
needs_setupwhile a typed value is missing; for servers that sign in with OAuth,connectedwhen the connector refers to a stored sign-in with tokens andneeds_signinotherwise;connectedfor servers with a token or none;errorafter a failed sign-in. - App channel (S25.1–S25.3,
packages/daemon/src/app-channel.ts,apps/desktop/src-tauri/src/app_channel.rs): when the desktop app spawns the daemon it creates a connected pair of Unix sockets and puts one end on the daemon's fd 3 (posix_spawnadddup2on macOS, withPOSIX_SPAWN_CLOEXEC_DEFAULTclosing every other descriptor; on Linux apre_execdup2plusclose_range(CLOSE_RANGE_CLOEXEC), or anfcntlloop before kernel 5.11, marking every other descriptor close-on-exec); it keeps the other. The connection is the authentication: nothing is written to a file or an environment variable, and nothing listens. The daemon (cli.ts) opens fd 3 before it spawns anything, only when it is a socket and not Node's own IPC channel, and first checks that a child spawned the daemon's way would not hold it (a probe child compares the socket's identity on its fd 3); if one would, it closes it and runs without a channel. On macOS, libuv spawns withPOSIX_SPAWN_CLOEXEC_DEFAULT, so the engine, stdio servers, and sign-in commands never get it (app-channel-fd.test.ts); on Linux, Node marks fds 0–15 close-on-exec at startup (libuvuv_disable_stdio_inheritance), fd 3 included, so no child of the daemon holds it either; Node cannot mark an inherited descriptor close-on-exec, which is why the probe checks rather than assumes. Frames are line-delimited JSON ({"kind":"request","id","method","params"},{"kind":"response","id","result"|"error"}), each side numbering its own requests. The app sendscommand {clientId, message},computer_register {url, token}, andcomputer_unregister; the daemon sendsapprovewith{connector, action, preview: [{name, value}], title?, summary?}and gets{approved}, and the secret requestssecret_get {id}({secret}ornull),secret_put {id, secret},secret_delete {id}({deleted}), andsecret_list({ids}). The app answers on worker threads: approvals with T23b'sapprovals(one native dialog at a time, Decline the default, 120 s timeout), secrets fromsecure_storewith ids checked (check_id), refusals that never repeat a value, and nothing logged; a malformed request, a dialog that fails, or the channel closing refuses. A frame longer than 1 MiB closes the channel on either side, and a closed channel stops the daemon (below), so neither side sends one: an oversized request fails before it is written (a daemon approval is then refused), and an oversized answer goes out as an error. Lifetime (S35.2): a daemon launched with a channel stops when it closes, as on SIGTERM (engine, memory, and the connectors' servers stopped, then the process exits), whether the app quit, crashed, or was killed, since the kernel closes the app's end in every case; it stops listening first, so a relaunched app starts a daemon of its own. A daemon started without a channel keeps running until it is stopped. - Privileged messages (S25.2,
APP_COMMANDSin the protocol):connector_connect,connector_signin,connector_setup,connector_disconnect,connector_remove,connector_mode,connector_draft_replyapproving,connector_import,computer_register, andcomputer_unregisterare refused on the WebSocket (error app_required, "Open the Gentle Dot app to change connectors.") whoever sends them, the access key notwithstanding (L49). The desktop panel sends them with theconnector_commandTauri command, which the app forwards over the channel with the panel'sclientId(fromready; it only routes the sign-in steps and refusals to that window and authorizes nothing by itself). Every other message stays on the WebSocket: chat, history, accounts, profiles, models, uploads,connectors_list,connectors_scan, sign-in answers (auth_reply, owner-checked), and declining a draft. Changes that widen access are confirmed natively even though the app sent them: switching to "Read and send", connecting or setting up a connector that is off, approving a draft, and importing (each with what it adds); declining sends the windowerror declinedand changes nothing. Narrowing (read only, disconnecting, removing) and signing in again need no dialog. Without a channel (a daemon started from a terminal such aspnpm dev, the web, a VPS until T23h) these messages and every approval fail closed. Approvals the daemon asks show in every window as anaskwithmethod: "app"("Waiting for your answer in the Gentle Dot app.");ui_responseto it is refused. - Approval guard (
packages/daemon/src/extensions/approval-guard.ts,tool_callhook, nested calls included): the tools of a connector the proxy fronts (proxiedin the policy: turned on and set up) pass, since the proxy filters them and asks itself; a card here would ask twice. A turned-off connector is not inproxiedor the approved list, so its tools stay blocked here as well. For any other connector tool: it runs without asking only when it declaresreadOnlyHint: trueAND it is on the curated list. Anything else asks throughctx.ui.confirm: an ask card ("Allow Notion to create pages?") with every argument, key fields first, up to 8,000 characters (beyond that it says "(truncated, N more characters)"), shown in a scrollable block. It is blocked when declined, when no one can answer, or when the connector is "Read only". A server outside the policy is blocked; without a valid policy every connector call asks. - Credential and control files:
<agentHome>/auth.json,mcp-auth.json(where it was before the proxy),models.json(it can hold API keys),mcp.json, the old sign-in home<dataDir>/connector-signinwith itsmcp.jsonandmcp-auth.json(gone after the migration, still protected in case they appear again),<dataDir>/connectors.json,<dataDir>/token, the guard itself, and the file that loads it into subagents (<agentHome>/extensions/gentle-dot-child-guard.ts, below). The file tools (read,write,edit,grep,find,ls) are blocked on them by resolved path (any spelling,@prefix, case, symlink, or hard link), andgrepalso on any folder that contains one. Commands (bash) are blocked when, with quotes, backslashes, and string concatenation removed, they name one of those files (any case; a pattern such asmcp-a*counts), the data folder.gentle-dot,PI_CODING_AGENT_DIR,security find-generic-password(or other keychain reads), ormcp add|login|logout|remove. The command check is best effort, not a security boundary: the assistant runs as the user with a shell, so a command can always build a name the check does not see. The in-memory connector state above does not depend on it, and stage 2 (S25) moves tokens out of the engine's reach. - Stage 2 integrity (S25.6, Integrity above) covers the user's own servers too: the signature is over the whole record, so a file edited while the daemon is not running cannot add a server that runs a command, turn it on, claim an
origin, change its command, arguments, URL, env, headers,enabled, ormode, or plant a secret reference (L117 A1) without being set aside at the next start with the app. Without the app it is still loaded, but connectors that need a secret are locked there. - Subagents (S25.4, T23f;
packages/daemon/src/child-guard.ts): they are on (GENTLE_PI_AGENTS=1, §3;GENTLE_DOT_SUBAGENTS=offturns them off). A subagent is a child engine that gentle-pi starts aspi --mode rpc(lib/agents-runner.tschildArguments) with the engine's environment (PI_CODING_AGENT_DIRis the assistant's engine home, plus the guard's policy) and without--no-extensions. So it reads the same<agentHome>/mcp.json: connectors only as proxy entries with the current launch's key, where the daemon filters by mode, refuses hidden tools, and asks in the app's native dialog before every sending action, whoever calls; and the computer helper at the app's address with its key, where the app's own session grant and confirmations apply. A child also loads gentle-pi's two child extensions (child-context.ts,child-safety.ts) and whatever it discovers in the engine home, never the engine's-e, and gentle-pi offers no setting for extra child extensions (itsGENTLE_PI_AGENTS_PIoverride splits on spaces, and the app's paths have them). The daemon therefore keeps<agentHome>/extensions/gentle-dot-child-guard.ts, which imports the guard from the daemon's own install (a path fixed when the daemon writes it, never one from the environment) and runs it only whenGENTLE_PI_AGENTS_CHILD=1and the daemon's policy variable are both set: inert in the main engine (which already has the guard) and in any engine Gentle Dot did not start that shares the home. It is written (0600) at every engine start, checked with the connector files (a change or removal is put back, logged, and reported like one tomcp.json; anextensionsfolder that became a link loses the link, never its target), and protected like the guard. If it cannot be put in place (the folder's place holds a file, the file's place a folder, or the folder cannot be written), that is logged once and the engine starts withGENTLE_PI_AGENTS=0. In a child the guard blocks the credential and control files and the connector commands as in the engine; it registers nopropose_connector, because a child's status updates go to its parent engine, never to the daemon, so a draft could not reach the user. The proxy and the native approvals stay the boundary; the guard in children is defense in depth, with the guard's own limits (the agent's shell can change files between the daemon's checks, add anindex.tsor ignore file to that folder, or turn the file off insettings.json), the same reach the engine's shell already has (S25, refined in L109).subagent-probe.test.ts(opt-in,GENTLE_DOT_SUBAGENT_PROBE=1, offline) runs the real engine with gentle-pi's subagents: the child's read ofmcp.jsonis refused by the guard, a read-only Notion search goes through the proxy without asking, creating a page waits for the app's answer, and the computer helper is reached with its key.
Switching and history races (S21)
- Opening or starting another conversation while the assistant answers first asks the user ("Stop and switch" or "Cancel"). The daemon then aborts the run and waits, bounded to 10 s, for it to settle before it sends
new_sessionorswitch_session(abort-then-switch): Pi would otherwise end the run inside the new session. That stop is reported asstopped, never as an error. - A message sent while a switch or a rotation runs waits for it, so it lands in the new session after that session's
history. - History replaces what a window shows, so it is read again (up to twice) when a message arrived while it was loading. Pi writes a message to its session file right after announcing it, so the daemon makes one
get_stateround trip before each read.
One continuous chat (S22)
The UI shows one endless chat: no conversations list, no new conversation, and the header shows the assistant (the rose glyph and "Gentle Dot"). The code and protocol for several conversations stay behind features.conversations (GENTLE_DOT_CONVERSATIONS=1); with it off, the UI also ignores the menu bar's dot://new-conversation. The daemon rotates the session underneath when it grows (§7), and history / get_earlier read through the chain of session files, so earlier messages, including those before any compaction, stay reachable with "Show earlier".
Computer control (macOS and Windows, S24)
The assistant can see the screen and operate apps through a built-in MCP server that the desktop app serves. macOS (L59) and Windows (S24.11); Linux, the web page and a VPS never offer it.
S24.1 Helper: native Rust inside the Tauri app (
apps/desktop/src-tauri), never in the daemon or the engine. It serves MCP (JSON-RPC 2.0 over streamable HTTP) onhttp://127.0.0.1:<random port>/mcpand requiresAuthorization: Bearer <key>, a fresh random key per app launch.S24.2 Tools:
screenshot,click,move,drag,scroll,type,key,open_app,list_apps,wait, each with an optionalintent. Screenshots of the display under the pointer are downscaled to a long edge of 1280 px; coordinates are pixels of the latest screenshot; actions return a fresh one; Gentle Dot's own windows are left out. On Windows, a detached Store app frame is listed by its shell display name (or its window title, or the frame host when neither is available), separately from other detached frames; two of them with the same name get their window titles appended (Fotos — img.jpg), and one is marked active only when it is the foreground window itself. This name is for listing only: the minimized app cannot be acted on until it is restored and identified; the action blocklist is unchanged.S24.3 Session grant: the first call without a session shows a native dialog ("Allow Gentle Dot to see and control this Mac for 30 minutes?"). A session ends on timeout, Stop, the tray item, or the panic shortcut ⌥⇧Esc, and queued actions are dropped.
S24.4 Guards: a fixed blocklist (Gentle Dot itself, System Settings, SecurityAgent, loginwindow, Keychain Access, password managers), 10 actions per second, and a native per-action confirmation for risky actions (send, pay, buy, delete, submit, confirm, transfer, and their Spanish equivalents, by Accessibility role and title, by
returnon a default button, or by the declaredintent). Keyboard actions go only to the app that was steadily in front during the latest screenshot; their recipient is fixed when they are checked and confirmed and rechecked before each chunk of text, each Return, and the key, and a change stops the input with the count of characters already sent. After a confirmation, the app in front before the dialog must be back in front within 500 ms, or nothing is done.- Windows held-modifier guard: a snapshot of both sides of Ctrl, Alt, Shift and Win (
GetAsyncKeyState) taken before posting, not a fence against keys pressed during the post. macOS/Linux behavior is unchanged.- Keyboard: before each keyboard post (text chunk, Return, or key), read both sides of Ctrl, Alt, Shift and Win with
GetAsyncKeyState. Refuse before pressing the event's own modifiers, so an injectedctrl+tdoes not refuse itself. A pressed modifier may be the user's or one a failed post could not release, so the message names both ways out. One key reports exactly "Ctrl is pressed, so nothing was sent. Release Ctrl, or press and release it once if no one is holding it, and try again." Several keys are named once in Ctrl/Alt/Shift/Win order, joined with ", " and a final " and ", e.g. "Ctrl, Alt and Shift are pressed, so nothing was sent. Release them, or press and release each once if no one is holding them, and try again." After earlier text landed, "nothing was sent" becomes "the rest was not sent" and the character count is appended, e.g. "Shift is pressed, so the rest was not sent. Release Shift, or press and release it once if no one is holding it, and try again. Typing stopped after 5 of 11 characters." Before any text lands, the suffix is "Typing stopped after 0 of M characters." - Pointer: actions that press a button or turn the wheel (
click,drag,scroll) take the same snapshot before posting anything, since a held modifier would make them a Ctrl+click, a Shift+click that extends the selection, an Alt+click, or a Ctrl+wheel zoom. A refusal sends nothing, not even a drag's button press, and uses the "nothing was sent" wording with no character count, e.g. "Ctrl is pressed, so nothing was sent. Release Ctrl, or press and release it once if no one is holding it, and try again." Pointer posts press no modifiers of their own. A plainmovepresses nothing, so it is not checked. - The guard also refuses when the agent's own combo needs the modifier the user is resting on (a finger on Shift while it sends
shift+tab); this is conservative and intended.
- Keyboard: before each keyboard post (text chunk, Return, or key), read both sides of Ctrl, Alt, Shift and Win with
- Windows held-modifier guard: a snapshot of both sides of Ctrl, Alt, Shift and Win (
S24.5 Permissions: the app reports and requests Accessibility and Screen Recording (
computer_permissions,computer_request_permission {kind}). The Connectors screen shows a built-in "Computer" entry with both statuses, Grant buttons, Check again, the note that debug builds lose the grants on every rebuild (macOS ties them to the code signature), and a note when the current model does not accept images (ConnectorInfo.noImages, from the model'sinputin the engine'sget_stateandset_modelanswers).S24.6 Visible state: the app emits
computer://state {active, endsAt?, reason?}(computer_statusgives the current one). Between calls, the rose shows the "in control" state (dot-in_control, moodcontrol: accent rim, steady traveling light) and the panel shows "Controlling your Mac · mm:ss left" with Stop (computer_stop). During a screenshot or action call (including an entire batch and its final screenshot), the Dot and panel are temporarily hidden and the top edge of the controlled display glows in the rose's neon with a light traveling along it, without text or logo. The click-through glow must be ready and hiding confirmed before capture or input; failed preparation sends no input. Completion and normal error/Stop paths restore prior visibility without changing saved preferences or taking focus. The tray's "Stop computer control" and the panic shortcut remain independent of the hidden panel; shortcut registration and full-screen tray availability must be verified on the target Mac.S24.7 Wiring: the app registers its helper itself, over the app channel, right after it spawns the daemon (
computer_register {url, token}; the daemon accepts onlyhttp://127.0.0.1:<port>/mcpand a header-safe key). A window cannot register, repoint, or remove it (L61 closed): the panel only callscomputer_endpointto know whether a helper exists. The daemon keeps the endpoint in memory, never inconnectors.json, and renderscomputer: {url, headers: {Authorization: "Bearer <key>"}, exposure: "direct"}intomcp.json, then restarts the engine when idle. The guard's policy lists it underbuiltin, so its tools run without in-engine approval cards. It is removed oncomputer_unregisterfrom the app or when the app's channel closes; windows coming and going do not touch it. A daemon without a channel (pnpm dev) gets no helper; the app never uses one (§9, Daemon lifecycle). The key is never logged or sent to a window:connectorslists only a built-in "Computer" entry (builtin: true) that the connector messages cannot change or remove, no saved or imported connector can take the namecomputer, and the import scan never offers the helper.S24.8 Speed:
batch {steps: [{tool, ...args}], intent?}runs 1 to 20 steps ofclick,move,drag,scroll,type,key,open_app, orwaitin one call and returns one screenshot. Each step takes the single tool's path (session and epoch, blocklist, risky confirmation, N1/N2 typing rules, coordinates mapped with the screenshot taken before the batch) and counts as one action for the rate limit; a full window delays the step instead of refusing it. Steps are 100 ms apart (1.5 s afteropen_app) so each step's guards read the screen the previous one left. The batch'sintentapplies to every step on top of the step's own. The first refused, declined, or failed step stops the batch; the error says which steps ran and comes with a fresh screenshot while the session lasts (none after Stop or panic). Malformed batches (empty, over 20, a nestedbatch,screenshot,list_apps, unknown tools, invalid arguments) run nothing. Actions settle 150 ms before their screenshot (open_app1.5 s); screenshots are JPEG quality 65; debug builds optimizeimage,zune-*, and this crate (opt-level 1, because the generic encoder is compiled here).S24.9 Yolo mode: in memory only, off at launch.
computer_set_yolo {enabled}and the tray item "Yolo mode" switch it; turning it on asks a native confirmation ("Turn on yolo mode? Gentle Dot will send, pay, delete, and submit without asking you first, for up to 1 hour. Stop and ⌥⇧Esc still work.", Turn On / Cancel). While on, only the risky-action confirmation is skipped; the grant, blocklist, rate limit, Stop, and panic are unchanged, and Stop or panic end the session, not yolo mode. It turns itself off after 1 hour.computer://stateandcomputer_statusaddyoloandyoloEndsAt?; every switch reports the resulting state, so a declined confirmation flips the UI switch back. Connectors → Computer shows a "Yolo mode" switch with a note that names the panic shortcut only whencomputer_permissionsreportspanicShortcut: true(registered at launch); otherwise, and until the app answers, it says only that Stop still works, as the dialog does. The banner shows "Yolo", and the rose carries a yellow mark (dot-yolo).S28 The pink glow where the agent acts:
- What it shows: a pulse on a click, a trail along a drag (drawn on the display where the drag starts), short markers for moves and scrolls, and an outline around the focused element after
typeandkey, when that element reports a frame (AXPosition,AXSize, read right after the keys); without one, nothing shows. The glow uses the accent#f095c8. It fades about 1.5 s after the last action (1.2 s lit, then a 300 ms fade) and clears at once when the session ends (Stop, panic, timeout). With "Reduce motion" it stays still: no pulse and no trail, only the drag's end. - Where the marks come from: once an action's input is posted,
performhands aMark(global points and a kind) to the helper's glow sink. Each batch step that runs gets its own mark. A refused, declined, stopped, or failed action or step reports nothing.open_app,wait,screenshot, andlist_appsreport nothing either. The sink only queues the mark on a channel, so no check, order, timing, or result changes; a rig test runs the same calls with and without the sink and compares them. - The overlay: a Tauri window
glow(index.html?surface=glow, titleGentle Dot Glow). It is transparent, undecorated, not focusable, out of the taskbar, and ignores cursor events. Its NSWindow sits at level 102, above menus, with collection behaviorcanJoinAllSpaces | stationary | ignoresCycle | fullScreenAuxiliary. It is ordered in withorderFrontRegardlesswhen a session starts, so it never becomes key or activates the app, and ordered out when the session ends. A thread of its own receives the marks and drops any that arrive after the session ended. That thread looks up the display (CGDisplayBounds), moves the overlay over the whole display, and emitscomputer://glowto that window only. The UI also ignores marks that come after acomputer://statewithout a session. - Working edge: a separate non-fading layer lights a thin neon line along the top edge of the controlled display, with a light traveling along it like the light on the rose's strokes, during a prepared tool call, not for the entire 30-minute authorization. No text or logo. With "Reduce motion" the edge stays lit and the traveling light is left out. The overlay covers the controlled display before a call starts, even before its first action mark. An internal
computer://working {active, operationId}event targets only the glow; a matching rendered-readiness acknowledgement (computer_working_ready, granted only to the glow window) is required before the interactive windows are temporarily hidden. Stale acknowledgements or queued preparation cannot hide windows after cancellation. The working edge clears when the call or session ends. - Guards and screenshots: the overlay is a Gentle Dot window covering the display, so pointer-owner resolution skips it by its window number (
kCGWindowNumber) and nothing else. The panel and the Dot still resolve to Gentle Dot and are refused. When the system-wide Accessibility hit test lands on the overlay while another app owns the window under the point, the risk check hit-tests that app's own element instead (AXUIElementCreateApplication). Screenshots leave the overlay out with every other window of our process (ScreenCaptureKitexcludingWindows). The overlay is on screen for the whole session, so it is in the capture's window list before it draws anything.
- What it shows: a pulse on a click, a trail along a drag (drawn on the display where the drag starts), short markers for moves and scrolls, and an outline around the focused element after
S24.11 Windows: the helper uses the same session and guards, with Windows-specific input, screenshots, app discovery and UI Automation.
- The panic shortcut is Alt+Shift+Esc; the panel says "Controlling your PC", and Connectors shows no macOS permission rows.
- Screenshots require Windows 10 version 2004 (build 19041) or newer for
WDA_EXCLUDEFROMCAPTURE. Each screenshot leaves out every visible Gentle Dot window and, right after it is taken, lets the ones it excluded show again, so the user's own screenshots still show the Dot and the panel; windows that are always left out (the glow, the approval dialogs) stay out. A dialog that cannot be left out holds screenshots off while it is open. On an older buildcomputer_permissionsanswersscreenshotsSupported: falsewithscreenshotsUnsupported: "tooOld"; a build that cannot be read gets no screenshots either, withscreenshotsUnsupported: "unknownVersion", so the helper's error and the Connectors note say that Gentle Dot cannot tell the Windows version instead of calling it too old.screenshotsUnsupportedis omitted when screenshots are supported (macOS before 14 sends"tooOld"), and afalsewithout it reads as too old. - Keyboard input to an elevated app is refused: "{app} runs as administrator, so Gentle Dot cannot send it keys."
open_appresolves names through Start menu shortcuts and App Paths, not PATH; it refuses unsafe targets and checks the resolved executable against the blocklist.- UI Automation failures are fail-closed: if any element in an ancestor chain is unreadable, the entire chain is unreadable and asks for confirmation. A default-button scan cut short is also unreadable.
Why enforcement lives in the app: everything inside the engine, and the daemon's WebSocket, is within the agent's reach (it has a shell, and with the daemon's access key it could answer its own approval cards, L49). The session grant, panic stop, blocklist, rate limit, and risky-action confirmations therefore run in the helper, behind native dialogs the agent cannot answer, and the in-engine guard adds nothing for these tools. macOS also attributes Accessibility and Screen Recording to the app that holds them, Gentle Dot.app. The key in mcp.json only reaches the helper, which still asks the user before anything happens.
Voice (S30)
The user can talk to the assistant: a mic button in the composer, and spoken replies.
- Where speech becomes text: "Sign in with ChatGPT" cannot transcribe (L88), so voice uses an OpenAI API key when one is connected, and the desktop app's own recognizer otherwise. On the desktop the key is preferred when present: the panel records with
MediaRecorderand sends the audio to the daemon. Without a key it uses the Tauri commandsvoice_status,voice_start {locale?},voice_stop→{text}, andvoice_cancel, plus the eventsvoice://partial {text},voice://level {level}, andvoice://error {message}(§9). The web only uses the daemon, and shows the mic only when a key is connected and the page is a secure context (HTTPS or localhost). - Protocol:
voice_transcribe {requestId, mime, data}(base64, at mostMAX_VOICE_AUDIO= 960,000 characters, so the frame stays under the 1 MiB WebSocket limit) →voice_transcript {requestId, text}.voice_speak {requestId, text ≤ 4096}→voice_speech {requestId, mime, data}. A failure answersvoice_unavailable {requestId, reason}, with the reason in plain words.readyandauth_providerscarryvoice: {transcribe, speak}, so voice turns on or off as soon as Accounts changes. - Daemon (
packages/daemon/src/voice.ts): it reads the key through Pi's ModelRuntime (AuthRuntime.openAIApiKey). It returns a key only when the storedopenaicredential is an API key (checkAuthtypeapi_key), never the ChatGPT token. Transcription isPOST /v1/audio/transcriptions(multipart,gpt-4o-mini-transcribe). Speech isPOST /v1/audio/speech(gpt-4o-mini-tts, voicealloy, mp3). The key goes only into theAuthorizationheader. Logs carry only the status code, and replies never carry the key or OpenAI's error bodies. 401, 403, 429, other statuses, and network failures each map to their own reason. - Mic button (S30.4): tap to start and tap to send. While recording, the composer shows the elapsed time, a level meter, the live partial text (desktop recognizer), and ✕. Esc also cancels, and it is handled before the panel's own Esc. Recordings stop on their own at 60 s. The transcript is sent as the user's message and stays in the chat. When voice cannot work, the button is disabled and its tooltip says why (permission, insecure page, no recorder); on the web without a key it is hidden.
- Spoken replies (S30.3): only the reply to a spoken message is read aloud, once the assistant is idle and the reply did not end in an error or Stop. Markdown, code, and links are stripped first. With
voice.speakthe daemon synthesizes it and the UI plays the mp3. OtherwisespeechSynthesisreads it with a voice in the reply's language (a Spanish/English guess, then the browser language). A speaker toggle in the header mutes it, and the choice is kept inlocalStorage(gentle-dot-voice-muted). Starting to talk, or Stop (shown while speaking), cuts the speech.
Attachments (S31)
The user can send files to the assistant (never the other way, L91).
- Upload (
packages/daemon/src/uploads.ts):POST /upload, one file per request, the raw bytes as the body, the name URI-encoded inX-File-Name, andX-Upload-Idto add a file to the folder of the message's first file. The access key goes only inAuthorization: Bearer; a key in the address is ignored. A foreignOriginis refused as on the WebSocket, and allowed origins (the desktop app'stauri://localhost) get a CORS preflight answer. The answer is{uploadId, name, size, mime, path}, withpathrelative to the workspace. - Storage and limits (S31.3):
<workspace>/uploads/<uploadId>/<name>, folders 0700 and files 0600, written withwx. Names keep only the last path segment, without control or invisible characters, leading dots, or reserved names (filewhen nothing is left), and duplicates becomename (2).ext. The daemon enforces 25 MB per file and 10 files / 50 MB per message (ATTACHMENT_LIMITS) while the bytes arrive: a declaredContent-Lengthover the limit is refused before reading, and a refused or broken upload removes its partial file. Nothing is opened or run. The type comes from the first bytes (PNG, JPEG, GIF, WebP, PDF), never from the name. On a later upload, unsent files from batches at least an hour old are removed. Cleanup deletes only unsent files and removes their folder only if empty; files already sent from the same batch stay available. - Sending:
sendtakesattachments: {uploadId, name}[](1-10; the text may then be empty). Each upload is sent once; an unknown or used one answerserror attachment_not_found, and nothing reaches the engine. The bridge appends an<attachments>block to the prompt, with one JSON line per file (name, size, type, absolute path). Images up to 3.75 MB (about 5 MB in base64) go to the engine asimagesonly when the current model accepts them (supervisor.modelImages); otherwise the line says the model cannot see images. - Display: the block is stored with the message in the session file, so
user_message,history, the queue, and titles show the user's own text, andattachments: {name, size, mime}[]become chips. A plainsendis unchanged. - UI: a paper-clip button, drag and drop onto the chat, and pasted images add chips (name, size, ✕). The app checks the limits first and explains a refusal on the chip. Files upload on send with
XMLHttpRequest, for progress, and an upload error stays on its chip with the message kept. In the desktop panel, HTML5 drops need the window's native drag-and-drop handler off (disable_drag_drop_handler()on the panel'sWebviewWindowBuilder).
Model picker (S32)
The user changes the main assistant's model from the chat, in the panel and the web UI.
- Messages:
models_listanswersmodels {current?, next?, groups, profiles, activeProfile?}.groupsare the engine'sget_available_models(only accounts with a working credential), grouped by provider and named like the Accounts screen; each model carries only{provider, id, name, images, thinkingLevels?}(toModelChoices, never endpoints, headers, keys, or costs).thinkingLevelsmirrors the engine'sgetSupportedThinkingLevels: none for a model that does not think, andxhigh/maxonly when the model maps them.profilesare the saved profiles with their main-assistant route, as quick picks that sendprofile_apply. model_set {provider, id, thinking?}: a model outside the available list answerserror model_unavailable, a level the model does not supporterror thinking_unavailable, and nothing changes. Otherwise the daemon saves it as the default (settings.jsondefaultProvider/defaultModel, anddefaultThinkingLevelonly when given, under the engine's settings lock), because the engine's RPCset_modeldoes not persist, then switches live through the sameLiveModelSwitchas profile apply. During a reply the switch waits for the run to settle (never an abort), andmodels.nextsays so. Every window gets the newmodels; after the switch the connectors list is sent again so the Computer image note followssupervisor.modelImages, as do images on the next attachment. Applying a profile also refreshesmodels.- UI (
ModelPicker.tsx): a pill chip above the composer with the model name; it opens a popover with a search box (aria-activedescendant), a listbox grouped by account plus a Profiles group, and a Thinking select only when the current model thinks (a new model keeps the level when it supports it). Arrow keys move, Enter picks, Esc closes and returns focus to the chip; the popover callspreventDefault, so App.tsx's Esc (leave full screen, then hide the panel) does not run. The picker's errors show inline in the popover, not as notices.
5. White-label layer
- Identity:
--append-system-promptwithidentity.md: the assistant is "Gentle Dot", a personal assistant; it must not mention Gentle Shell, Pi, el Gentleman, ODD, or Engram by name, and describes them as "my workflow" and "my memory" when needed. It keeps every behavior. - Event sanitizer (
packages/daemon/src/white-label.ts, unit-tested): rewrites internal names in toasts, ask titles, messages, and options (answers are mapped back to the agent's original option strings), final assistant text, and history. Informationalnotifyrecords are harness chatter and are hidden; warnings and errors are shown.setStatus,setWidget,setTitle, and terminal-only requests are dropped. Tool names map to activity kinds and neutral titles (for examplemem_search->memory"Checking my notes"). Streamed deltas are not rewritten; the UI replaces them with the final text. - Commands:
gentle:*slash commands are never exposed, and a message starting with/gentle:is refused withunsupported; the UI has no command palette in this version. - Errors: provider or process errors become neutral messages; raw details go to the daemon log only.
6. User experience
The Dot (collapsed)
- Our neon rose inside a black circle (S9, L24): a 66 pt disc in a 72 pt transparent window. It is always on top, draggable, snaps to the nearest screen edge, and its position is persisted. Design sheet:
docs/brand/rose-design.html. - The rose is inline SVG built from the 178 strokes traced from the logo (
docs/brand/rose-lines.svg→packages/ui/src/rose/strokes.ts, generated bydocs/brand/tools/build-rose-strokes.mjs). The strokes carry the glow (#FF2D7Aneon,#FFD6E8light core), and a light layer on the 60 longest strokes travels along them. - The state is shown by motion and glow:
idle: the outline breathes a soft glow; sparkles twinklethinking: one slow light runs along each strokeworking: fast lights race through petals, leaves, and stemneeds_you: the rose pulses brighter, with an amber!badgestartingandrestarting: dim grey rose with one faint light tracingerror(unavailable): dim and still
- Only
stroke-dashoffset,opacity, andfilteranimate. With "Reduce motion", nothing moves: the light layer is hidden and the glow stays (stronger while working or waiting for the user). - Click, the global shortcut
⌥ Space, or the menu bar item expands it.
The panel (expanded)
- 420 × 640 px, rounded 20 px, translucent (macOS vibrancy), anchored to the Dot.
- Header (one continuous chat): the rose glyph and "Gentle Dot", then Accounts, Profiles, Connectors (a plug; also
/connectors), Settings (a gear), Hide the rose (an eye) and Full screen (desktop panel only), and Hide as 18 px stroke icons with tooltips. The web UI has no Settings for now. Withfeatures.conversationson, the conversation title, the conversations list, and New conversation return. - "Show earlier" at the top of the chat loads the previous page; a subtle "Earlier messages" divider marks where the chat's earlier session ends.
- Body: message list with streaming Markdown and code blocks; activity rows are collapsed one-liners grouped under the assistant turn ("Read 3 files · Ran tests").
- Ask cards: when the agent needs the user, an inline card with the question and buttons (select and confirm) or a text field (input and editor). The Dot turns amber until the user answers.
- Composer: multiline, Enter sends, Shift+Enter adds a new line. While the agent works, the composer offers "Stop", and sending a message steers the current run.
Esccollapses back to the Dot; the conversation keeps running. In full screen,Escfirst restores the panel's size (see §9, Hiding the rose and full screen).
Menu bar
- Template icon: the hand-drawn rose glyph (
docs/brand/rose-glyph.svg), with one variant per state: ready, working (dashed outer petals; also used while thinking), needs you (a filled badge dot), and unavailable (dimmed; starting, restarting, and error). - Menu: Open (
⌥ Space), Open in browser, Restart assistant, Launch at login (toggle), Quit. New conversation appears after Open only with the conversations list on (GENTLE_DOT_CONVERSATIONS=1).
Web
- The same UI at
http://127.0.0.1:4317, full-height layout without the orb. The token is passed once through/#token=…and stored insessionStorage.
Visual system
- The panel and the web view follow gentlemanprogramming.com (S15, measured from the live site, L30). Dark only; there is no light theme.
- Tokens (
packages/ui/src/styles.css):--bg#1a1218, translucent header--bg-glassrgba(26,18,24,0.82)with a 12 px blur and a bottom border--surface#20161e,--surface-2#241822,--line#342230--text#f6eff3,--muted#a78e9b--accent#f095c8; the primary button has0 10px 30px rgba(240,149,200,.3)and#1a1218text (8.60:1; white is 2.13:1)- notes: green
#b4e7c7, red#ff718f, yellow#e0c27a - radii 8 / 12 / 16 px, pills 999 px
- Type: Inter for text, 14/20 body; an uppercase monospace eyebrow (Iosevka Term / JetBrains Mono, 12 px, letter-spacing .12em, accent color); headings in 800 weight with a light-to-pink gradient.
- The rose Dot keeps its own look (S9): neon
#FF2D7Astrokes in a black circle, with the amber#F5A524badge. - Motion: 180 ms ease-out for expand and collapse; the Dot animations respect "Reduce motion".
7. Recovery
- Pi sessions persist under
~/.gentle-dot/sessions, and the daemon reopens the last active one after any restart (state.jsonsessionFile). - Rotation (S22): Pi's auto-compaction keeps the model context bounded, but the session file keeps every entry and grows forever, and detail fades with each summary. After a run settles, when the agent is idle (no run, no compaction, no open ask, no message on its way), the daemon checks the open session file. Past 20 MB (
GENTLE_DOT_ROTATE_BYTES) or 10 compaction entries (GENTLE_DOT_ROTATE_COMPACTIONS), it rotates:- It writes a new session file next to the old one, in Pi's own format (a v3
sessionheader withparentSession, then onecustom_messagewithcustomTypegentle-dot.handoffanddisplay: false). The handoff text is the latest compactionsummaryfrom the old file, with no extra model call, or, before any compaction, the previous handoff plus the last 12 messages. - It sends
switch_sessionto that file and checks that Pi opened it (get_statereports it) and thatget_messagesholds the handoff. Pi sends a custom message to the model as user-role context, but it is never a user message, so the chat never shows it. - If Pi did not load it (for example, its session format changed), the daemon deletes nothing, logs it, and sends
new_sessionwithparentSessioninstead: a fresh session without the handoff, so the user always keeps a working chat. If the handoff file cannot be written, the chat stays in the current session. state.jsonchainsmaps the new file to the earlier ones (oldest first), so history pages read through them, and every window gets a freshhistorywith the earlier messages marked.
- It writes a new session file next to the old one, in Pi's own format (a v3
- Rotation never happens while the assistant is busy or an ask is open, and a failure is logged and leaves the current session working.
- After a crash, the turn that was in flight is lost. The conversation history remains, and the UI shows "I was interrupted. Continue?" with a Continue button that sends "Continue where you left off."
- The user's global Engram (project
gentle-dot) keeps decisions and progress across conversations; the Gentle workflow already consults it when resuming. - Pi Durable is reconsidered only for unattended or scheduled work.
8. Security (local)
- The daemon binds
127.0.0.1only. A random 256-bit token is stored in~/.gentle-dot/token(mode 0600). The desktop app reads it; the browser receives it once by URL fragment. - WebSocket upgrades check
Originagainst an allowlist (http://127.0.0.1:4317,tauri://localhost). - The VPS guide requires HTTPS, a reverse proxy with authentication, and a dedicated Docker container with no access to personal machines.
- Server mode (S25.8,
GENTLE_DOT_VPS=1, set only by the container image;daemon/src/vps.ts): the daemon runs as root in the container with onlySETUID,SETGID,CHOWN,FOWNER,DAC_OVERRIDE, andKILLandno-new-privileges, and refuses server mode otherwise. It starts the engine asdot(spawnuid/gid; its tools, shell, subagents, and memory server inherit it) and its stdio connector servers asdotmcpthroughsetpriv(no groups, no capabilities), with their own home and working folder in<data>/connector-home, so they cannot see the engine's workspace. The data folder is the daemon's (0711); the token,connectors.json, the secrets, and the PIN hash are the daemon's (0600); the engine's folders (agent,home,workspace,sessions,gentle-ai) aredot's. The daemon never acts on them as root (B1): Pi's ModelRuntime (sign-in, providers, the voice key), which runs a!commandvalue and expands$NAME, lives in a helper started asdot(cli.ts --auth-helper,auth-helper.ts, Node IPC, plain data back); every other read, write, mkdir, chmod, or removal there (profiles andsettings.json,mcp.jsonand the subagents' guard, the workspace's.piand.engram, history and rotation, uploads and the images read for a prompt, the engine's oldmcp-auth.json) runs in a synchronousengineAccessbracket (engine-access.ts:setgroups,setegid,seteuidtodot, then back to root, or the daemon stops), so the kernel resolves every link withdot's rights and what is made there isdot's. The bracket never starts a process, and the daemon does no asynchronous file work (the ids change on every thread; a test checks the imports, and uploads open their file in the bracket and stream to the open descriptor); the daemon's own files go throughwritePrivateFile(exclusive temporary file, owner checked, refused inside a bracket). Files an older version left as root there are handed over once at start withchown -R -P --from=0:0. The root-only checks run in the image (packages/daemon/test/vps-root.test.tswithGENTLE_DOT_TEST_ENGINE_USER=dot GENTLE_DOT_TEST_CONNECTOR_USER=dotmcp). Without the app, connector secrets live in<data>/secrets.enc.json, AES-256-GCM per record (random nonce, the id as additional data) underGENTLE_DOT_SECRETS_KEY, which only the daemon's environment holds (removed fromprocess.envat start and from every child's environment); without it, connectors that need a secret fail closed and say why; with it, secrets older files still hold move there once (migrate). Privileged actions from the web page need a PIN instead of the app:pin_set(once; a salted scrypt hash in<data>/web-pin.json),pin_command {pin, command}for a connector change (the PIN is its confirmation), andpin_approve {requestId, pin}for an approval shown as an ask withmethod: "pin"and the full preview (ui_response confirmed:falsedeclines without it); 5 wrong tries in a row lock it for 15 minutes, persisted. With the app's channel nothing changes: the WebSocket getsapp_required, also for the PIN messages, and secrets stay in the app's store. - The assistant's engine runs as the user with a shell. Its file tools cannot read the token, sign-ins, or connector files, and the connector state lives in the daemon's memory (§4, Connectors), but shell checks are best effort: a determined command can still read what the user's account can read. Stage 2 (S25) moves connector tokens and enforcement into the daemon: the MCP proxy (S25.4, done) keeps every token, real address, and server environment out of the engine's
mcp.json, and enforces mode, hidden tools, and approvals in the daemon. Connector changes and approvals come only from the desktop app that launched the daemon, over its private channel, and are answered in native dialogs (§4, App channel); the WebSocket's access key no longer reaches them. Connector secrets (tokens, client secrets, imported headers, sign-ins) are in Keychain items the signed app creates and reach the daemon only in memory over that channel (S25.5, §4 Secrets); without the app, connectors that need one fail closed. What the Keychain cannot check:security-frameworkexposes no item access list, so the app cannot tell an item it created from one a same-user process planted (before the firstput, or after deleting the app's); the daemon only reads ids it recorded, and everyputreplaces the item.connectors.jsonis signed with a key in the Keychain, and a file changed while Gentle Dot was closed is set aside at the next start with the app (S25.6, §4 Integrity); without the app it is loaded unverified. On Linux the app keeps connector secrets in the Secret Service (GNOME Keyring or KWallet), encrypted at rest; the Secret Service has no per-caller access list, so any same-user process, the agent's shell included, can read the items while the keyring is unlocked (S25.7, documented limit). The app channel, the MCP proxy, and native approvals work as on macOS: no child of the daemon holds the channel (checked in containers byscripts/package/linux-cargo-check.mjsand the package smoke). Without a Secret Service at start, the connectors' integrity key cannot be read, so connectors that need a secret stay locked until Gentle Dot restarts (daemon.lognames the missing keyring; the assistant is told to restart); if the keyring goes away later, the assistant anddaemon.log(connector <id> cannot get its secrets: …) name it. Only the Linux keyring message is passed on this way; other store refusals keep their earlier wording. Still open: the proxy key is in the engine'smcp.json, so the agent's shell could call the proxy directly; that reaches only what the proxy allows, and every sending action still needs the user's approval.
9. Desktop shell contract (Tauri 2 <-> UI)
The desktop app bundles the built UI (packages/ui/dist/app) as its frontend, so its origin is tauri://localhost, which the daemon allows. It has no dock icon (macOS accessory activation policy). It also runs on Linux (S13); the differences are under "Linux" below.
Windows
| Label | Size | URL | Properties |
|---|---|---|---|
dot |
72 × 72 pt (the rose in a 66 pt black disc) | index.html?surface=dot |
title Gentle Dot; transparent outside the disc, no decorations, always on top, not resizable, skip taskbar, visible on all workspaces, shadow off; placed in logical points |
panel |
420 × 640 | index.html?surface=panel (Linux: &effects=none) |
title Gentle Dot Panel; transparent with macOS vibrancy (HudWindow), no decorations, always on top, hidden at start, skip taskbar. With effects=none the UI sets data-effects="none" on <html> and paints the panel opaque (--bg, no backdrop blur). |
glow (macOS) |
the display where the agent acts | index.html?surface=glow |
title Gentle Dot Glow; the computer-control glow overlay (S28, §4): transparent, no decorations, not focusable, ignores cursor events, above menus, on every Space, shown only during a control session. Its own capability allows only core:event:allow-listen and allow-unlisten; it never connects to the daemon. |
When the panel opens, it is placed next to the Dot on the side with more room, and it stays inside the monitor.
Rust commands the UI calls (@tauri-apps/api/core invoke)
| Command | Arguments | Result |
|---|---|---|
connection_info |
— | { "url": "ws://127.0.0.1:<port>/ws", "token": "…", "webUrl": "http://127.0.0.1:<port>/#token=…" }, read from ~/.gentle-dot/config.json and ~/.gentle-dot/token |
toggle_panel |
— | shows and focuses the panel next to the Dot, or hides it |
hide_panel |
— | hides the panel |
set_dot_state |
{ "state": AgentState } |
updates the tray tooltip and swaps the tray glyph for the state |
rose_hidden |
— | true when the user hid the rose |
set_rose_hidden |
{ "hidden": boolean } |
hides or shows the Dot window, saves the choice, emits dot://rose; returns the resulting state |
set_panel_fullscreen |
{ "on": boolean } |
fills the work area of the panel's display, or restores the frame before; returns the resulting state |
shortcut_get (panel only) |
— | { "shortcut": "Alt+Space", "default": "Alt+Space" }: the shortcut that toggles the panel now, in its normal spelling |
shortcut_set (panel only) |
{ "shortcut": string } |
{ "shortcut": string } as saved, or a rejection with a reason for the user (see "Menu bar and shortcut") |
connector_command (panel only) |
{ "clientId": string, "message": ClientMessage } |
sends a connector change (S25.2) to the daemon over the app channel on behalf of the window clientId; resolves once the daemon handled it (after any native confirmation), or rejects with a reason (no channel: the app did not start this daemon) |
The Dot drags with getCurrentWindow().startDragging() (permission core:window:allow-start-dragging). After a drag ends (no move events for 300 ms), Rust snaps the Dot, by its real window size, to the nearest monitor edge with a 12 px margin and saves the position in ~/.gentle-dot/desktop.json; the next launch restores it, or defaults to the right edge, vertically centered.
Events Rust emits to the UI (@tauri-apps/api/event listen)
| Event | Payload | Meaning |
|---|---|---|
dot://new-conversation |
— | the tray item "New conversation" was chosen; with the conversations list on, the panel starts a new conversation and opens; in the single chat (default) the UI ignores it |
dot://panel-shown |
— | the panel became visible; the UI focuses the composer |
dot://rose |
{ "hidden": boolean } |
the rose was hidden or shown (panel header or tray) |
computer://glow (to glow only) |
{ "kind": "click" | "move" | "scroll" | "drag" | "key", "x", "y", "toX"?, "toY"?, "width"?, "height"? } in points from the overlay's top-left corner |
the agent just acted there (S28); drag adds the end point, key the focused element's size |
Menu bar and shortcut
Tray menu: Open (⌥ Space), New conversation (only with GENTLE_DOT_CONVERSATIONS=1, read like the daemon reads it), Open in browser, Hide the rose / Show the rose, Restart assistant, Launch at login (check item), Quit. The global shortcut Alt+Space (configurable as shortcut in config.json, or in the panel's Settings) toggles the panel.
Settings (S33): a gear in the desktop panel header opens a Settings screen styled like Accounts. Its "Keyboard shortcut" section shows the shortcut (⌘ ⌥ ⌃ ⇧ on macOS, names elsewhere); "Change" records the next key combination from the physical key (code), Esc alone cancels recording without hiding the panel (the recorder listens in the capture phase and marks the keys it takes as handled), and "Reset to default" sets Alt+Space. shortcut_set applies it live, with no restart (src/shortcut.rs):
- Rules: the accelerator must parse; it needs a modifier unless it is F1–F24; Esc alone and the panic shortcut ⌥⇧Esc (any spelling) are refused. The saved spelling is normal: modifiers as
Ctrl+Alt+Shift+Super, then the key (K,1,Space,F5). - Apply: the new shortcut is bound first; if the system or another app holds it, the old one stays and the reason is "That shortcut is taken by the system or another app." Then
shortcutis saved inconfig.json(read, change that key only, write a 0600 temporary file and rename it; a file that cannot be read or is not a JSON object is reported, never replaced); if saving fails, the new binding is released and the old one stays. Last, the old shortcut is released and the tray's Open item shows the new one. - Native Wayland: the desktop owns shortcuts, so
shortcut_setexplains how to bindgentle-dot --toggleinstead. Launch at login usestauri-plugin-autostart; Open in browser usestauri-plugin-openerwithwebUrl.
Hiding the rose and full screen (S26)
- Hide the rose: the tray item "Hide the rose" (relabeled "Show the rose" while hidden) and an eye button in the panel header call
set_rose_hidden. The choice is saved asrose_hiddenin~/.gentle-dot/desktop.jsonnext todot_points; files without the key load as shown. A hidden rose is still placed at launch, only not shown. The shortcut and the tray's Open never need the Dot: with the rose hidden, the panel opens at the spot where it was last hidden when that is on the display under the pointer, or else at the right edge of that display, vertically centered. Computer control stays visible in the panel banner (and the tray's Yolo mode check) while the rose is hidden. - Full screen: a header button and ⌘⇧F (Ctrl+Shift+F off macOS) while the panel has focus call
set_panel_fullscreen. The panel fills the work area of its display (the menu bar and the Dock stay visible) and stays an accessory window, not a separate macOS fullscreen Space. The app remembers the frame before and restores it, kept on a display that still exists. While full screen, the panel is not moved when it opens or the Dot snaps, and the conversation, notes, and composer use a centered column of--reading-width(780 px, the web page's column). The web page has no button; it already fills the browser. Escin the panel, in order: anEscthat something inside the panel already handled (preventDefault) is left alone; in full screen it restores the panel; otherwise it hides the panel.
Second launch and --toggle
The app is single-instance (tauri-plugin-single-instance; D-Bus on Linux). A second launch hands its arguments to the running app and exits: --toggle toggles the panel, anything else shows it. A first launch with --toggle opens the panel once the app is up. Desktop shortcuts bind gentle-dot --toggle where the app cannot register its own (Wayland).
Linux
src/platform.rs holds the decisions, as pure functions of the environment:
- GNOME on Wayland (Debian, Ubuntu): before GTK starts, the app sets
GDK_BACKEND=x11when the session is Wayland, the desktop is not Hyprland (HYPRLAND_INSTANCE_SIGNATURE, orHyprlandinXDG_CURRENT_DESKTOP),DISPLAYis set (XWayland), andGDK_BACKENDis unset. Under XWayland the app places, raises, and snaps its windows as on macOS. TheAlt+Spacegrab only sees keys while an X11 window has focus, so the documented shortcut is a GNOME custom shortcut runninggentle-dot --toggle. - Native Wayland (Hyprland on Omarchy, or a user-chosen
GDK_BACKEND=wayland): the compositor places windows, so the app skips restoring and snapping the Dot, skips placing the panel, and does not register the global shortcut. Hyprland window rules matched by title float and pin both windows and place them; abindrunsgentle-dot --toggle(scripts/linux/hyprland/, inhyprland.luaandhyprland.confforms). - Window sizes: GTK sizes a non-resizable window to its content (the Dot came out 200 × 200 in an X11 test), so on Linux the Dot is resizable with equal minimum and maximum sizes of 72 × 72. A panel that was never shown reports 0 × 0, so placement uses the fixed
PANEL_SIZE. - Tray: Linux trays do not tint template images, so
icons/tray/linux/holds 32 px glyphs in light gray over a dark outline; GNOME shows them through the AppIndicator extension. - Delivery is from source (
scripts/linux/setup-debian.sh,setup-arch.sh), becausebuild.rsrecords the build machine's paths. Tester checklist:docs/linux-testing.md.
Daemon lifecycle
On launch, the app checks GET /health. If the daemon does not answer, the app spawns it: <node> <repo>/packages/daemon/src/cli.ts, with the PATH captured at build time (apps launched from Finder get a minimal PATH, and the daemon needs gentle-shell). build.rs records the absolute node path, the daemon script path, and PATH; GENTLE_DOT_NODE and GENTLE_DOT_DAEMON_SCRIPT override them at runtime. A daemon spawned by the app gets the app channel on fd 3 (§4) and stops by itself when that channel closes, so it never outlives the app, even after a crash or a kill (S35.2, #22). Each spawn records <dataDir>/daemon.pid (0600: the pid and the process start time, from proc_pidinfo on macOS and /proc/<pid>/stat on Linux), written to a new file in the same folder and renamed over the old one, so it is never written through a symlink and never read half written; it is read only as a small regular file, opened without following a symlink or blocking on a FIFO, and a record naming the app itself, its parent, init, or pid 0 is ignored. The start time is checked again before each signal. Quit stops the daemon, closes the channel, and removes the file. The app never attaches to a daemon it did not launch, which would have no channel and keep connectors locked. When a daemon answers at launch: if the pid file names a process that is still the same one (same start time), the app stops it (SIGTERM, SIGKILL after 10 s), waits for the port, and starts its own; otherwise (pnpm dev, or a daemon left by an app older than this rule) it starts nothing and shows a dialog naming the way out: stop the other one (Ctrl+C where pnpm dev runs, or the process on the port), then Restart assistant. The panel then gets that message from connection_info instead of a connection. A pid file names a process the app may signal, so a same-user process that rewrites it could make the app stop that process at the next launch, only while a daemon answers on the port; that user can already do so directly. Restart assistant restarts the daemon this app spawned, and shows the same dialog when another one holds the port. The UI connects only after the daemon this app spawned answers /health. Each time a start leaves that daemon answering (at launch or after Restart assistant), the app sends dot://assistant-ready to its windows, and a Dot or panel that was refused or gave up asks connection_info again and connects without a reopen. That also covers a slow replacement: connection_info waits 20 s, while stopping an earlier app's daemon can take up to 17 s (10 s grace, 2 s after SIGKILL, 5 s for the port) before the new one is spawned and given its own 20 s.
10. Configuration
~/.gentle-dot/config.json, all optional:
{ "port": 4317, "workspace": "~/Documents", "shortcut": "Alt+Space", "launchAtLogin": false }
All keys are optional. workspace is the user's preferred working folder: the engine is told about it but always runs in <dataDir>/workspace. Changing the shortcut in Settings rewrites shortcut and keeps every other key.
Environment overrides: GENTLE_DOT_AGENT_HOME (default ~/.gentle-dot/agent), GENTLE_DOT_ENGRAM_DATA_DIR (default: the user's Engram data folder), GENTLE_DOT_ENGRAM (private for a memory of the assistant's own), GENTLE_DOT_ENGRAM_PORT (private memory only, default 7438), GENTLE_DOT_SUBAGENTS (off turns the engine's subagents off), GENTLE_DOT_PORT, GENTLE_DOT_HOST (default 127.0.0.1; 0.0.0.0 only inside a container), GENTLE_DOT_DATA_DIR, GENTLE_DOT_WORKSPACE, GENTLE_DOT_UI_DIR, GENTLE_DOT_AGENT_BIN, GENTLE_DOT_AGENT_ARGS (JSON array), GENTLE_DOT_ALLOWED_ORIGINS (JSON array), GENTLE_DOT_CONVERSATIONS (1 turns the conversations list on), GENTLE_DOT_ROTATE_BYTES (default 20 MB), GENTLE_DOT_ROTATE_COMPACTIONS (default 10), GENTLE_DOT_HISTORY_PAGE (default 100).