Technology
Architecture
The Mac app manages workers and conversations. A provider chooses the next step. The engine reads the window as text, acts on the seat and verifies the effect. The driver owns the seat: a virtual display, the adopted window, input and capture.
System responsibilities
App and provider
Workers, conversations, settings, the provider’s turn.
Engine
Scene, target resolution, policy, verification, the Brain.
Driver
Virtual display, window placement, input to one window, cursor fence, capture, validated builds.
| Layer and modules | What it owns |
|---|---|
| Mac app BrausApp | Workers, conversations and events in Workspace.store, Settings, the keychain, the worker hosts for agents and for the model loop. |
| SeatBroker SeatBroker | What the app talks to: the seat queue, a worker’s desktop session, permissions, build validation. |
| Driver SeatCore, PrivateSymbols, VirtualScreens, WindowPlacement, SeatInput, CursorGuard, SeatCapture, SeatSession, TargetReader | The seat itself and the ledger of validated macOS builds. |
| Perception PerceptionCore, VisionText, IncrementalText, WindowServerListing, AccessibilityFacts, PixelControlState, PixelRegions, PixelSections, Perception, ScreenCapture | The window as a text Scene: OCR, visual candidates, panels, accessibility facts, control state from pixels. |
| Engine EngineCore, Engine, Memory, FileKnowledge, LiveScenes, HIDActuation, AccessibilityActions, WorkspaceActivation | The act cycle and its verification, the Brain and its files, and the foreground adapters the command line uses without a seat. |
| Integration SeatDriving, AutomationRuntime, AutomationMCP | The seat filling the engine’s roles; the desktop tools and their schemas. |
| Chat ChatCore, CLIProviders, FileConversations, LocalMCP | The Claude Code and Codex adapters, command-line transcripts, the loopback MCP bridge. |
| ModelTransports ModelTransports | The Anthropic, Gemini and Ollama clients and the model catalogue. |
| Tools braus, braus-bridge | The command line (windows, scene, act, select, batch, memory, peek and chat) and the bridge helper the app launches for an agent. |
A seat is a virtual display with input routed to one window. It is not a virtual machine, a separate Mac or a separate user account.
Execution path
- Observe: the seat captures the adopted window; Perception reads it into a Scene; the Brain annotates what it already knows.
- Plan: the provider receives the task, the conversation and the Scene as text, and asks for a tool.
- Resolve: the runtime checks the session ID, the seat’s readiness and the target by label or element ID; destructive targets are refused unless a person allowed them.
- Act: the input goes through the seat to the adopted window, never as a global event.
- Check: an oracle or the difference between two Scenes decides the outcome; the Brain records the effect.
Coordination and concurrency
Workers converse in parallel; one worker runs one turn at a time, and the MCP bridge runs one tool call at a time. The seat queue grants one seat: a worker keeps it 30 seconds after a turn and gives it back at once when another is waiting. A conversation that needs no app needs no seat.
See Background for windows, outcomes and stopping.
Memory and state
| Layer | Responsibility |
|---|---|
| App knowledge | One file per application in Knowledge, with daily backups. Written by the engine while sessions observe and act; recalled before an action. |
| Brain view | Inspect app knowledge under Settings → Computer → Brain. Reasoning remains the provider’s job. |
| Workspace history | Workers, conversations, messages and events in Workspace.store, with the provider session ID that a resume offers back to the same provider. |
| Window context | The current target and observation. Revalidated before input; invalid after a restart. |
Implementation boundaries
| Component | Data | Where it goes |
|---|---|---|
| Perception | Window images | Stay on the Mac. The Scene is text. |
| Worker turn | Prompts, Scene text, tool results | The provider you chose: Anthropic or Google endpoints, the command line’s own service, or your Ollama server. |
| MCP bridge | Tool calls and results | A loopback port on the Mac, with a private credential file removed at shutdown. |
| Keychain | Anthropic and Gemini API keys | The login keychain. |
| Files | Knowledge, history, transcripts | The Braus folder under Application Support. |
| Account | Sign-in | Your Forte account. The open source edition does not sign in. |
The open source edition of Braus is under Apache 2.0: its app, the engine and the background driver. These guides describe the Braus app downloaded from this site, which works with a Forte sign-in.
Source scope
These guides describe the source baseline named below. Launch support includes external MCP connections from Claude Code and Codex. MCP and agents also documents other local STDIO clients, not each tested end to end; Gemini and Ollama are model connections in Braus. Installation is in Get started. Source coverage does not mean every workflow has been tested.
Verified source
Checked against Braus app source at main 524eb7f on October 1, 2026. UI labels and paths have not yet been checked against the Braus build downloaded from this site.