Disclaimer: Compass is for informational purposes only to support conversations with your medical team. It does not constitute medical advice. All treatment decisions should be made in consultation with your treating physicians.
The medical system regularly fails rare-disease patients — not from malice, but from structural mismatch. Specialists operate in silos. Follow-up surveillance falls through the cracks. Families juggle dozens of contacts, appointments, records, and decisions across months or years, often without anyone keeping the whole picture in view. A surveillance scan gets skipped and no one tracks the gap. A tissue sample gets discarded before anyone thinks to bank it. A clinical trial closes before the family knew it existed.
Compass is an AI co-pilot that fills that coordination gap. It maintains a structured knowledge base of the patient's case — medical records, scan history, molecular findings, treatment history, clinical trials — and updates it automatically as new documents arrive. It thinks across the whole case, not just the last appointment. It flags risks proactively, before they become urgent. It drafts communications that are calibrated to their audience — concise and clinical for doctors, clear and honest for family. And it does all of this in coordination with everyone on the care team, not just one person.
Compass is built on the same principles as a great medical advocate: it knows the case cold, thinks two steps ahead, asks the questions no one else is asking, and never lets something fall through the cracks. It is not a replacement for doctors or medical judgment. It is a force multiplier for the family doing the hardest work of their lives.
Compass runs inside Claude Cowork (a product within Claude Desktop — distinct from the Claude Chatbot and Claude Code surfaces) and inside Codex Desktop. It requires only a folder it can read and write — no servers, no databases, no subscriptions beyond your AI subscription. Your case files stay on your machine and your cloud storage. Nothing is sent anywhere else.
- Case knowledge base — ingests medical records (PDFs, Word documents, spreadsheets) and builds a structured summary: molecular profile, treatment history, scan history, timeline, consultation log, clinical trials. Updates automatically as new files arrive.
- Daily catch-up (
/compass:update) — scans new files, emails, calendar, meeting transcripts, and notes; assembles a morning briefing of what's new, what's due, and what needs attention. Runs in file-only mode when email and calendar connectors are not configured. - Deep research (
/compass:research) — tiered decision framework from standard-of-care through first-principles, with regulatory-status awareness (approved / expanded access / IND pathway / etc.) for every recommendation. - Meeting prep (
/compass:prep) — concise prep file for any upcoming call: who the contact is, what you've discussed before, open action items, recent developments, suggested questions. - To-do management (
/compass:todo) — workstream-organized, multi-user, with action items pulled automatically from emails and meeting transcripts. Items carry assignee and attribution. - Email drafts (
/compass:email) — audience-aware tone: clinical and concise for doctors, plain-language and honest for family. Produces drafts only — you always review and send manually. - Contacts (
/compass:contacts) — central directory of doctors, consultants, advocates, and specialists with role, institution, specialty, and relationship notes. - Daily briefing email (
/compass:briefing) — optional scheduled email summarizing what's new, what's due, what's coming up. Configurable recipients, cadence, and content. - Hourly scheduled updates — optional background task that checks for new information and flags material changes without prompting for input.
- Proactive considerations — agent flags risks, missed surveillance opportunities, and preparatory steps — written to
patient/considerations.mdand surfaced in every briefing. - Multi-user — family members, advocates, and care team members all use the same shared case folder, with to-do items assignable by name and every change attributed.
- Multi-host — runs as a Claude Cowork plugin inside Claude Desktop (not the Chatbot or Claude Code surfaces) and as a Codex Desktop plugin. Background tasks use Cowork's scheduler on Claude, Automations on Codex.
| Connector | Status | What it enables |
|---|---|---|
| Local or cloud-synced folder (Google Drive Desktop, Dropbox, iCloud, etc.) | Required | Reading and writing case files |
| Gmail or Outlook | Recommended | Email drafts, inbox scanning, action-item extraction |
| Google Calendar or Outlook Calendar | Recommended | Upcoming-meeting detection, prep file triggering |
| Fireflies, Otter, or Granola | Recommended | Automatic meeting transcript ingestion |
| Apple Notes | Optional | Notes ingestion during /compass:update |
All connectors are optional except the folder. The agent degrades gracefully — each step prints a one-line notice and continues if a connector is not configured.
Compass is a Claude Cowork plugin. Cowork is one of three surfaces bundled in Claude Desktop (the others are Claude Chatbot and Claude Code). The plugin marketplace and scheduled tasks used by Compass only exist inside Cowork — installing or running Compass in the Chatbot or Claude Code surfaces will not work.
- Sign up for a paid Claude account at claude.com/pricing. Claude Max ($100+/month) is recommended — Compass does heavy research and long multi-file sessions that benefit from the higher usage limits. Pro ($17–20/month) works for lighter use.
- Open Claude Desktop and switch to Cowork (left sidebar → Customize; this is the Cowork workspace where plugins live).
- Go to Settings → Plugins.
- In the marketplace input, paste:
jordajm/compass - Click Add — Claude Desktop fetches the marketplace entry.
- Click Install on the
compassplugin listing. - Create (or open) a folder for the patient's case. This is where Compass will store all case files. A Google-Drive-Desktop-synced folder works best so you can share it with your care team.
- In that folder, type
/compass:onboarding. Compass will guide you through the rest.
For a fully-illustrated walkthrough, see docs/install-claude-desktop.md. To set up hourly background updates via Claude Cowork, see docs/install-cowork-scheduled-task.md.
git clone https://github.com/jordajm/compass.git
claude --plugin-dir ./compass
This loads the plugin directly without installing it — useful when iterating on the plugin itself.
Codex's plugin ecosystem is UI-driven — plugins install through the in-app Plugins panel. Until Compass is listed in the official Codex plugin directory, use the manual-install path below.
- Clone the repository directly into Codex's plugins folder:
git clone https://github.com/jordajm/compass.git ~/.codex/plugins/compass - Restart Codex. It auto-discovers plugins under
~/.codex/plugins/. - Generate the Codex subagent TOML files from the shared agent source:
This installs
bash ~/.codex/plugins/compass/scripts/build-codex.shcompass-*.tomlsubagent files at~/.codex/agents/. - Navigate to your case folder and type
@onboarding— Codex will auto-load the skill and start the guided setup.
To set up hourly background updates via Codex Automations, see docs/install-codex-automations.md.
cd ~/.codex/plugins/compass && git pull
bash scripts/build-codex.shOnce the Codex plugin directory lists Compass, you will be able to install from the in-app Plugins panel with one click. Check github.com/jordajm/compass for the updated install path.
Once installed, start the onboarding conversation:
- Claude Desktop: type
/compass:onboarding - Codex Desktop: type
@onboarding
Compass will ask you a series of questions — who the patient is, their condition, where you are in treatment, who else is on the care team — and build the case files from your answers. If you have existing medical records, drop them in a documents/ folder and Compass will read them in batches. No config files to edit.
Onboarding takes 5–15 minutes for a typical case and can be paused and resumed at any point.
If anything feels off at any point, run /compass:troubleshoot (or @troubleshoot in Codex) for a health check covering plugin version, case file integrity, connector status, and storage writability.
- All case data stays on your machine and your chosen cloud storage (Google Drive, Dropbox, iCloud, etc.). Compass does not transmit your data to any external service beyond the AI model you're already using.
- The AI model (Claude or Codex) processes your inputs per Anthropic's or OpenAI's standard privacy policy. Review their policies if you have concerns about sensitive medical information.
- Compass never sends email automatically. All
/compass:emailoperations produce drafts only; you review and send manually. - Compass never deletes files.
- The disclaimer "This is not medical advice" appears at the top of every research report and every email draft.
Running a health check. If anything feels off, run /compass:troubleshoot (or @troubleshoot in Codex) for a diagnostic report. It checks plugin version, case file integrity, connector status, storage writability, and whether a newer Compass release is available — then prints a single table with copyable fixes. Start here before the specific issues below.
"The agent says it can't find Gmail."
Gmail is optional. If you haven't configured the Gmail connector, Compass will skip email steps and continue. To enable Gmail, follow the connector setup instructions in /compass:onboarding or run it again and choose the Gmail option.
"My case files aren't being read."
Make sure you're running Compass from the correct working directory — the folder containing patient/PROFILE.md. In Claude Desktop, open the folder as a project. In Codex Desktop, select the matching project.
"I'm getting context-limit errors or the session feels slow."
Start a fresh chat. Long sessions with many files read accumulate context quickly. In Claude Desktop, click "New chat" or type /clear. In Codex Desktop, start a new session. Compass saves its state to files so nothing is lost.
"The agent keeps asking me who I am."
Configure the Gmail connector (or Outlook). Compass identifies you by matching your connected email account against the care team roster. Without an email connector, it asks at the start of each session. You can also set your name in the <!-- compass:prefs --> block in ~/.claude/CLAUDE.md.
"I dropped files in documents/ but they weren't processed."
Run /compass:update --ingest to process new files. Compass processes files in batches (15 files per session by default) to manage context. If you have many files, run /compass:update --ingest multiple times — ideally in a new chat each time — until the status shows "all files processed."
"A care team member can't see the case files."
Make sure you've shared the case folder with them in Google Drive (right-click → Share in Drive on the web). Each team member needs to install Compass on their own machine, point it at the shared folder, and run /compass:onboarding — Compass will recognize the existing case and skip re-setup.
Compass is open source under the MIT license. Contributions welcome.
- Bug reports and feature requests: GitHub Issues
- Pull requests: please open an issue first to discuss the change
- If you've used Compass on a real case and have feedback, please share it — user experience from families in the middle of a medical case is the most valuable input
Compass is an open-source generalization of IDA, built by John Jordan.