DocsTechnology
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
Workers, conversations, settings, the provider’s turn.
Scene, target resolution, policy, verification, the Brain.
Virtual display, window placement, input to one window, cursor fence, capture, validated builds.
| Layer and modules | What it owns |
|---|---|
| Mac app MecumApp | 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 mecum, mecum-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 Mecum folder under Application Support. |
Mecum is open source under Apache 2.0, including the app, the engine and the background driver.
These guides describe the source baseline named below. Launch support includes external MCP connections from Claude Code and Codex. Models & MCP also documents other local STDIO clients, not each tested end to end; Gemini and Ollama are model connections in Mecum. Installer instructions are being finalized. Source coverage does not mean every workflow has been tested.
Checked against Mecum app source at main 524eb7f on October 1, 2026. UI labels and paths have not yet been checked against the signed release build.