Skip to content
jtrefonPublic

About

Compass, the 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. MIT. No Electron. No lock-in.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

805 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Compass

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.

CI Release


Why Compass exists

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.

Quick start

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/releases

First 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.

What's shipping

  • 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/

Development

./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 artifacts

The 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.xcodeproj

Note 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.

The harness — the agent is tested by agents

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.

Contributing

Contributions are what make this project real. Start here:

The roadmap (v1.0 → v1.5 → v2.0) is published on the website, in the open.

Troubleshooting

Xcode/SourceKit "false compile errors"

Sometimes Xcode/SourceKit shows red errors (missing types, failed imports) while xcodebuild build and xcodebuild test are green. Recovery steps, in order:

  1. Quit Xcode.
  2. ./run.sh clean
  3. Delete DerivedData for this project: ~/Library/Developer/Xcode/DerivedData/ (the Compass-* folder)
  4. Re-open Compass.xcodeproj
  5. 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.

Terminal / shell

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.

License

MIT — see LICENSE. Copyright © 2025–2026 Jacek Trefon.

About

Compass, the 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. MIT. No Electron. No lock-in.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages