AI coding that respects your machine.
Compass is a native AI IDE for macOS: agentic coding with your own provider and keys, plus on-device RAG, FIM completion, and local chat that work fully offline. ~200MB, MIT licensed, no Electron, no lock-in.
Status: pre-alpha → alpha (single maintainer, daily-driving the editor). We're honest about maturity — nothing gets pitched until it's earned. See ROADMAP.md for where we are and where we're going, and BENCHMARKS.md for the numbers we've measured.
My MacBook Pro M4 has 16GB of RAM. Cursor and Docker were using all of it — YouTube started stuttering, and I was swapping like it was 2009. So I built my own IDE.
Compass is the editor I use every day to build itself: a real macOS binary (SwiftUI + AppKit, Liquid Glass, Apple Neural Engine) with two deliberately separate AI pipelines:
| Local pipeline | Cloud pipeline | |
|---|---|---|
| What it does | FIM completion (<100ms), inline Q&A, semantic search, local chat | Agentic coding: Planner → Worker → QA, 20+ tools, stall detection |
| Model | 4B on-device LLM via MLX | Your choice — OpenRouter, Kilo, DeepSeek, Alibaba, any OpenAI-compatible endpoint |
| Privacy | 100% offline, nothing leaves your machine | Opt-in only, your key, your bill |
| Network | None required. Ever. | Required for agentic work |
The local model never orchestrates. The cloud model never runs inline completion. Each does what it's best at: that's the whole architecture in one sentence.
Vibe code at full speed. Bring the best model in the world, run the full agentic pipeline at native speed, pay your provider's rate — not a per-seat tax.
And keep working at 30,000 feet. No network? RAG over your codebase, FIM completion, and local chat all still work. The intelligence is on-device too.
Nobody can sell it out from under you. MIT, auditable, forkable, and your data stays yours.
Requirements: Apple Silicon Mac, macOS 26+, Xcode 26+ for building from source.
# Install via Homebrew (one command; auto-taps the cask)
brew install --cask jtrefon/compass/compass
# Or the one-line installer (downloads the latest release, checks the signature):
curl -fsSL https://raw.githubusercontent.com/jtrefon/compass/main/install.sh | bash
# Or grab the latest DMG/ZIP from Releases
# https://github.com/jtrefon/compass/releasesFirst launch: Compass indexes your project and pulls the on-device model. Local completion, chat, and search work immediately: no keys, no account, no network.
For agentic coding, add your own API key (OpenRouter, Kilo, DeepSeek, any OpenAI-compatible endpoint) in Settings → Providers. Your key, your bill, your choice.
The honest part: builds are not notarized yet. Compass ships without Apple's paid notarization, like many open-source Mac apps; your Mac will ask you to confirm once (right-click → Open). The source is right here if you'd rather verify first.
- Real FIM completion — ghost text in <100ms from a 4B on-device model, not a remote round-trip, not a fake heuristic
- Private local chat — ask questions, bounce ideas, get a second pair of eyes, entirely on-device
- ANE-accelerated RAG — SQLite index + HNSW/FAISS retrieval, embeddings on the Apple Neural Engine
- Agentic coding, your provider — Planner → Worker → QA orchestration, 20+ tools, harness-tested
- Built-in terminal & browser, tree-sitter highlighting across 20+ languages, per-project system prompts, command palette, project state persistence
Full detail: FEATURES.md · ARCHITECTURE.md · website: https://jtrefon.github.io/compass/
./run.sh app # Build and launch
./run.sh build # Full Xcode build
./run.sh test # Unit tests (skips UI-heavy suites)
./run.sh test SuiteName # Single suite filter
./run.sh harness # Headless integration tests
./run.sh harness-online # Live-provider suites (needs API keys, serial)
./run.sh harness-offline # Offline suites
./run.sh benchmark-offline # Embedding model benchmarks
./run.sh e2e # XCUITest suites
./run.sh clean # Remove build artifactsThe project builds with xcodebuild (scheme Compass), not swift build. Derived data:
.build/ for the app, .build-tests/ for tests.
If package resolution fails on the first attempt (a known SwiftJinja/OrderedCollections quirk):
xcodebuild -resolvePackageDependencies -project Compass.xcodeprojNote for AI agents: this repo has an
AGENTS.md— read it before touching code. It documents the architecture, the harness system, and the conventions the project lives by.
Compass ships a headless integration harness (CompassHarnessTests/) that instantiates the real
app, injects a prompt, and validates the full pipeline via telemetry. No mocks, no stubs — it runs
the actual production code paths. If you touch the agent loop, ./run.sh harness is part of the
deal. See AGENTS.md and CONTRIBUTING.md.
Contributions are what make this project real. Start here:
- CONTRIBUTING.md — how to build, test, and submit changes
- Discussions — ideas, questions, roadmaps
- Issues — bugs and feature requests
The roadmap (v1.0 → v1.5 → v2.0) is published on the website, in the open.
Sometimes Xcode/SourceKit shows red errors (missing types, failed imports) while
xcodebuild build and xcodebuild test are green. Recovery steps, in order:
- Quit Xcode.
./run.sh clean- Delete DerivedData for this project:
~/Library/Developer/Xcode/DerivedData/(theCompass-*folder) - Re-open
Compass.xcodeproj - If needed:
File > Packages > Reset Package Caches
If it persists but xcodebuild is green, treat xcodebuild as the source of truth and file an
issue with your Xcode version, repro steps, and a screenshot.
The embedded terminal uses the system shell (/bin/zsh or /bin/bash). If spawning a shell
fails, grant the app Full Disk Access in System Settings.
MIT — see LICENSE. Copyright © 2025–2026 Jacek Trefon.