Cortex

Cortex is a multi-tenant AI agent SaaS platform (formerly Zippy, an internal company agent). Teams sign up, create a workspace (organization), invite members, and get an AI super-agent with access to HubSpot CRM, Google Workspace, and shared Brain Knowledge — from a web chat interface, Claude Desktop (MCP), and a native desktop app.

Accounts are powered by better-auth: email + password (with verification and reset), Google SSO, multi-tenant organizations with role-based membership and email invitations, a platform admin layer (ban / impersonate / session management), and TOTP two-factor with backup codes.

---

Architecture at a glance

cortex-agent/
├── apps/
│   ├── web        Next.js 15 (App Router) — chat UI, admin, Inngest background functions
│   ├── mcp        Cloudflare Worker — MCP connector for Claude Desktop
│   └── desktop    Tauri 2 wrapper — native desktop app (shell around apps/web)
├── packages/
│   ├── core           Shared types, env loader, crypto, logger
│   ├── agent-tools    Tool registry, HubSpot / Gmail / Calendar / Sheets / KB / Rate tools, runTool pipeline
│   └── agents         Agent definitions (Sales agent)
└── infra/
    └── supabase       Postgres migrations, RLS policies, pgvector indexes, seed data

Data flow: apps/web and apps/mcp both call into packages/agent-tools → packages/agents → external APIs (HubSpot, Google Workspace, rate-estimator service). All tool results are grounded through packages/core types. Auth tokens for per-user integrations are encrypted at rest in Supabase via TOKEN_ENCRYPTION_KEY.

---

Tech stack

Area	Technology
Language	TypeScript 5.7
Runtime	Node 20.17.0
Package manager	pnpm 9.12.0 (via Corepack)
Monorepo	Turborepo 2
Web framework	Next.js 15 (App Router)
UI	React 19, Tailwind CSS, shadcn/ui (Radix UI), Framer Motion
AI / LLM	Vercel AI SDK 4, Claude Opus 5 (generation) + Voyage AI voyage-3-large (embeddings)
Auth	better-auth — email/password + Google SSO, organizations (multi-tenant), admin, 2FA
Database	Supabase — Postgres 15 + pgvector + Auth + Storage
Background jobs	Inngest
MCP connector	Cloudflare Workers + Hono
Desktop	Tauri 2
Observability	Sentry, OpenTelemetry
Testing	Vitest (unit), Playwright (e2e)
Linting / formatting	Biome

---

Quick start

For a detailed first-time setup guide see docs/operations/local-setup.md.

# 1. Install dependencies
nvm use && corepack enable && pnpm install

# 2. Configure environment
cp .env.example .env.local   # then fill in all values — see docs/operations/secrets.md

# 3. Start local Supabase (requires Docker Desktop running)
pnpm db:start

# 4. Apply all migrations
pnpm db:reset

# 5. Start the web app
pnpm --filter @cortex/web dev
# Visit http://localhost:3000 → create an account (or Google SSO) → /chat

pnpm dev (without filter) runs the full Turborepo pipeline — all apps in parallel. Use the filtered form above if you do not have the Rust toolchain (Tauri) or a Cloudflare login (wrangler) set up.

---

Common scripts

Script	What it does
pnpm dev	Start all apps in dev mode (Turborepo)
pnpm build	Build all packages and apps in dependency order
pnpm lint	Run Biome lint across all packages
pnpm typecheck	TypeScript type-check all packages
pnpm test	Run Vitest unit tests across all packages
pnpm test:e2e	Run Playwright e2e tests
pnpm format	Auto-format with Biome
pnpm db:start	Boot local Supabase via Docker
pnpm db:stop	Stop local Supabase containers
pnpm db:reset	Wipe and reapply all migrations + seed data
pnpm db:push	Push pending migrations to a linked remote Supabase project

---

Project structure

cortex-agent/
├── apps/
│   ├── web/            Next.js 15 web app (chat UI, admin, API routes, Inngest functions)
│   ├── mcp/            Cloudflare Worker MCP connector (Claude Desktop integration)
│   └── desktop/        Tauri 2 native desktop wrapper
├── packages/
│   ├── core/           Shared types, env loader, crypto utilities, structured logger
│   ├── agent-tools/    Tool registry, integration connectors, runTool pipeline
│   └── agents/         Agent definitions (Sales agent system prompt + runtime)
├── infra/
│   └── supabase/       DB migrations (14 files), RLS policies, pgvector, seed data
├── docs/
│   ├── operations/     Setup runbooks, deploy guides, OAuth setup, secrets reference
│   └── superpowers/    Design specs and implementation plans
├── .env.example        Template for .env.local
├── package.json        Root scripts and devDependencies
├── pnpm-workspace.yaml Workspace definition
├── turbo.json          Turborepo task pipeline
└── biome.json          Linting and formatting config

---

Links

Resource	Path
Design spec	docs/superpowers/specs/
Implementation plans	docs/superpowers/plans/
Local setup runbook	docs/operations/local-setup.md
Secrets reference	docs/operations/secrets.md
Deploy runbook	docs/operations/deploy.md
MCP connector deploy	docs/operations/mcp-deploy.md
Claude Desktop install	docs/operations/claude-desktop-install.md
Google OAuth setup	docs/operations/google-oauth-setup.md
HubSpot OAuth setup	docs/operations/hubspot-oauth-setup.md