CORTEX Docs

Get started

Cortex

Cortex is a Windows desktop application that runs AI coding-agent CLIs (Claude Code, Codex, OpenCode) as managed "agents" and controls them from one window. Version 0.2.0, distributed as an unsigned per-user Windows installer (Cortex_0.2.0_x64-setup.exe) or built from source.

What problem it solves#

Each coding-agent CLI is a separate terminal session with its own process, state and lifecycle. Cortex puts them under one control surface: you register projects and agents, start, stop and restart the CLI processes, read their output (or use the CLI's own terminal inside the window), hand work to agents as tasks, and let external tools drive the same operations through a local MCP server.

What it does today#

  • Projects and Agents kept in JSON files in a per-user data directory; Agent state is tracked (CREATED, STARTING, READY, BUSY, PAUSED, STOPPING, STOPPED, FAILED, CRASHED) and Start / Stop / Restart / Pause are available from the window, from the card or from a right-click menu on it. An agent can be given the orchestrator role: it coordinates other agents and cannot read, change or run anything in the project.
  • Three runtime adapters: Claude Code (structured or terminal mode), Codex (structured, read-only sandbox) and OpenCode (structured, over ACP). The window creates only Claude Code agents; Codex and OpenCode agents are created through the MCP create_agent tool.
  • Orchestrator panel and Tasks screen: one instruction becomes one Objective with one Task, taken by an eligible READY structured Agent of the project. Retries, waiting reasons and Cancel are supported.
  • MCP server inside the desktop process on 127.0.0.1:47821 (configurable), with 32 tools, bearer-token access for local clients and OAuth approval in the window for remote clients that reach Cortex through your own HTTPS tunnel.
  • Runtimes screen, opened on first start: shows for each CLI whether it is found, its version and whether it is signed in, and installs the missing ones you select with their official installers (winget for Claude Code, OpenAI's installer for Codex, npm for OpenCode). Existing installs are kept; signing in stays with each CLI. A CLI installed while Cortex runs is found without a restart.
  • Processes screen, structured JSON logs with rotation, and a configuration file read at startup.

Limitations#

  • Windows only. Process launching uses Job Objects and ConPTY, which exist only in the Windows build. The workspace compiles elsewhere with stubs, but no agent can start there.
  • No cortex command-line tool and no settings screen (edit config.json and restart). The installer is not code-signed.
  • Structured agents cannot do anything that needs approval: Claude Code runs with --permission-prompts none, Codex with --sandbox read-only, and OpenCode permission requests are rejected.
  • Sessions and agent output are in memory: after a normal close agents come back STOPPED, and if Cortex ended abruptly while they were active they come back CRASHED. Either way they must be started again.
  • Several sidebar items (Context, Resources, Events, Tools) and the account menu are visible but not functional. The Hooks and Behaviours screens open but are read-only: they show what hooks.json and behaviors.json define.

The full list is in the user guide.

Platform and prerequisites#

  • Windows x64 with the Microsoft Edge WebView2 runtime (the installer adds it when missing). Developed and tested on Windows 11; Windows 10 version 1809 or later is expected to work but is untested.
  • To build from source: Rust 1.89 or newer (the development machine uses x86_64-pc-windows-msvc) with the Tauri 2 Windows prerequisites, and Node.js with npm (20.19+ or 22.12+ to build the UI; the UI tests need a newer Node, see Installation).
  • At least one agent CLI installed and logged in as the Windows user that runs Cortex. None is needed to start Cortex.

Architecture#

A Rust workspace with strict layering, plus a React/TypeScript UI:

Part Role
crates/cortex-domain Entities, state machines, structured errors, ports
crates/cortex-application Cortex API: the single entry point of every surface
crates/cortex-infrastructure Config, data directory, instance lock, logs, process, PTY and storage implementations
crates/cortex-runtime-claude-code, -codex, -opencode Runtime adapters; only they know their CLI
crates/cortex-mcp MCP server (Streamable HTTP, OAuth 2.1 for remote clients)
crates/cortex-bootstrap Composition root: builds the Core and drives startup, ready, drain, stop
apps/desktop/src-tauri cortex-desktop: Tauri 2 host and IPC commands
apps/desktop/ui React UI; reaches the Core only through Tauri IPC
apps/landing, apps/commercial Public landing page (ADR 0007) and a Remotion video project; not part of the app
apps/docs Documentation site generated from this README and docs/*.md (ADR 0013); not part of the app

Details, lifecycle and the layering rules (checked by crates/cortex-bootstrap/tests/architecture.rs) are in Development and architecture.

Install#

Run Cortex_0.2.0_x64-setup.exe (per-user, no administrator rights; build it with npm run installer, see Release and packaging), or run from source with Start.bat (below). Prerequisites, the installer, configuration, data locations, troubleshooting and uninstall are in Installation.

Development setup and commands#

bat
cd apps\desktop\ui
npm ci
npm run build
cd ..\..\..
cargo build -p cortex-desktop
Command Directory What it does
Start.bat / Start.bat release repo root Installs UI dependencies if node_modules is missing, builds the UI, builds cortex-desktop (debug or release) and starts it
npm run build apps/desktop/ui tsc --noEmit then vite build into ui/dist; must exist before compiling cortex-desktop
cargo build -p cortex-desktop [--release] repo root Builds target\<profile>\cortex-desktop.exe (no installer)
npm run installer apps/desktop/ui Rebuilds the UI, builds the release host and packages target\release\bundle\nsis\Cortex_<version>_x64-setup.exe
cargo run -p cortex-desktop repo root Runs the host; needs apps/desktop/ui/dist
npm run dev apps/desktop/ui Vite only; the UI works only inside the Tauri host, so this alone shows nothing useful

Launching#

Run Start.bat (debug build, keeps a console window) or Start.bat release (no console window), or start target\debug\cortex-desktop.exe / target\release\cortex-desktop.exe directly after a build. The executable takes no arguments. The MCP server is hosted by the desktop app and runs only while the app is open.

Note

There is no cortex command-line tool. It is planned (see Planning/Plan.md) and not implemented; scripts and other tools can drive Cortex through its MCP server instead.

Tests and build#

Command What it covers
cargo test --workspace --exclude cortex-desktop Whole Rust suite without the UI build; tests that drive real CLIs are #[ignore]d
cargo test -p cortex-desktop Tauri commands on a mock runtime; needs apps/desktop/ui/dist
cargo test -p cortex-bootstrap --test architecture Crate layering checks
npm run typecheck and npm test in apps/desktop/ui tsc --noEmit and vitest run
cargo fmt --all --check and cargo clippy --workspace --all-targets -- -D warnings Style and lint, default settings

Opt-in tests against the real CLIs (cargo test -p cortex-bootstrap --test runtime|codex|opencode -- --ignored) need the CLI installed and logged in, and can spend model tokens. See Development and architecture for details. The only workflow is .github/workflows/windows-installer.yml. It runs on a v*.*.* tag or by hand, on a Windows runner: UI npm ci, npm run typecheck and npm test, UI build, cargo test --workspace --locked, then the NSIS installer build, its SHA-256 and a workflow artifact (30 days). It does not run cargo fmt, cargo clippy or cargo test on pushes or pull requests, and it publishes nothing.

Documentation#

  • Installation: prerequisites, building, configuration, data and logs, troubleshooting, cleanup
  • User guide: what the app does today, screens, workflows, limitations
  • Development and architecture: architecture, lifecycle, build and test
  • Command reference: command reference, the 32 MCP tools with parameters and results, and the actions of the window
  • Release and packaging: versioning, building the installer, signing and validation
  • Releases: the releases built so far (0.1.0, 0.2.0), with size and SHA-256
  • docs/adr/: design record, ADR 0001 to 0013 (Portuguese)
  • Planning/Plan.md and Planning/TODO.md: architecture and roadmap

Project status#

Current status, work packages and decisions are in Planning/TODO.md and Planning/Plan.md.

Whatever is not built yet is a plan, not a feature. The workspace declares UNLICENSED and publishes nothing.

Type to search.