Cortex Documentation

1 Introduction

Cortex is an agentic AI IDE for Windows. It combines a native code editor (Monaco), a file explorer, an integrated terminal, and a multi-provider AI agent that can autonomously plan, search, edit, run, and verify code across your entire project.

Two principles define how Cortex is built:

• BYOK — Bring Your Own Key. Your prompts and code travel directly from your machine to the AI provider you choose. There is no Cortex proxy in the middle, and no token markup. You pay your provider directly at their prices.
• Local-first. API keys, chat history, project memory, and settings all live on your machine. The Cortex server handles only account, subscription, and three platform services (OCR fallback, embeddings, web search).

2 Installation & Sign-in

3 Quick Start — Your First Task

4 The Workspace

4.1 Editor

The editor is Monaco (the engine inside VS Code): syntax highlighting for all mainstream languages, multi-tab editing, minimap, and word wrap. When the agent edits a file that's open, the tab reloads automatically.

4.2 Sidebar & file search

The file explorer supports instant fuzzy file search — start typing to filter the tree; hovering a result shows its full path. Right-click for file operations.

4.3 Terminal

A real Windows terminal (ConPTY-based) runs inside the IDE — same environment the agent uses for its commands, so "it works in the agent but not for me" can't happen.

4.4 Diff viewer

Every agent edit produces a reviewable diff. Open the diff viewer from the edit card to see exactly what changed, side by side.

4.5 Keyboard shortcuts

5 The Chat Interface

The chat panel is where you and the agent collaborate. It renders far more than plain text:

• Thought cards — reasoning models (DeepSeek, MiMo, Claude, Grok, GLM…) stream their internal thinking into a collapsible card with a live word count. The final answer stays clean; expand the card when you want to see why.
• Tool cards — every file read, search, edit, and command appears as a card with a spinner while running and a real result count when done ("42 files", "7 matches"). Expand any card to see the details.
• Diff cards — edits show as before/after diffs with accept context, and clicking a file path opens it in the editor at the right line.
• Rich rendering — markdown tables render as real tables, Mermaid diagrams render as interactive cards (copy source, fullscreen viewer), and code blocks get syntax highlighting with a language tag, Copy button, and collapse control.
• Images in, images understood — paste or attach screenshots. Vision-capable models (Claude, GPT, Gemini, Grok, Kimi, and more) see the image itself through your own API key at no cost from Cortex. For models without vision (e.g. DeepSeek), an OCR fallback (subscription) extracts the text so they can still work with it.
• Persistence — chats survive IDE restarts, including tables, diagrams, and code blocks, and re-render in whichever theme is active.
• Stop button — interrupts the agent mid-turn, immediately.

6 Modes: Agent · Ask · Plan

Rule of thumb: Ask to understand → Plan to decide → Agent to execute.

7 Agent Tools Reference

These are the 13 core tools the agent can call. You'll see each one as a card in the chat when it runs.

8 The Agentic Loop

In Agent mode, Cortex doesn't answer in one shot — it works in turns, like a developer:

Agentic Loop Mode

For bigger autonomous runs, enable Agentic Loop Mode in Settings. It adds a formal cycle on top: the agent writes a plan, executes it, then an independent reviewer model (your strongest configured model) audits the changes — checking for missing tests, secrets in code, and incomplete work — before the loop is allowed to finish. Failed reviews send the agent back to fix the findings.

9 Permissions & Safety

9.1 The permission card

Reading is free — the agent can read, search, and analyze without interruptions. The first time it wants to write, edit, or delete, a permission card appears:

While the card waits, the agent doesn't time out — take your time. Read-only work can continue in the background.

9.2 Command safety

Terminal commands pass through a dedicated security layer: commands are classified (read-only vs. mutating vs. dangerous), paths are validated against the project boundary, and risky patterns require explicit approval. Search and file tools are scoped to the opened project folder — the agent cannot wander your disk.

9.3 Guardrails

• Turn limits and thinking budgets prevent infinite loops.
• A safety guard detects repeated failing actions and stops the pattern.
• Memory-pressure monitoring throttles the agent on low-RAM machines instead of freezing your session.

10 Models & API Keys (BYOK)

Keys go in Settings → Models & Providers. Each row has a Test button (live connection check), a Remove button, and an enable toggle controlling whether that provider's models appear in the chat dropdown. MiMo and DeepSeek are enabled by default; enable others after adding their keys. Keys are stored encrypted on your device (Windows Credential Manager + encrypted store) and never sent to Cortex servers.

10.1 MiMo key types — important

• tp-… — token-plan keys (prepaid token packages).
• sk-… — standard API-based pay-as-you-go keys.
• Both are supported. Note that MiMo's Singapore server accepts token-plan (tp-) keys only — Cortex detects your key type automatically, routes to the correct endpoint, and falls back from tp- to sk- if you've configured both.

10.2 Auto model & failover

• Auto (top of the dropdown) picks a sensible model for each request.
• Failover: if your active provider has an outage or quota problem mid-task, Cortex automatically retries on your next configured provider instead of failing the task.
• A ● dot next to a model means its provider key is configured and working.

10.3 Extended thinking

Reasoning-capable models (Claude, Grok, Gemini, GLM, DeepSeek, MiMo, Qwen) automatically get extended thinking enabled — their reasoning streams into the thought card instead of cluttering the answer.

11 Context Management

• Model-aware budgets. Cortex knows each model's real context window (up to 1M tokens on MiMo, DeepSeek, Claude, Gemini, Qwen) and derives file-read caps, tool-result caps, and history limits from it — no hardcoded guesswork.
• Conversation compaction. Long sessions are summarized in the background so the agent keeps the important facts without hitting the context ceiling.
• History restore. Reopening the IDE restores your recent conversation — the agent remembers what you were doing yesterday.
• Large-file protection. Reads are size-capped per model; the agent reads big files in ranges instead of flooding its own context.

12 Project Memory

Cortex keeps a persistent memory per project, so the agent remembers your conventions, architecture decisions, and gotchas across sessions.

• Where it lives: plain markdown files inside your project at <project>/.cortex/memory/, with an index file the agent loads at session start. It's your data — readable, editable, version-controllable.
• Global memory also exists for facts that apply to every project (your preferences, your style).
• Never uploaded. Memory stays on your machine. The Cortex server never receives it — same guarantee as your code and keys.
• Semantic recall: at the start of each task, relevant memories are found by meaning and injected as context.
• Consolidation: a background pass merges duplicates and prunes stale entries so memory stays sharp instead of bloating.

Manage everything in Settings → Memory: browse project/global scopes, edit or delete entries, see staleness indicators, run consolidation, and search your memories semantically.

13 Settings Reference

14 MCP Servers & Extensions

Cortex speaks MCP (Model Context Protocol) — the open standard for giving AI agents extra tools. Add an MCP server in Settings → MCP Servers and its tools become available to the agent alongside the built-ins (databases, issue trackers, design tools, whatever the server provides).

The plugin system extends the IDE itself — installed plugins are managed from Settings → Extensions.

15 Account & Subscription

LLM usage is always BYOK — the subscription never marks up tokens. $10/month (or $80/year) covers the three platform services that need server-side keys:

• OCR fallback — for models without native vision (e.g. DeepSeek), screenshots become usable text context. Vision-capable models see images directly through your own key — no subscription needed for that.
• Semantic search embeddings — your code and memories become searchable by meaning.
• Web search — current docs and answers from the live web.

• Payment: PayPal (USD) or Razorpay (INR). After every successful payment you receive a branded receipt email with the PDF tax invoice attached; invoices are also always available at Account → Plan.
• License: your subscription generates a license key the IDE validates automatically — nothing to type in.
• Cancel anytime — access continues to the end of the paid period.

16 Updates

• Cortex checks for new releases automatically and shows the current version on the download page and in Settings → About.
• Critical releases can be marked force update — the IDE will ask you to install before continuing, ensuring security fixes reach everyone.
• Each release ships with its SHA-256 checksum so you can verify the download.

17 Privacy & Security

Full details in the Privacy Policy.

18 Tips & Tricks

• "update your memory" — the highest-leverage habit in Cortex. Explicit memory beats automatic capture every time.
• Plan → Agent workflow — for anything multi-file, get a plan first, correct it in one round, then execute. Cheaper and better than letting the agent discover the design mid-flight.
• Paste errors raw — full tracebacks and console output beat your summary of them. The agent is good at logs.
• Ask by meaning — semantic search finds "where do we throttle API calls?" even when no code says "throttle".
• Request diagrams — "draw a mermaid sequence diagram of the login flow" renders an interactive diagram card, fullscreen-able and copyable.
• Use the todo checklist — for long tasks, watch the agent's live task list to see exactly where it is; if priorities change, say so and it re-plans.
• Interrupt early — if the thought card shows the agent heading the wrong way, hit Stop and redirect. Ten seconds of steering saves ten minutes of wrong work.
• Two providers > one — a second key means outages and quota limits fail over instead of stopping your work.
• Screenshots as specs — attach a UI screenshot and say "match this layout". Vision models see it directly; the OCR fallback covers non-vision models.
• Keep the dropdown lean — enable only providers you actually use; the model picker stays fast to navigate.
• Let it verify — after edits, ask "run the tests" in the same conversation. The agent sees the results and fixes failures with full context.

19 Troubleshooting

20 Antivirus & Performance

Like any developer tool — IDEs, compilers, git — Cortex performs many small file operations while you work. Some antivirus products scan each one in real time, which can make any IDE feel slower than it should. Most vendors (and tools like Visual Studio and JetBrains IDEs) recommend excluding developer directories from real-time scanning for the best experience.

Add these two paths (and, where the product supports it, the Cortex.exe process):

• C:\Program Files\Cortex — the application
• C:\Users\<you>\.cortex — Cortex's local workspace data

Is this safe? Yes — these folders contain only Cortex itself and your local workspace data. API keys are never stored in either location (they live encrypted in Windows Credential Manager), and Cortex's core source code is public on GitHub, so you can verify what it does.

21 Support

• Email [email protected] — include your Cortex version (Settings → About) and, for agent issues, the model you were using.
• Quick answers on pricing, BYOK, and privacy: the FAQ.