Get started

Installation

How to get Cortex running on a Windows machine, as the repository stands today (version 0.2.0). There are two ways: the Windows installer (Cortex_0.2.0_x64-setup.exe, built with npm run installer, see Release and packaging) or a source build started with Start.bat. For what the app does once running, see the user guide; for architecture, build internals and tests, see Development and architecture.

Supported systems and prerequisites#

Cortex is Windows only. Agent processes are launched through Job Objects and ConPTY, which exist only in the Windows build. The workspace still compiles on other systems with stubs, but starting an agent there fails with process.job_failed. No other platform is supported.

Developed and tested on Windows 11 x64 with the x86_64-pc-windows-msvc Rust toolchain. Windows 10 x64 version 1809 or later should work (the pseudoconsole of the terminal mode and the agent CLIs need 1809) but has not been tested. ARM64 is not built or tested.

Building and running from source#

From the repository root:

Start.bat

Start.bat does four things in order:

1. In apps\desktop\ui, runs npm install only if node_modules is missing, then npm run build (tsc --noEmit && vite build into apps\desktop\ui\dist).
2. Runs cargo build -p cortex-desktop.
3. Starts target\debug\cortex-desktop.exe. The console window stays open and shows startup errors.
4. Returns the exit code of the app; if a build step fails it prints Falhou. Veja a mensagem acima. ("Failed. See the message above.") and exits with 1.

Start.bat release builds with --release and starts target\release\cortex-desktop.exe, which has no console window. The script changes into its own directory, so it can be started from anywhere.

Manual equivalent:

cd apps\desktop\ui
npm ci
npm run build
cd ..\..\..
cargo build -p cortex-desktop --release
target\release\cortex-desktop.exe

The UI must be built before compiling cortex-desktop: Tauri embeds apps\desktop\ui\dist (frontendDist in tauri.conf.json) at compile time. cargo build (and Start.bat) produce an executable only; the installer comes from npm run installer (Release and packaging). cargo run -p cortex-desktop also works once ui\dist exists. npm run dev starts Vite only; the UI reaches the Core solely through Tauri IPC, so it does nothing useful outside the Tauri host.

Install with the Windows installer#

The installer is Cortex_0.2.0_x64-setup.exe, an NSIS setup for 64-bit Windows. Build it with npm run installer in apps\desktop\ui (output in target\release\bundle\nsis\); its size and SHA-256 are listed in Releases.

What the setup does:

• Installs for the current Windows user only and needs no administrator rights. The default folder is %LOCALAPPDATA%\Cortex; the directory page lets you pick another one.
• Copies two files there: cortex-desktop.exe and uninstall.exe. No configuration, credentials or sample data are installed; Cortex creates its data on first start.
• Adds a Start Menu shortcut "Cortex". The last page offers "Create desktop shortcut" and a box to run Cortex right away. A silent install (/S) always creates the desktop shortcut.
• Registers "Cortex" (version 0.2.0, publisher Cortex) in Settings → Apps → Installed apps, under HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Cortex.
• Installs the WebView2 runtime first if it is missing, by downloading Microsoft's bootstrapper.
• Asks you to close Cortex if it is running from the install folder.

Upgrading. Run the newer setup: it installs into the same folder and replaces cortex-desktop.exe. The data directory is not touched. If the same version is already installed, the setup first asks whether to reinstall or uninstall.

The setup's details pane lists every step it ran; leave the last page open and use "Show details" when a step fails. The setup does not write a log file.

First start: agent CLI setup#

The last page of the setup starts Cortex. On the first start of an installation with no agents, Cortex opens the Runtimes screen in setup mode instead of the Agents screen. The same screen stays in the sidebar (SYSTEM → Runtimes) for later checks, retries and manual steps.

For each runtime the screen shows what Cortex found: the executable, its version and whether the CLI says it is signed in. Cortex asks the CLI itself, with read-only commands and a timeout: claude --version and claude auth status --json, codex --version and codex login status, opencode --version and opencode providers list (OpenCode 2: opencode auth list --standalone --format json). Their answers are read for the version and the signed-in state only; they are never stored or logged.

Every runtime that is not installed has a checkbox, checked by default; uncheck the ones you do not want. Install selected runs, one after the other, the official installer of each checked CLI:

• Every installer runs for your Windows user only. Cortex never asks for administrator rights and never changes an execution policy. Should a tool's installer need elevation, Windows shows its own prompt, which you may decline.
• Installing accepts that tool's license terms (winget is run with --accept-package-agreements).
• A CLI that is already installed is kept as it is: Cortex never reinstalls, upgrades or downgrades it. One that is installed but does not answer is reported, not replaced. A runtime whose runtimes.<id>.executable is set in config.json is never installed over.
• Cortex installs no prerequisite. When winget or Node.js is missing, the row says so and shows the manual command and the vendor's documentation address instead.
• An installer may run for up to 20 minutes. Cancel ends the installer's whole process tree and skips the CLIs not reached yet; closing Cortex does the same.
• After each install Cortex checks the CLI again. It finds a new CLI without restarting, even when the installer added its folder to your PATH after Cortex started (see Environment variables).
• Each row ends as Installed, Already installed — kept, Failed (with the reason and what to do) or Cancelled. A failed or cancelled row can be installed again.
• Skip for now (or Continue after an install) leaves setup mode. Cortex records this in setup.json and does not open the screen on its own again.

Installing a CLI gives you no account, subscription, API credits or provider access. Sign in with each CLI's own login before its agents can work.

Launching#

After installing, start "Cortex" from the Start Menu (or the desktop shortcut). From a source build, start Start.bat, or run target\debug\cortex-desktop.exe / target\release\cortex-desktop.exe directly. The executable takes no arguments. No cortex command-line tool exists (planned as Session 13 in Planning\TODO.md, not implemented).

On start the Core creates the data directory and a default config.json, then the splash screen waits until the Core is READY. The MCP server runs inside this process and only while the window is open. Closing the window shuts the Core down and stops running agents; on the next start they are STOPPED and must be started again. Agents that were still active when Cortex ended abruptly (crash, process killed, or a shutdown that did not finish) come back CRASHED with recovery.cortex_restart.

To run a second, isolated instance, set CORTEX_DATA_DIR to another absolute directory and give that directory's config.json a different mcp.port (or 0), because the default port 47821 is held by the first instance. Start.bat contains a commented set CORTEX_DATA_DIR=... line for this.

Configuration#

config.json lives in the data directory. It is created with defaults on first start, has no UI, and is read once at startup: edit it with Cortex closed, then start Cortex again. Only schema_version (must be 1) is required; any key you omit keeps its default. Unknown keys are rejected, and an invalid value stops the Core with config.invalid naming the field.

Example (backslashes must be doubled in JSON):

{
  "schema_version": 1,
  "logging": { "level": "debug" },
  "mcp": { "port": 47822 },
  "runtimes": {
    "claude-code": { "executable": "C:\\path\\to\\claude.exe" }
  }
}

Environment variables#

Data and log locations#

Default data directory: %LOCALAPPDATA%\Cortex, or CORTEX_DATA_DIR when set.

Sessions and agent output are never persisted: agent output (256 KiB per agent) and terminal bytes (1 MiB) live in memory only.

Logs are one JSON object per line (ts, level, module, event, correlation_id, fields). cortex.log rotates at logging.max_file_bytes into cortex.1.log, cortex.2.log, and so on, keeping logging.max_files files. Secrets appear as [REDACTED]. Useful events: core.starting, config.loaded, mcp.started, mcp.start_failed, api.command_failed, runtime.shutdown_incomplete, runtime.contract_unsupported. An error shown in the window carries a correlation id: search the log for it. Startup errors that happen before the log opens are shown in the window and, in debug builds only, on the console; release builds have no console.

Agent CLI prerequisites and authentication#

Cortex never reads or stores the credentials of an agent CLI and never signs one in. Each CLI must be authenticated for the Windows user that runs Cortex. The adapters were verified against Claude Code 2.1.295, codex-cli 0.160.0, OpenCode 1.18.33 and OpenCode 2.0.31; the setup commands against Claude Code 2.1.301, codex-cli 0.162.1, OpenCode 1.19.0 and OpenCode 2.0.31.

"PATH" below is Cortex's own PATH followed by the machine's and the user's PATH as the registry holds them at each lookup (see Environment variables).

The window creates only Claude Code agents. Codex and OpenCode agents are created through the MCP create_agent tool and always run in structured mode. Structured agents cannot do anything that needs approval (Claude Code runs with --permission-prompts none, Codex with --sandbox read-only, OpenCode requests are rejected; OpenCode 2 then ends the turn itself, which Cortex reports as cancelled by OpenCode). Details: user guide and ADR 0003, 0006 and 0009.

Troubleshooting#

Uninstall and cleanup#

Installed with the setup. Close Cortex, then uninstall "Cortex" from Settings → Apps → Installed apps (or run uninstall.exe in the install folder). The uninstaller removes cortex-desktop.exe, uninstall.exe, the Start Menu and desktop shortcuts and the Settings entry. It keeps the Cortex data directory and everything in it. Its checkbox "Delete the application data" removes only %APPDATA%\dev.cortex.desktop and %LOCALAPPDATA%\dev.cortex.desktop (the WebView2 profile: browser cache), never %LOCALAPPDATA%\Cortex. To remove your Cortex data as well, delete the files in the table below after uninstalling.

Source build. A source build installs nothing: no registry entries, no services, no shortcuts. Cleanup means deleting folders. Close Cortex first (Task Manager should show no cortex-desktop.exe); closing the window stops running agents.

Cortex stores only the path of each project folder, so deleting the data directory never deletes your code. Credentials and settings of Claude Code, Codex and OpenCode belong to those CLIs and are not removed: log out or uninstall them with the CLI itself. Uninstalling Cortex also keeps the CLIs its Runtimes screen installed; remove them with their own tools (winget uninstall Anthropic.ClaudeCode, the uninstall steps in the Codex README, npm uninstall --global opencode-ai). Delete the data directory only when you accept losing the rows above; they cannot be recovered.