95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
<div align="center">
|
|
<img src="assets/images/logo.png" alt="Mastermind Logo" width="200"/>
|
|
|
|
# Mastermind
|
|
|
|
### A personal local-first assistant for macOS
|
|
|
|
</div>
|
|
|
|
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`](CONTEXT.md) — canonical domain language.
|
|
- [`docs/product/mastermind-product-brief.md`](docs/product/mastermind-product-brief.md) — product boundary and MVP.
|
|
- [`docs/product/companion-island.md`](docs/product/companion-island.md) — interaction model.
|
|
- [`docs/product/mvp-acceptance.md`](docs/product/mvp-acceptance.md) — completion criteria.
|
|
- [`docs/architecture/native-mastermind.md`](docs/architecture/native-mastermind.md) — production architecture.
|
|
- [`docs/privacy/local-first-data-contract.md`](docs/privacy/local-first-data-contract.md) — normative privacy and data rules.
|
|
- [`docs/adr`](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`](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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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`](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`](LICENSE).
|