From d45a79a482f285192bd800ef429444c3ea7e6278 Mon Sep 17 00:00:00 2001 From: echobt <154886644+echobt@users.noreply.github.com> Date: Thu, 8 Oct 2026 02:56:59 +0000 Subject: [PATCH 1/4] docs: alpha README, docs index, getting started, FAQ and issue templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 35 ++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 21 +++ CONTRIBUTING.md | 4 +- README.md | 184 +++++++++++++++------ SECURITY.md | 2 + docs/README.md | 27 +++ docs/assets/banner-crop.png | Bin 0 -> 45848 bytes docs/assets/banner.png | Bin 0 -> 89152 bytes docs/configuration.md | 33 ++++ docs/connection-modes.md | 2 +- docs/faq.md | 24 +++ docs/getting-started.md | 49 ++++++ docs/troubleshooting.md | 22 +++ 14 files changed, 350 insertions(+), 54 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 docs/README.md create mode 100644 docs/assets/banner-crop.png create mode 100644 docs/assets/banner.png create mode 100644 docs/configuration.md create mode 100644 docs/faq.md create mode 100644 docs/getting-started.md create mode 100644 docs/troubleshooting.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..c8864445 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,35 @@ +name: Bug report +description: Something is broken in Cortex Desktop (alpha) +labels: [bug] +body: + - type: markdown + attributes: + value: | + Cortex Desktop is alpha software. Never paste API keys, tokens, cookies or private paths. Report security issues privately, see SECURITY.md. + - type: textarea + id: what + attributes: + label: What happened? + description: What you did, what you expected, what you saw. + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + validations: + required: true + - type: input + id: version + attributes: + label: Commit or version + placeholder: git rev-parse --short HEAD + validations: + required: true + - type: input + id: os + attributes: + label: OS and architecture + placeholder: macOS 26, arm64 + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3ba13e0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..f2df5e6d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,21 @@ +name: Feature request +description: Suggest an improvement +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What are you trying to do, and what gets in the way? + validations: + required: true + - type: textarea + id: idea + attributes: + label: Proposed solution + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c073626f..63682873 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Cortex -Bun workspaces monorepo; Electron 44 desktop app; React 19 renderer; local engine in main. +Cortex Desktop is alpha software. It's a Bun workspaces monorepo: Electron 44 desktop app, React 19 renderer (Base UI, Vite 8), local engine in main. Setup and docs: [docs/README.md](./docs/README.md). Read [AGENTS.md](./AGENTS.md) and [`.rules/`](./.rules/) first. Keep changes small, typed, and tested. @@ -73,4 +73,4 @@ issues, PRs or logs. ## Questions -GitHub Issues for bugs; Discussions for design questions when enabled. +Use [GitHub Issues](https://github.com/CortexLM/desktop/issues) with the bug and feature templates. Source copy is English; other locales come from `node scripts/translate-locales.mjs`. diff --git a/README.md b/README.md index 8d7b0f6f..73e0641b 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,121 @@ -# Cortex +
+
+
A desktop app for Chat, Work, Bots and Code, with an agent engine that runs on your machine.
+ -Cortex desktop: Chat, Work, Bots, Files and Cortex Code on a local agent engine. +> [!WARNING] +> **Alpha software.** Cortex Desktop is not recommended for production use. Features can change or break between commits, nothing is guaranteed to be stable, and builds are **unsigned** (no code signing, no notarization). Back up anything you care about and expect rough edges. -One Electron 44 app. The engine runs inside the app's main process, stores sessions and -settings in local SQLite (`node:sqlite`), and talks to the model providers you configure. -Provider keys use a separate main-process credential store. No account is needed. -Cortex Cloud (`cortex.foundation`) and self-hosted settings save a preference, probe servers -and support email-code sign-in through main. Sign-in lasts until Cortex closes; prompts -still use the local engine and configured providers. +--- -## Quick start +## What is Cortex Desktop? + +Cortex Desktop is one Electron app. The agent engine runs inside the app's main process, keeps sessions and settings in local SQLite (`node:sqlite`), and talks to the model providers you configure. Provider keys sit in a separate credential store in the main process and never reach the renderer. You don't need an account to use it. + +If you'd rather use Cortex Cloud, you can sign in with an email code from Settings. Signed-in screens (Bots, Work, remote Chat and Code) talk to the Cortex Cloud account, and everything else stays local. + +## Features + +What works today (see [Status](#status) for the exact boundaries): + +- **Chat** on the local engine, streaming, with reasoning and image input for models that support them. +- **Work** tasks and approvals. +- **Bots** with mascots and an iMessage-style conversation: bubbles only, typing dots while a Bot works. These screens need a Cortex Cloud sign-in. +- **Cortex Code** on a local folder. +- **Providers and models** from the public [models.dev](https://models.dev) catalog (Anthropic, OpenAI, Google and OpenAI-compatible endpoints). +- **MCP servers**, skills (a `summarize` skill ships in [`skills/`](./skills)) and optional [computer use](./docs/computer-use.md). +- **Eight locales** (`en fr es de ja zh-Hans pt-BR ko`), English by default, dark and light themes. + +## Status + +- Live: Chat, Work tasks and approvals, Bots, Cortex Code on a local folder, Settings, Providers and models, connection selection with probing and email-code sign-in. +- Preview only: file viewers and other screens without engine wiring (open `#/gallery` in a preview build). +- Not built yet (waiting on design): Space, Scheduled, Plugins and skills, extra sign-in continuation screens. Remote prompt routing is pending. +- Sign-in lasts until Cortex closes. Prompts still use the local engine and the providers you configured. +- Acceptance is incomplete: see [evidence/STATUS.md](./evidence/STATUS.md). +- The banner above is a real macOS window of the app (Electron 44, dark theme, English). The Bot thread is live code, but the screenshot feeds it demo data (a made-up Bot named Nova and fake messages) instead of a real Cortex Cloud account, so no personal data appears. + +## Install + +There are no signed releases yet. Build from source. + +You need [Bun](https://bun.sh) 1.4 and Node 22 or newer. ```bash +git clone https://github.com/CortexLM/desktop.git +cd desktop bun install node node_modules/electron/install.js # Bun skips Electron's postinstall bun run build -bun run start # headless Linux: DISPLAY=:1 bun run start -- --no-sandbox +bun run start ``` -Then Settings → Providers & models: pick a provider, paste your key. +On headless Linux use `DISPLAY=:1 bun run start -- --no-sandbox`. -Renderer-only loop in a browser: +### Unsigned packages ```bash -bun run dev:api # engine on :5298, in-memory keys -bun run dev:app # Vite on :5299, proxies /api +bun run pack # unpacked app in dist/, current platform +bun run dist:mac # macOS dmg and zip (x64 and arm64) ``` -## Layout +`electron-builder.yml` also defines Windows (NSIS installer and portable, x64) and Linux (AppImage and deb, x64) targets. CI builds unsigned packages only. -``` -packages/ - schema/ zod contracts (browser-safe) - core/ local engine: storage, bus, catalog, providers, sessions, tools, - permissions, agents, skills, plugins, MCP, bots, scheduler, space, - connection, computer use - protocol/ Hono route table + validation - server/ createServer(core) → app.fetch - client/ typed fetch client + SSE parser - i18n/ catalogs (locales/A$fq^w!D7M$&Dp
zu|44-f;Zmnzq&M6yE@ JH!zo~91#_X
zNd3+{Akp0d4X5wCjWIY*C7#26Fb-|jbs6EhIywaL8njGA@jEBxVMRyqI^Zb?>I?eh
z$k5DheO*RJ3_%}9F{WmL8i02zkEzc`@CCCHO*J8YeljmH+{CfJ^2Eu8c_R3RsrhT$
zAk&4Qro0iRRf-}aIbqx^L0j`8c<2bpBX~swU%BiLyYiB@55NXMlnDBF5+f$EU&(V_
z2Ohe098Y1eFib}XZXN9{Es?k1B7;OJ3%UZPA{Rj{SJo|(f#&0pBipJ}At-$K@cPWI
z8_pjf=zIv#EPGAY?06SCYAAx_9DDAir-OXar?!4i5cyv)$Q&vQTb{rg?N>pHLVJg+ln&!Qqd1$sjl
zGf1joDv?m~AyJ>Vw<|9=xS8J>xFu>XuvBrN^K&m8$S?p#0n$Db3(K~CC21u1p`oG3
z%8{=
zVNhwWRr2ks{t>CZ{~@%9!;FH&B(x09>yxwTp=X1D7K
z3viT;>3Jm`vi~i8;MtGZI}$bqjmJMi-O>Aa`j8kKZgX}V{xBs-Rd6@|m&W(ZB}9uXA05k33uQpjrqA9F@Uj2S$x<*j*4
zm&}J4Ki7CA54QcYJI&