> ## Documentation Index > Fetch the complete documentation index at: https://docs.xynthis.com/llms.txt > Use this file to discover all available pages before exploring further. # The macOS app > The menu-bar resident client: chat, voice, workspace, brain surfaces, computer-use overlays, and licensing. The Xynthis app is the native macOS face of the brain. It lives in the menu bar, not the Dock: click the menu-bar icon to open the panel, close the window and it hides rather than quits, and the brain keeps running. The app spawns the bundled brain and daemon on launch and shuts them down cleanly on quit, so it is self-contained: install the DMG from [xynthis.com](https://xynthis.com) and you have the full stack. The app is purely a client. It never writes memory itself. Every memory or agent operation goes through the daemon on `:3939`, which forwards to the brain. That means everything you do in the app is visible to `xynthis recall` in the terminal, and vice versa. Requires macOS 26 or later. The current version is 1.0.89. ## First run A six-step onboarding wizard overlays the app until you complete it: Welcome, Permissions, Brain, License, LLM, Done. Permissions you skip just leave those tools hidden, and the LLM step (which gets a model configured so your first message has somewhere to go) can be deferred to Settings. The License step is the one hard gate: activate a key or sign in to continue. ## Chat and sessions The chat screen is the default view. The sidebar lists your past sessions, loaded from the daemon, with dots marking unread and still-streaming sessions; selecting one restores its full transcript, and `+` starts a new session. Sessions are shared with the CLI: a conversation started with `xynthis chat` shows up here. While the agent works, the timeline interleaves messages with live activity: tool calls, plan steps, and, during computer use, a cursor overlay showing where the agent is clicking on screen. The composer has a few shortcuts worth knowing: * **⌘F** opens a find bar that searches within the current transcript and highlights matches. * Typing **@** opens a popover for inserting file references; typing **/** does the same for commands. Arrow keys move the selection, Return inserts, Escape dismisses. * The **attach** button opens a file picker; the agent then ingests the chosen file into memory through the standard perception pipeline, so you can ask about it in this or any later session. ## Voice A microphone button gives push-to-talk input: transcription runs on-device first, with a whisper fallback through the daemon. When you speak a request, the reply is spoken back. For typed messages, a speaker toggle in the chat bar controls whether replies are read aloud; it is a single global setting, off by default, that persists across relaunches. Pick the voice in Settings. ## Model picker The chip in the chat bar shows the active model. Tap it to list every provider the daemon knows about; selecting one writes the config and restarts the daemon to apply it, so the switch takes effect immediately but interrupts an in-flight turn. Local providers that aren't running yet (an Ollama server, for example) show a start action instead: tap to launch them. ## Workspace The Workspace screen is a development surface with toggleable panels: a terminal running a real shell, a git diff view, a web preview, tasks, and the agent's current plan. Workspace has its own chat, isolated from the main chat session, so agent work here doesn't pollute your main conversation history. * **⌘K** opens a command palette that navigates screens, toggles panels, and surfaces repo-aware commands (build, test, run) detected from the open project. **⌘1** through **⌘7** toggle panels directly. * When a shell command in the terminal fails, the app sends the command and the tail of its output to the agent and shows a plain-language explanation of what went wrong. * A **model download panel** fetches recommended GGUF models from Hugging Face into Application Support for local use. * A **project memory panel** shows the brain's summary of the current project, so you can see what Xynthis already knows about the repo you are working in. ## Brain surfaces Several screens keep the brain's state visible: * **Home** is the landing overview: brain status, recent activity, and quick entry points. * **Focus Radar** is a live tactical overview composing connectivity, memory, corpus, model, lessons, activity, and permissions into one what-needs-attention surface. * The **BRAIN side panel** (right edge) shows the soul and emotion state, live perceptions as they arrive, the active provider, and ambient-observer status. * The **brain dock** at the bottom of the sidebar keeps compact vitals visible from any screen, with a scrolling perception ticker and an animated pulse line. ## Memory and the knowledge graph The Memory screen is a window into the brain: search recall directly, run semantic search, browse ingested corpora, and inspect stored facts. The knowledge-graph view renders the entities and relationships the brain has extracted as a force-directed interactive graph. A Lessons screen lists the failure-to-correction lessons the agent has accumulated and lets you clear them. ## When the agent acts on screen During computer use, borderless click-through overlays show you exactly what the agent is doing: a glowing ring and animated cursor flight at each click, plus a status badge. A mission panel lists the plan's steps live, and a compact HUD in the top-right tracks the single active step. Two features put you in the loop: * **Guide-Me mode.** Instead of acting, the agent highlights one on-screen target with a pulsing coach-mark and a narration banner, then waits for you to click it yourself. Controls let you skip a step or hand it back with "Do it for me". * **Tool approval.** When a tool call needs your sign-off, a floating panel asks you to approve or deny it, with a countdown to expiry. The decision syncs to the brain, and to your team's audit log if you are on a team license. ## Ambient observer An optional passive observer samples the frontmost app, window title, selection, and URL every 30 seconds and stores the result as ambient memory, so you can later ask "what was I working on Tuesday afternoon". It is **off by default**: start and stop it from Settings, which also shows its status and sample count. Password managers and similar apps are on a deny-list and never sampled, repeated identical samples are deduplicated, and it requires the Accessibility permission. ## Settings **API keys.** Settings → Models holds one row per provider with masked key entry. Keys are stored in the macOS Keychain, scoped to this device only and never synced to iCloud, not in a plaintext file. **Voice.** Pick the TTS voice used when replies are spoken aloud. **Ambient observer.** Start or stop background observation and see what it has sampled. **License.** Paste a license key to unlock Pro. Verification happens offline against a bundled public key, with a 30-day grace window when the machine can't reach the license server. When a license expires, the app soft-degrades to Free rather than wiping your key: your data stays, Pro features gate off, and a renewal banner links you to the dashboard. Signing in with your account can recover a key that is no longer on the machine. ## Permissions The app asks for macOS permissions only when a feature needs them, and never fires a system prompt on its own. The sidebar shows what's granted, and a Grant button takes you to the right System Settings pane. | Permission | Why | | ---------------- | -------------------------------------------------------------------------------------- | | Accessibility | Computer use and the ambient observer: the agent clicks, types, and reads window state | | Screen Recording | Computer use: the agent sees the screen to decide where to act | | Microphone | Push-to-talk voice input | | Full Disk Access | Reading files outside the standard sandbox, e.g. iMessage ingestion | | Automation | Controlling other apps via AppleScript | Computer use stays fully disabled until Accessibility and Screen Recording are granted. macOS caches the Screen Recording verdict per process, so the app must relaunch once after you grant it; it offers to do this itself. ## Updates The app polls a per-architecture release manifest every 6 hours, and when a newer version exists it downloads the DMG, verifies its SHA-256 hash against the manifest, and swaps the app atomically. A banner at the top of the window announces a ready update; nothing installs without your confirmation. Chatting with your local brain from the web dashboard is built into the app as an outbound relay connection, but the cloud side is not live yet. Until it ships, the app, CLI, and MCP bridge are the ways in.