Cortex

Local desk for Reactive Agents: Bun + Elysia API, SQLite store, WebSocket ingest/live fan-out, and a SvelteKit UI (Beacon / Trace / Lab).

Contributors & AI agents: see AGENTS.md in this folder for architecture, WS contracts, store map, pitfalls, and plan index.

Prerequisites

From the repo root:

bun install

Start everything (recommended for review)

From apps/cortex:

cd apps/cortex
bun start

This runs:

1. Cortex server on http://localhost:4321 — REST, ingest WS, live WS.
2. SvelteKit dev on http://localhost:5173 — Vite proxies /api and /ws to the server.

Open the UI at port 5173. The server does not auto-open a browser when started via bun start (so your tab stays on the dev UI).

Two terminals (optional)

| Terminal | Command | Role | |----------|---------|------| | 1 | cd apps/cortex && bun run dev:server | API + WS on 4321 | | 2 | cd apps/cortex && bun run dev:ui | UI on 5173 (proxied to 4321) |

Environment

| Variable | Default | Purpose | |----------|---------|---------| | CORTEX_PORT | 4321 | HTTP + WS listen port | | CORTEX_NO_OPEN | unset | Set to 1 to disable opening a browser when running dev:server alone |

SQLite path comes from defaultCortexConfig in server/types.ts (default .cortex/cortex.db under the current working directory — usually apps/cortex).

Security note (Lab — host shell)

The Lab builder can opt in to shell-execute, which runs allowlisted terminal commands on the same machine as the Cortex server. It is disabled by default; enabling it is at your own risk. When enabled, you can add extra allowed command names or (advanced) replace the default allowlist in the Tools section; defaults and opt-in lists match ShellExecuteConfig in @reactive-agents/tools. Use only on trusted accounts and codebases, and read the framework docs on blocklists and Docker sandboxing for stronger isolation.

Production-style UI (single port)

Build the static UI and let Cortex serve it from ui/build:

cd apps/cortex
bun run build:ui
bun run dev:server

Then open http://localhost:4321. (Ensure server/index.ts staticAssetsPath points at the built UI — it does when run via the bundled entry.)

Tests

cd apps/cortex
bun test

UI component/store tests:

cd apps/cortex/ui
bun test

UI checks

cd apps/cortex/ui
bun run check   # svelte-kit sync + svelte-check
bun run build

Plans

Implementation tracks docs/superpowers/plans/2026-03-31-cortex-app-phase*.md:

• Phase 3 — Beacon (agent grid, bottom input, WS desk).
• Phase 4 — Run detail at /run/[runId] (vitals strip, D3 signal monitor, trace panel, debrief card, bottom tabs for decisions / memory / context). Live + replay via /ws/live/:agentId?runId= after REST loads the run row.
• Phase 5+ — Lab, command palette commands, replay scrubber, etc.