M1K3

M1K3 for macOS — build from source

The flagship surface: a Mac-native SwiftUI app — on-device MLX inference, live voice (Kokoro TTS + WhisperKit STT), a personal knowledge graph with RAG, an embedded agent, a 3D companion, and a local MCP server other agents can call.

Private by design. M1K3 runs on your Mac. Models download once from Hugging Face; after that the only network use is web search, which is on by default so answers can be current, with one switch in Settings to turn it off. (An opt-in Apple Private Cloud Compute rung arrives in a later release; the 1.0 build has no cloud path.)

Requirements

• macOS 26 (Tahoe) on Apple Silicon — hard requirement: the app uses Liquid Glass, on-device Foundation Models, and Metal via MLX.
• Xcode 26.x (Swift 6.2 toolchain).
• XcodeGen and (optional, nicer logs) xcbeautify: brew install xcodegen xcbeautify
• Disk: nothing to download for the default brain (Mini runs on Apple's on-device models). Allow ~2–7 GB extra only if you opt into the bigger Lil/Big brains.

Build & run

git clone https://github.com/Round-Tower/M1K3.git

cd m1k3/macos

project.yml is the source of truth — M1K3.xcodeproj is generated, not tracked

xcodegen generate

open M1K3.xcodeproj # then ⌘R (set your own dev team for local signing)

Or from the command line:

xcodebuild -scheme M1K3 -destination 'platform=macOS' build | xcbeautify

The same package graph also drives the iOS + visionOS shell (M1K3iOSApp/):

xcodebuild -scheme M1K3iOS -destination 'generic/platform=iOS Simulator' build | xcbeautify xcodebuild -scheme M1K3visionOS -destination 'generic/platform=visionOS Simulator' build | xcbeautify

First launch is one screen: say hello (a name is optional) and you're talking — M1K3 starts on Mini, Apple's built-in on-device model, so there's nothing to download. Sharper local brains (Lil / Big) are one click away in Settings, or via the in-chat offer after your first answer; weights download only when you ask.

Signing note: run with your personal development team. Building with

CODE_SIGNING_ALLOWED=NO compiles fine (CI does it) but the app then runs

without its sandbox container and will read/write the wrong data locations.

Tests

The business logic lives in SwiftPM packages and tests without Xcode:

swift test --parallel --disable-xctest   # the full fast suite (CI runs it without the flag)

tools/dev/tdd.sh M1K3KnowledgeTests # one test target, rebuilt and run alone

Tests use swift-testing (import Testing, @Test), not XCTest.

Heavy MLX/Metal integration tests are env-gated off by default — M1K3_MLX_INTEGRATION=1 swift test opts in (downloads a real model and generates; Apple Silicon only).

Where things are

MCP server

The running app serves MCP over HTTP at http://127.0.0.1:4242/mcp — knowledge search, documents, voice, and ask_m1k3 (ask the resident AI). See docs/MCP_SETUP.md to wire it into Claude Code or any MCP client.

Contributing

See CONTRIBUTING.md at the repo root. Found a bug? In the app: Settings → Report an issue… generates a redacted diagnostic you can attach to a GitHub issue.