cortex

A local task tracker for one engineer supervising several AI coding agents at once.

Your agents post progress, status changes and plans to cortex from the command line. You watch it all live in the desktop app, and cortex interrupts you only when an agent is blocked. Tasks double as memory, so the next agent session picks up where the last one stopped.

• One binary. The CLI and a small background daemon; plain cortex opens the desktop app.
• Local and private. One SQLite file under ~/.config/cortex, a private Unix socket, no network listener, no accounts.
• Live. A change from any agent shows up in every app window at once.
• Made for agents. Stable --json output, updates credited to each agent session, and skills, a pi extension and a bb plugin that teach agents the conventions.

Install

On macOS or Linux:

curl -fsSL https://github.com/kalindudc/cortex/releases/latest/download/install.sh | sh
cortex init            # create your database
cortex agents install  # teach your agents: skills, plus pi and bb support if you use them

Then run cortex to open the app. The script installs the cortex CLI into ~/.local/bin and the desktop app of the same version: into /Applications on macOS, with apt on Debian and Ubuntu, and as an AppImage in ~/Applications elsewhere. It checks every file against the release's checksums first. Set CORTEX_VERSION for another version, CORTEX_BIN_DIR for another folder, CORTEX_NO_APP=1 for the CLI alone or CORTEX_NO_CLI=1 for the app alone. Run it again to upgrade; it also restarts the cortex daemon on the new version.

With Homebrew, on macOS or Linux, tap first (Homebrew installs only from taps you have added) and use the full name, because Homebrew's own cortex is an unrelated project:

brew tap kalindudc/tap
brew install kalindudc/tap/cortex
curl -fsSL https://github.com/kalindudc/cortex/releases/latest/download/install.sh | CORTEX_NO_CLI=1 sh  # the app

To upgrade, run brew upgrade kalindudc/tap/cortex, then the app line again; it also restarts the daemon (without the app, run cortex stop). Every package is also on the releases page, for example a deb for sudo apt install ./Cortex-<version>-linux-amd64.deb. The macOS app is not signed by Apple yet, so a dmg downloaded in a browser opens only after Open Anyway in System Settings, under Privacy & Security.

Quick start

cortex add "ship the login page" -p 0                             # a task; priority 0 is the highest
cortex update 1 -m "tests pass" -s review --as my-agent-1a2b3c4d  # what an agent posts
cortex                                                            # watch it in the desktop app

A task moves through draft, open, review, blocked and done. Only a move into blocked raises a notification.

_{Left: everything the agents posted on a task, and the Inbox of status changes. Right: a task's Markdown beside its preview.}

Learn more

• The desktop app: reading, editing and triaging tasks, and how the app is built.
• Agent memory: how agents keep and find their working state, with or without pi.
• Cortex in bb: each thread's task beside the conversation, and memory tools for every provider.
• How cortex works: the daemon, where your data lives, and what happens when agents collide.
• cortex --help, cortex schema and cortex doctor: every command, the data model for agents, and a health check.

Development

You need Node.js and pnpm; Bun comes in as a dev dependency. After pnpm install --frozen-lockfile, pnpm run desktop:dev and pnpm run dev -- <command> run cortex from source on a sandbox in tmp/dev/, so unreleased code never touches your real data. pnpm run desktop:dist packages the desktop app, and pnpm run deploy installs your build into ~/bin (keep it on your PATH) through the same install script users run. AGENTS.md has the commands, tests, conventions and the checks to run before a PR.