Cortex v0.2.1 — Anthropic SDK · Capability-Token Auth · Schema Codegen

Real-time biofeedback engine for macOS that reads cognitive overwhelm
from your face and webcam at 30 FPS, then lets Claude restructure
your workspace.

This is the first release since v0.1.0 (April 4). It bundles an
architectural-grade rewrite of the LLM stack, two Architectural Debts
closed, every one of the 56 audit Ledger findings landed, two phases
of polish, and the full open-source meta layer.

Download

Cortex.dmg — drag to /Applications, then xattr -cr /Applications/Cortex.app to strip quarantine, open and follow the 4-step setup wizard.

Ad-hoc signed — Gatekeeper will warn on first launch. A signed +
notarised build will follow once a Developer ID is provisioned;
the release workflow at .github/workflows/release.yml is already
wired to consume CORTEX_SIGN_IDENTITY / CORTEX_NOTARIZE_PROFILE
secrets.

Highlights since v0.1.0

Anthropic SDK migration

Cortex now talks to Claude exclusively through the Anthropic SDK with
three pluggable transports — AWS Bedrock (default), GCP Vertex AI,
and the direct Anthropic API — selected by a single
CORTEX_LLM__PROVIDER env var. Logical model tiers
(claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-7) resolve
to provider-specific identifiers at call time. Removed: Azure OpenAI,
self-hosted Qwen, and local Ollama clients. Legacy 0.1.x .env files
boot cleanly because the validator maps stale values to the
rule-based fallback.

Debt-1 — Schema codegen drift gate

The Pydantic models in cortex/libs/schemas/ are now the single
source of truth for every shape that crosses the daemon ↔
browser-extension boundary. A custom generator emits a TypeScript
.d.ts with an AUTOGENERATED — DO NOT EDIT BY HAND header.
Both the pre-commit hook and the schema-codegen-check CI job
reject any drift. This collapses six historical findings
(F42 / F43 / F44 / F45 family) into a class of bug that is now
structurally impossible.

Debt-2 — Capability-token auth

Every mutating HTTP route now requires
Authorization: Bearer <token> (with the legacy
X-Cortex-Auth-Token header still accepted as a fallback). The
WebSocket connection opens with an AUTH handshake before
IDENTIFY; any pre-AUTH non-AUTH frame closes with code 1011 and
emits an AUTH_REJECTED event. The 256-bit token lives at
~/Library/Application Support/Cortex/auth.token (mode 0600) and
is rotatable from the desktop Settings UI. SHUTDOWN payloads carry
a defence-in-depth inline token check.

F19 — End-to-end correlation IDs

Every mutating request is stamped with a UUID surfaced as
X-Cortex-Request-ID on responses and injected into structured logs
via structlog.contextvars. The dashboard error toast quotes the
cid back so users can copy it into a support ticket — the
monospace ref: <cid> field is selectable.

Phase I — Performance

Capture loop sub-samples MediaPipe between rPPG windows; parallel
WebSocket broadcast with a hard budget; lazy mediapipe + keyring
imports for sub-2 s startup; the LeetCode observer is now
content-script-only (no more background-tab polling).

Phase J — User-facing polish

Onboarding detects paired iPhone / iPad Continuity Cameras and
surfaces an inline "we'll skip your iPhone camera" callout; every
onboarding card has a "Why we need this?" expander explaining where
the data lives. Daemon errors raise a top-bar toast with the F19
cid quote-back. Empty states for both biometrics and advanced tabs
before the first capture frame. Overlay micro-interactions (headline
scale-in + causal-row fade-in) that honour the macOS
Reduce Motion accessibility preference. A11y sweep with explicit
focus policy + accessible names on previously-overlooked surfaces.

Engineering signals shipped this release

• 56 / 56 Ledger findings closed across two audit sessions plus two
  Architectural Debts. The full ledger is at audit/findings.md; the
  execution log with per-commit traceability is at
  audit/execution-log.md.
• CI matrix expanded to four required gates — schema-codegen
  drift, ruff + mypy --strict + pytest, eval-regression baseline
  (synthetic-trace replay with 3 % relative tolerance), dependabot
  for weekly dependency hygiene.
• 124 pytest files, 1,334 test functions, 17 vitest specs.
• Atomic-write discipline retrofitted onto every persisted
  artifact (handover snapshots, causal reports, project config, ML
  classifier, cost ledger, session recorder) so SIGKILL or disk-full
  mid-write no longer truncates state.
• Multi-layer kill chain (WS → HTTP → native-msg → SIGTERM →
  SIGKILL) documented and regression-tested for the stop button.
• Browser extension now consumes the generated cortex_schemas.d.ts
  union; the switch's never default flags any forgotten case at
  build time.

Breaking changes

• The CORTEX_LLM__MODE env var is gone. Use CORTEX_LLM__PROVIDER
  instead. Stale values are silently mapped to the rule-based
  fallback so 0.1.x .env files still boot.
• Azure OpenAI, self-hosted Qwen, and local Ollama clients have been
  removed. Cortex now talks to Claude via the Anthropic SDK only.
• The WebSocket handshake order is now strict: AUTH → AUTH_OK →
  IDENTIFY → everything else. Pre-AUTH frames close the socket.

See CHANGELOG.md
for the full per-section log.

Verification

make ci      # ruff + mypy --strict + pytest + codegen drift
make test    # 1,334 test functions across 124 files

Acknowledgements

Cortex implements published rPPG algorithms — POS (Wang et al. 2017)
and CHROM (de Haan & Jeanne 2013) — and bundles the
MediaPipe FaceLandmarker
model under Apache-2.0. See NOTICE
for the full third-party attribution.

Cortex v0.1.0 — First Release

Native macOS desktop application for real-time cognitive biofeedback.

Download

• Cortex.dmg — Drag to Applications, open, and follow the 4-step setup wizard.

What's Inside

• Real-time BPM, HRV, and blink rate monitoring via webcam
• Two-tab dashboard: consumer biometrics view + advanced debug view
• One-click browser extension setup (Chrome + Edge)
• One-click editor extension setup (VS Code, Cursor, VSCodium)
• In-process daemon — no terminal required
• BYOK: enter your Azure OpenAI API key once, stored in macOS Keychain

Requirements

• macOS 13+ (Apple Silicon)
• Webcam (built-in MacBook camera works)
• First launch: grant Camera and Accessibility permissions when prompted

Notes

• Ad-hoc code signed (right-click → Open on first launch)
• Browser extension loaded via Developer Mode (Load unpacked)