cortex-md 1.1.1

package/README.md

@@ -0,0 +1,172 @@
+# Cortex — Personal AI Operating System
+
+[![GitHub Release](https://img.shields.io/github/v/release/angshuman/cortex?style=flat-square&label=Latest%20Release)](https://github.com/angshuman/cortex/releases/latest)
+[![Downloads](https://img.shields.io/github/downloads/angshuman/cortex/total?style=flat-square&label=Downloads)](https://github.com/angshuman/cortex/releases/latest)
+[![Build](https://img.shields.io/github/actions/workflow/status/angshuman/cortex/release.yml?style=flat-square&label=Build)](https://github.com/angshuman/cortex/actions)
+
+A local-first personal operating system with an AI reasoner, note-taking, task management, and browser automation via MCP. Built with Node.js, TypeScript, React, and Tailwind CSS.
+
+---
+
+## Download
+
+**[Go to the Releases page to download Cortex](https://github.com/angshuman/cortex/releases/latest)**
+
+### Latest Release
+
+| Platform | Architecture | Download |
+|----------|-------------|----------|
+| **Windows** | x64 / ARM64 | [Cortex-Setup.exe](https://github.com/angshuman/cortex/releases/latest/download/Cortex-Setup-1.1.1.exe) |
+| **macOS** | Apple Silicon | [Cortex-arm64.dmg](https://github.com/angshuman/cortex/releases/latest/download/Cortex-1.1.1-arm64.dmg) |
+| **macOS** | Intel | [Cortex.dmg](https://github.com/angshuman/cortex/releases/latest/download/Cortex-1.1.1.dmg) |
+| **Linux** | x64 | [Cortex.AppImage](https://github.com/angshuman/cortex/releases/latest/download/Cortex-1.1.1.AppImage) |
+| **Linux** | ARM64 | [Cortex-arm64.AppImage](https://github.com/angshuman/cortex/releases/latest/download/Cortex-1.1.1-arm64.AppImage) |
+| **Linux** | x64 (deb) | [cortex_amd64.deb](https://github.com/angshuman/cortex/releases/latest/download/cortex_1.1.1_amd64.deb) |
+| **Linux** | ARM64 (deb) | [cortex_arm64.deb](https://github.com/angshuman/cortex/releases/latest/download/cortex_1.1.1_arm64.deb) |
+
+> On first launch, a setup dialog asks for an API key (OpenAI, Anthropic, xAI, or Google Gemini). No environment variables needed.
+
+---
+
+## Features
+
+- **AI Chat & Reasoning** — Converse with Claude, OpenAI, Grok, or Gemini. The agent reasons through problems, creates notes, manages tasks, and uses tools.
+- **Notes** — Full markdown editor with image support (paste screenshots), folder hierarchy, inbox quick dump, and rendered preview.
+- **Tasks** — Pure no-AI task management with kanban and list views, subtasks, priorities, due dates, and status tracking.
+- **Search** — Unified search across notes, tasks, and chat history. Configurable for local keyword or OpenAI vector search.
+- **Skills System** — Extensible tools the AI agent can use. Built-in skills for note-taking, task management, web search, and browser automation.
+- **Browser Use (MCP)** — Connect a Playwright MCP server for real browser automation.
+- **Multi-Vault Workspaces** — Separate vaults for work, personal, etc. Each with its own notes, tasks, and chats.
+- **API Key Management** — Add, verify, and manage API keys from the UI. No env vars required.
+- **Local Filesystem** — All data stored as plain JSON and Markdown files. Human-readable, navigable, portable.
+- **Sync** — Point vault folders to OneDrive, Google Drive, USB, or any path for portability.
+- **Desktop App** — Native Electron app with system tray, single-instance lock, and platform menus.
+
+## Data Structure
+
+```
+.cortex-data/
+├── vaults/
+│   ├── personal/
+│   │   ├── notes/          # Markdown files + index
+│   │   ├── tasks/          # tasks.json
+│   │   ├── chat/           # Session files
+│   │   ├── skills/         # Skill definitions
+│   │   └── files/          # Uploaded assets
+│   └── work/
+│       └── ...
+├── vaults.json             # Vault registry
+└── config.json             # Global settings + API keys
+```
+
+## Quick Start (Development)
+
+```bash
+git clone https://github.com/angshuman/cortex.git
+cd cortex
+npm install
+npm run dev
+```
+
+Open [http://localhost:5000](http://localhost:5000) — the API key setup dialog will appear on first launch.
+
+You can also set keys via environment variables:
+
+```bash
+# macOS / Linux / Git Bash
+export OPENAI_API_KEY=sk-...
+
+# Windows PowerShell
+$env:OPENAI_API_KEY = "sk-..."
+```
+
+> **Tip:** Create a `.env` file in the project root for persistent config:
+> ```
+> OPENAI_API_KEY=sk-...
+> CORTEX_DATA_DIR=C:\Users\you\OneDrive\cortex-data
+> ```
+
+## Electron Desktop App
+
+```bash
+# Dev mode — build + launch
+npm run electron:dev
+
+# Package for your platform
+npm run electron:pack:win     # Windows .exe installer
+npm run electron:pack:mac     # macOS .dmg
+npm run electron:pack:linux   # Linux .AppImage + .deb
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `ANTHROPIC_API_KEY` | Claude API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `GROK_API_KEY` | Grok/xAI API key |
+| `GOOGLE_API_KEY` | Google Gemini API key |
+| `CORTEX_DATA_DIR` | Custom data directory (default: `.cortex-data/`) |
+
+### Settings UI
+
+- **API Keys** — Add, verify, and manage provider keys from Settings > General.
+- **AI Provider** — Auto-detected from first configured key. Override model per-vault.
+- **Vector Search** — Local keyword or OpenAI embeddings.
+- **MCP Servers** — Add Playwright or custom MCP servers for extended capabilities.
+- **Agent Tuning** — Max turns, temperature, token limits, custom system prompt.
+- **Data Directory** — Shown in settings. Sync vault folders for portability.
+
+## Skills
+
+Built-in skills (always available):
+
+| Skill | Tools | Description |
+|---|---|---|
+| **note-taker** | `create_note`, `read_note`, `list_notes`, `update_note` | Manage notes |
+| **task-manager** | `create_task`, `list_tasks`, `update_task`, `complete_task` | Manage tasks |
+| **web-search** | `web_search` | Search the web |
+| **browser-use** | `browser_navigate`, `browser_screenshot`, `browser_click`, `browser_type`, `browser_snapshot` | Browser automation via MCP |
+
+Add custom skills via the Skills JSON in your vault's `skills/skills.json`.
+
+## Tech Stack
+
+- **Backend**: Express + TypeScript, filesystem storage, WebSocket for real-time chat
+- **Frontend**: React + Vite + Tailwind CSS + shadcn/ui
+- **Desktop**: Electron with system tray and native menus
+- **AI**: Anthropic SDK, OpenAI SDK (also used for Grok and Gemini via compatible API)
+- **Markdown**: `marked` for rendering
+- **Icons**: `lucide-react`
+- **Build**: Vite (client) + esbuild (server + Electron) + electron-builder (packaging)
+- **CI/CD**: GitHub Actions — auto-builds Windows/macOS/Linux on tag push
+
+## Architecture
+
+- No database — everything is JSON/Markdown files on disk
+- AI agent has a reasoning loop with tool use (configurable depth per message)
+- WebSocket streams agent events (thoughts, tool calls, results, messages) to the UI
+- Skills define tools the agent can invoke, with parameters and instructions
+- MCP browser support is built into the skill system
+- Electron wraps the Express server + React client into a native desktop app
+
+## Code Signing
+
+The binaries are currently unsigned. To enable code signing, add these GitHub repository secrets:
+
+**Windows:**
+- `WIN_CERT_P12_BASE64` — Base64-encoded .p12 certificate
+- `WIN_CERT_PASSWORD` — Certificate password
+
+**macOS:**
+- `MAC_CERT_P12_BASE64` — Base64-encoded Developer ID Application .p12
+- `MAC_CERT_PASSWORD` — Certificate password
+- `APPLE_ID` — Apple ID for notarization
+- `APPLE_APP_SPECIFIC_PASSWORD` — App-specific password
+- `APPLE_TEAM_ID` — Apple Developer Team ID
+
+## License
+
+MIT

package/bin/cortex.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const electronPath = require('electron');
+const mainPath = path.join(__dirname, '..', 'dist', 'electron', 'main.cjs');
+
+const child = spawn(electronPath, [mainPath], {
+  stdio: 'inherit',
+  windowsHide: false,
+});
+
+child.on('close', (code) => process.exit(code ?? 0));

package/dist/electron/main.cjs

@@ -0,0 +1,302 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// electron/main.ts
+var import_electron = require("electron");
+var import_path = __toESM(require("path"), 1);
+var import_net = __toESM(require("net"), 1);
+var gotLock = import_electron.app.requestSingleInstanceLock();
+if (!gotLock) {
+  import_electron.app.quit();
+}
+var mainWindow = null;
+var tray = null;
+var serverPort = 0;
+function getDataDir() {
+  if (process.env.CORTEX_DATA_DIR) {
+    return process.env.CORTEX_DATA_DIR;
+  }
+  return import_path.default.join(import_electron.app.getPath("userData"), ".cortex-data");
+}
+function findAvailablePort() {
+  return new Promise((resolve, reject) => {
+    const srv = import_net.default.createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      if (addr && typeof addr !== "string") {
+        const port = addr.port;
+        srv.close(() => resolve(port));
+      } else {
+        reject(new Error("Could not find available port"));
+      }
+    });
+    srv.on("error", reject);
+  });
+}
+async function startServer(port) {
+  process.env.NODE_ENV = "production";
+  process.env.PORT = String(port);
+  process.env.CORTEX_DATA_DIR = getDataDir();
+  process.env.ELECTRON = "1";
+  const serverPath = import_electron.app.isPackaged ? import_path.default.join(process.resourcesPath, "server", "index.cjs") : import_path.default.join(__dirname, "..", "index.cjs");
+  return new Promise((resolve, reject) => {
+    try {
+      console.log(`[Cortex] Loading server from: ${serverPath}`);
+      require(serverPath);
+      console.log("[Cortex] Server module loaded, waiting for port...");
+      let attempts = 0;
+      const maxAttempts = 300;
+      const check = setInterval(() => {
+        attempts++;
+        const testConn = import_net.default.createConnection({ port, host: "127.0.0.1" }, () => {
+          testConn.end();
+          clearInterval(check);
+          resolve();
+        });
+        testConn.on("error", () => {
+          if (attempts >= maxAttempts) {
+            clearInterval(check);
+            reject(new Error("Server did not start within 30 seconds"));
+          }
+        });
+      }, 100);
+    } catch (err) {
+      console.error("[Cortex] Failed to load server module:", err);
+      reject(err);
+    }
+  });
+}
+function createWindow() {
+  mainWindow = new import_electron.BrowserWindow({
+    width: 1280,
+    height: 800,
+    minWidth: 900,
+    minHeight: 600,
+    title: "Cortex",
+    icon: getIconPath(),
+    backgroundColor: "#0e1117",
+    show: false,
+    webPreferences: {
+      preload: import_path.default.join(__dirname, "preload.cjs"),
+      nodeIntegration: false,
+      contextIsolation: true,
+      spellcheck: true
+    }
+  });
+  mainWindow.loadURL(`http://127.0.0.1:${serverPort}`);
+  mainWindow.once("ready-to-show", () => {
+    mainWindow?.show();
+  });
+  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+    if (url.startsWith("http://127.0.0.1") || url.startsWith("http://localhost")) {
+      return { action: "allow" };
+    }
+    import_electron.shell.openExternal(url);
+    return { action: "deny" };
+  });
+  mainWindow.on("close", (event) => {
+    if (process.platform === "darwin" && tray) {
+      event.preventDefault();
+      mainWindow?.hide();
+    }
+  });
+  mainWindow.on("closed", () => {
+    mainWindow = null;
+  });
+}
+function getIconPath() {
+  if (import_electron.app.isPackaged) {
+    return import_path.default.join(process.resourcesPath, "icons", "icon.png");
+  }
+  const iconPath = import_path.default.join(__dirname, "..", "..", "electron", "icons", "icon.png");
+  return iconPath;
+}
+function createTray() {
+  const iconPath = getIconPath();
+  let trayIcon;
+  try {
+    trayIcon = import_electron.nativeImage.createFromPath(iconPath);
+    if (trayIcon.isEmpty()) {
+      trayIcon = import_electron.nativeImage.createEmpty();
+    }
+  } catch {
+    trayIcon = import_electron.nativeImage.createEmpty();
+  }
+  if (!trayIcon.isEmpty()) {
+    trayIcon = trayIcon.resize({ width: 16, height: 16 });
+  }
+  tray = new import_electron.Tray(trayIcon);
+  tray.setToolTip("Cortex");
+  const contextMenu = import_electron.Menu.buildFromTemplate([
+    {
+      label: "Open Cortex",
+      click: () => {
+        if (mainWindow) {
+          mainWindow.show();
+          mainWindow.focus();
+        } else {
+          createWindow();
+        }
+      }
+    },
+    { type: "separator" },
+    {
+      label: `Data: ${getDataDir()}`,
+      enabled: false
+    },
+    {
+      label: "Open Data Folder",
+      click: () => {
+        import_electron.shell.openPath(getDataDir());
+      }
+    },
+    { type: "separator" },
+    {
+      label: "Quit Cortex",
+      click: () => {
+        import_electron.app.quit();
+      }
+    }
+  ]);
+  tray.setContextMenu(contextMenu);
+  tray.on("double-click", () => {
+    if (mainWindow) {
+      mainWindow.show();
+      mainWindow.focus();
+    }
+  });
+}
+function setupMenu() {
+  const template = [
+    {
+      label: import_electron.app.name,
+      submenu: [
+        { role: "about" },
+        { type: "separator" },
+        {
+          label: "Open Data Folder",
+          click: () => import_electron.shell.openPath(getDataDir())
+        },
+        { type: "separator" },
+        { role: "hide" },
+        { role: "hideOthers" },
+        { role: "unhide" },
+        { type: "separator" },
+        { role: "quit" }
+      ]
+    },
+    {
+      label: "Edit",
+      submenu: [
+        { role: "undo" },
+        { role: "redo" },
+        { type: "separator" },
+        { role: "cut" },
+        { role: "copy" },
+        { role: "paste" },
+        { role: "selectAll" }
+      ]
+    },
+    {
+      label: "View",
+      submenu: [
+        { role: "reload" },
+        { role: "forceReload" },
+        { role: "toggleDevTools" },
+        { type: "separator" },
+        { role: "resetZoom" },
+        { role: "zoomIn" },
+        { role: "zoomOut" },
+        { type: "separator" },
+        { role: "togglefullscreen" }
+      ]
+    },
+    {
+      label: "Window",
+      submenu: [
+        { role: "minimize" },
+        { role: "zoom" },
+        { type: "separator" },
+        { role: "front" }
+      ]
+    }
+  ];
+  import_electron.Menu.setApplicationMenu(import_electron.Menu.buildFromTemplate(template));
+}
+import_electron.app.on("ready", async () => {
+  import_electron.ipcMain.handle("open-folder", async (_event, folderPath) => {
+    if (folderPath && typeof folderPath === "string") {
+      return import_electron.shell.openPath(folderPath);
+    }
+    return "Invalid path";
+  });
+  try {
+    serverPort = await findAvailablePort();
+    console.log(`[Cortex] Starting server on port ${serverPort}...`);
+    console.log(`[Cortex] Data directory: ${getDataDir()}`);
+    await startServer(serverPort);
+    console.log(`[Cortex] Server ready at http://127.0.0.1:${serverPort}`);
+    setupMenu();
+    createTray();
+    createWindow();
+  } catch (err) {
+    console.error("[Cortex] Failed to start:", err);
+    import_electron.dialog.showErrorBox(
+      "Cortex failed to start",
+      `Error: ${err instanceof Error ? err.message : String(err)}
+
+Please check your configuration and try again.`
+    );
+    import_electron.app.quit();
+  }
+});
+import_electron.app.on("second-instance", () => {
+  if (mainWindow) {
+    if (mainWindow.isMinimized()) mainWindow.restore();
+    mainWindow.show();
+    mainWindow.focus();
+  }
+});
+import_electron.app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") {
+    import_electron.app.quit();
+  }
+});
+import_electron.app.on("activate", () => {
+  if (mainWindow === null) {
+    createWindow();
+  } else {
+    mainWindow.show();
+  }
+});
+import_electron.app.on("before-quit", () => {
+  if (mainWindow) {
+    mainWindow.removeAllListeners("close");
+    mainWindow.close();
+  }
+  if (tray) {
+    tray.destroy();
+    tray = null;
+  }
+});

package/dist/electron/preload.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+// electron/preload.ts
+var import_electron = require("electron");
+import_electron.contextBridge.exposeInMainWorld("cortexDesktop", {
+  platform: process.platform,
+  isElectron: true,
+  versions: {
+    electron: process.versions.electron,
+    node: process.versions.node,
+    chrome: process.versions.chrome
+  },
+  /** Open a folder in the native file manager (Explorer / Finder) */
+  openFolder: (folderPath) => import_electron.ipcRenderer.invoke("open-folder", folderPath)
+});

package/dist/icons/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="108" fill="#111318"/>
+  <g fill="none" stroke="#e5e7eb" stroke-linecap="round" stroke-linejoin="round">
+    <!-- C arc -->
+    <path d="M 320,126 C 270,90 210,80 165,100 C 100,128 66,190 66,256 C 66,322 100,384 165,412 C 210,432 270,422 320,386" stroke-width="36"/>
+    <!-- Three connector lines from the C opening -->
+    <line x1="320" y1="126" x2="380" y2="126" stroke-width="28"/>
+    <line x1="345" y1="256" x2="405" y2="256" stroke-width="28"/>
+    <line x1="320" y1="386" x2="380" y2="386" stroke-width="28"/>
+  </g>
+  <!-- Terminal dots -->
+  <circle cx="388" cy="126" r="18" fill="#e5e7eb"/>
+  <circle cx="413" cy="256" r="18" fill="#e5e7eb"/>
+  <circle cx="388" cy="386" r="18" fill="#e5e7eb"/>
+</svg>