Open source
For contributors
Compass is MIT-licensed and built entirely in Swift. If you want to shape how native AI development works on macOS, or just want a project that tests its AI with AI, this is the place.
Codebase
~40,000 lines of Swift across compass/, the harness tests, and the UI layer. Build with Xcode 26+ on Apple Silicon. The project uses xcodebuild (not SwiftPM) for the main target, with SPM packages for SyntaxHighlighting(tree-sitter) and Terminal.
Get started
./run.sh build ./run.sh test ./run.sh harness
See AGENTS.md and ARCHITECTURE.md in the repo. Everything runs from ./run.sh.
Where to start
Two-pipeline isolation
The core architecture: local (4B MLX, no orchestration) and cloud (orchestration graph, 20+ tools). They share zero AI execution code.
compass/Services/LocalPipeline/ · compass/Services/CloudPipeline/Codebase index
SQLite index for symbols, chunks, and files, with HNSW-backed embedding retrieval. All in compass/Services/Index/.
compass/Services/Index/DatabaseManager.swiftInline completion engine
Local FIM completion with ghost-text rendering, caching, ranking, and sub-100ms latency. The tightest latency loop in the app.
compass/Services/LocalPipeline/InlineCompletionEngine.swiftAgent tool system
20+ tools implementing the AITool protocol. The tool loop runs in ToolLoopHandler.swift with stall detection.
compass/Services/Tools/ · compass/Services/CloudPipeline/ToolLoopHandler.swiftThe harness: our AI tests AI
Compass ships a headless integration harness that runs real agentic tasks through the real pipeline and validates the outcome: no mocks, no stubs. When your PR touches the agent, the agent gets tested by agents. Few projects can say that.
compassHarnessTests/ · ./run.sh harnessFor full architecture docs, read ARCHITECTURE.mdand FEATURES.md.
Your first PR starts here
Pick a good first issue, open a Discussion with your idea, or clone the repo and start exploring. Every contributor starts somewhere, and the roadmap is decided in the open.