Mastermind

A personal local-first assistant for macOS

Mastermind is a Swift-native assistant that builds an inspectable understanding of work happening on a Mac and uses it to answer grounded questions. Its primary interface is the normally hidden Companion Island at the top center of the primary display; a Menu Bar Item remains present while the app runs.

The production product is currently in reconstruction. native/MastermindPOC proves the macOS capture and windowing capabilities, while the Electron application under src is legacy reference code.

Canonical context

Start here before product or implementation work:

CONTEXT.md — canonical domain language.
docs/product/mastermind-product-brief.md — product boundary and MVP.
docs/product/companion-island.md — interaction model.
docs/product/mvp-acceptance.md — completion criteria.
docs/architecture/native-mastermind.md — production architecture map.
docs/architecture/system-patterns.md — normative system patterns.
docs/architecture/swift-patterns.md — Swift implementation standards.
docs/development/commenting-standard.md — documentation rules.
docs/privacy/local-first-data-contract.md — normative privacy and data rules.
docs/adr — hard-to-reverse decisions and their rationale.

When older code or text conflicts with these documents, the canonical context wins.

MVP direction

Apple Silicon and macOS 14 or newer.
Swift/AppKit host with SwiftUI content where appropriate.
Continuous local context from screen, microphone, system audio, selected workspaces, selected calendars and Reminders lists, and terminal metadata.
Ephemeral raw screen/audio/transcript data; only structured local derivations persist.
Encrypted local Context Graph with inspectable Provenance.
User-confirmed Facts kept distinct from inferred Assertions.
OpenAI-compatible Local Provider over loopback or a Unix socket.
Separate local ASR sidecar using 16 kHz mono PCM.
Russian, English, and mixed-language work.
Text answers, plans, and drafts only; no autonomous actions.

Codex is a future Provider direction and is deliberately absent from the MVP until an official no-tools integration boundary exists.

Privacy boundary

The MVP does not send machine context to cloud services. Mastermind does not hide its process, permissions, capture indicators, or network activity from macOS or managed environments.

Window exclusion from the app's own capture is required. Exclusion from third-party capture is best effort and is never guaranteed.

Current native capability proof

native/MastermindPOC currently demonstrates:

a menu bar application and transparent AppKit panel;
ScreenCaptureKit screen and system-audio capture;
AVAudioEngine microphone capture;
separate 16 kHz PCM output for microphone and system audio;
current-process window exclusion;
click-through, hide/show, opacity settings, and Pause All;
Swift unit tests and app-bundle build script.

See docs/migration/native-poc-results.md for verified and manual checks. The POC is not the production application and will be retired after its validated capabilities are ported to native/Mastermind.

Build and test the POC

cd native/MastermindPOC
swift test
swift build --product MastermindPOC
./scripts/build-app.sh

Legacy Electron application

The Electron implementation remains available as reference during reconstruction. New product functionality belongs in the Swift application.

npm install
npm test
npm start

Do not use Electron UI, storage, provider coupling, or marketing copy as the source of truth for the native product.

Responsible boundary

Mastermind is a personal work assistant. It is not a proctoring bypass, process-hiding system, monitoring-evasion tool, or means to conceal prohibited AI use. AI output can be wrong; grounded answers must expose evidence and uncertainty.

Contributing

Read AGENTS.md and the canonical context before making changes. Keep production work inside the Swift-native direction and preserve the local-first data contract.

License

Mastermind is licensed under GPL-3.0. See LICENSE.

4.6 KiB Raw Blame History