Getting started

Cortex is a study OS for desktop and iOS: it turns lectures, PDFs, slides, recordings and the web into structured, trustworthy study material. This guide gets you from install to your first cheatsheet in about five minutes.

Installation #

Install from the AUR (Arch/Omarchy), the Homebrew tap (macOS), or grab a signed build for Linux, macOS or Windows from GitHub Releases. iOS ships through TestFlight.

# Arch / Omarchy — via your AUR helper
$ yay -S cortex-bin

# macOS — Homebrew tap
$ brew install --cask pndaman/cortex/cortex

# Any platform — .AppImage / .deb / .dmg / .msi
$ open https://github.com/PndaMan/cortex/releases/latest

On first launch, Cortex runs a short onboarding: paste your key, pick a theme, optionally point it at a homelab, and create your first subject.

Your first subject #

A subject is a course-sized container — it holds topics, sources, and one living cheatsheet. Create one, then add material into its topics.

• Press n (or click New subject) and name it after a course.
• Open the subject and press ␣ s to add your first source.
• Once a source finishes embedding, Cortex drafts a cheatsheet — review the diff to merge it.

Subjects & topics #

Cortex organises everything as Subjects → Topics → Sources. Unlike a flat note pile, this hierarchy is what lets the AI scope its answers and keep cheatsheets coherent per topic.

• Subject — a course. Has a color, a code, and a streak.
• Topic — a unit within a course (e.g. Recursion). Owns its own cheatsheet sections.
• Source — a PDF, slide deck, recording, web page or video filed under a topic.

Sources & ingestion #

Add a source four ways: upload a file, paste a URL or YouTube link, record a lecture, or snap a photo to OCR. Each runs the same pipeline:

parse  →  chunk  →  embed  →  ready

Sources are editable — hover any source card and click ✎ Edit to rename it, move it between subjects/topics, or change its tags. Recordings open a save dialog first so you can title and file them.

Cheatsheets & the approve-diff #

This is the heart of Cortex. Each topic has a sectioned cheatsheet — Definitions, Key Concepts, Formulas, Worked Examples, Common Pitfalls, Quick Recall. When a new source changes a section, Cortex drafts the update and shows a diff instead of overwriting.

Scoped chat #

The chat panel answers within a scope you control via the breadcrumb: a single source, a whole topic, or an entire subject. Click a breadcrumb segment to widen or narrow; click the source chip's ▾ to switch which source you're asking about. Answers carry citation chips that jump to the exact page or timestamp.

Materials #

From the Materials tab, generate study assets from any selection of sources: flashcards, quizzes, audio overviews, slideshow videos and infographics. Each is auto-filed under the dominant topic of the sources you pick, so they slot into the right group.

• Flashcards — SRS deck; rate Again / Hard / Good / Easy.
• Quiz — MCQ, short-answer and cloze with instant feedback.
• Audio overview — a two-host podcast with a synced transcript.

Keybindings #

Cortex is modal, in the spirit of Helix. Three modes, a command palette, and a space-leader hint pane. Every binding is rebindable in Settings → Keybinds.

Models #

Route each task to the provider that does it best in Settings → Models. Chat, cheatsheet synthesis, audio scripts, quizzes, flashcards and embeddings each get their own provider and model. Out of the box Cortex uses DeepSeek V4 Flash via OpenRouter — fast, cheap and 1M-context — and routes image/scanned-PDF OCR to a vision-capable model automatically.

Every key can be verified from Settings with one click, and when a provider is Ollama the model picker lists your installed models live.

Homelab acceleration #

Offload heavy jobs to a box on your network: Whisper transcription, SearXNG web search, Ollama models, the document ingest/OCR pipeline, and encrypted sync. Cortex stays fully functional without a homelab — this just makes big jobs faster and keeps everything self-hosted.

Set one Homelab URL in Settings → Integrations; every service is derived from it via a reverse proxy. Cortex tries your LAN address first, then Tailscale, then a public URL — so the same device works at home, over Tailscale, or anywhere.

# one base URL — services live behind paths
homelab_base = "http://homelab.local:8080"
  /searxng   → web search
  /whisper   → lecture transcription
  /ollama    → local models
  /ingest    → PDF / OCR pipeline
  /sync      → encrypted WebDAV vault

A ready-made docker-compose.yml (Tailscale-only by default) ships in the repo under homelab/ — it even pre-pulls the Whisper model so transcription works on first run.

Web search #

Cortex can search the web through your own self-hosted SearXNG instance, so research and cheatsheet images never route through a third-party search API. It's reached via the /searxng path on your Homelab URL — set the homelab once and search lights up.

Moodle & Google Calendar #

Connect your university LMS and calendar to pull courses, announcements, deadlines and events straight into Cortex.

• Moodle — sign in with your institution (Microsoft/SAML + MFA supported). Courses map to subjects, and announcements & due dates flow into your calendar.
• Google Calendar — connect with OAuth; events sync both ways and surface alongside your assignments.

Both connections sync across your linked devices and show as connected everywhere — the tokens are AEAD-encrypted on-device before they touch your homelab, so they can't be read or changed off the server.

Calendar & assignments #

The Calendar view gathers lecture events, deadlines and assignments in one place. The Assignments tracker shows what's due — grouped by subject and priority — combining items pulled from Moodle with anything you add yourself, so nothing slips before an exam.

Sync across devices #

Enable sync to mirror your whole vault — the database plus original files and recordings — across devices through your own homelab over WebDAV. There is no Cortex cloud.

• Row-level merge — union by id, newest wins, with tombstones for deletes. A row on only one side is never dropped, so nothing is silently lost.
• Background & resilient — it pulls and pushes on a schedule even with the window closed on desktop, and resumes when a device comes back online.
• Encrypted credentials — API keys, Moodle and Google tokens are sealed on-device (XChaCha20-Poly1305) before upload.

Mobile (iOS) #

Cortex runs on iOS — currently in TestFlight beta — built from the same Rust + Svelte core through Tauri. Record lectures on your phone, read sources, review flashcards, and stay in sync with your desktop through your homelab.

On mobile, heavy services (Ollama models, Whisper transcription) are reached via your homelab rather than localhost, and the UI adapts to a touch-first layout with a swipe-out drawer.

Theming #

Cortex ships ten built-in palettes — Gruvbox (default), Tokyo Night, Catppuccin, Nord, Dracula, Everforest, Rosé Pine, Kanagawa, Solarized and Osaka Jade — chosen in Settings → Appearance. On Omarchy Linux, Cortex can read your desktop palette and re-skin live as you switch themes.

All palettes are validated to meet WCAG AA contrast — structure comes from size and weight, so the UI stays legible in every theme. This very page uses the same tokens; try the palettes at the bottom of the landing page.

Data & privacy #

Everything lives in a local SQLite database with a built-in sqlite-vec vector index, stored in the app's data directory. There is no Cortex account and no Cortex server. You can export the archive, clear caches, or wipe it entirely from Settings.