Architecture
How Compass works
Two completely separate AI pipelines. Shared infrastructure. No compromises.
Pipeline comparison
Two independently optimized AI paths
LocalAlways on, always private
- Latency
- <100ms (target; benchmarks published)
- Model
- 4B on-device LLM via MLX
- Privacy
- 100% offline, nothing leaves your machine
- Tasks
- FIM completion, inline Q&A, semantic search, local chat
- Network
- No internet required. Ever.
- Boundaries
- No orchestration, no tool loop, by design
CloudOn demand, full reasoning
- Latency
- Seconds (task-dependent)
- Model
- Any provider: OpenRouter, Kilo, DeepSeek, Alibaba, or any OpenAI-compatible endpoint
- Privacy
- Opt-in, you choose when code is sent
- Tasks
- Agentic refactors, multi-file planning, tool orchestration, review
- Network
- Requires internet, offline falls back to local
- Boundaries
- Never runs inline completion; that's the local pipeline's job
Infrastructure
Shared services powering both pipelines
CodebaseIndex
SQLite-backed index with symbol extraction, file watching, and chunk management. The vector index uses HNSW over FAISS for embedding-based semantic search, 10–50× fasterthan the original brute-force approach with ~95–99% recall.
Services/Index/DatabaseManager.swiftInlineCompletionEngine
Local FIM completion subsystem with ghost-text rendering (Tab accept, Esc dismiss), debounced triggers, language-scoped context assembly, completion caching, duplicate filtering, and ranking. The tightest latency loop in the app - target: <100ms end-to-end.
Services/LocalPipeline/AITool System
20+ tools implementing the AITool protocol, executed by ToolLoopHandlerin the cloud pipeline. Includes file I/O, terminal commands, search, project management, and diagnostic tools. Stall detection prevents runaway loops. Results are QA-reviewed before final application.
Services/Tools/ · Services/CloudPipeline/ConversationOrchestrator
Multi-role orchestration graph: Planner → Worker → QA → Final. The planner synthesizes a plan, the worker executes tool loops, QA reviews the output, and the finalizer applies the change. Supports streaming responses, conversation folding, and history persistence.
Agent Context Retrieval
The cloud pipeline's retrieval layer with intent classification, evidence fusion ranking, code segment retrieval (HNSW-backed), symbol search, and project overview. Designed to inject relevant context without overloading the model. The local pipeline has its own on-device retrieval, same philosophy, different hardware.
EventBus
Central typed event system using Combine PassthroughSubject. Every pipeline, service, and UI component communicates through the bus. Events are dispatched by type name. Subscribers receive onDispatchQueue.main. Loose coupling by design.
Core/EventBus.swiftDeveloper experience
Built for the Mac
Syntax highlighting
Powered by tree-sitter AST parsing with the Neon runtime - not regex-based tokenization. Supports 20+ languages with accurate, incremental, and fast highlighting. Customizable color schemes per-language via the settings UI.
Packages/SyntaxHighlighting/Terminal integration
Embedded terminal with the system shell (/bin/zsh or /bin/bash), build error parsing, and clickable links to editor locations. Build error diagnostics are parsed for file/line references - click to navigate directly to the issue.
Packages/Terminal/