# 🧠 Genius Cortex **Multi-repo orchestration for vibe coders.** Your AI coding toolkit manages one project at a time. Cortex manages all of them. ## What it does - **See all your projects** β€” versions, health scores, last activity - **Shared behaviors** β€” coding habits that follow you everywhere ("prove before fix", "post-fix audit") - **Cross-project memory** β€” knowledge captured in one project, available in all - **Project factory** β€” new project in 30 seconds (template β†’ GitHub β†’ GT installed β†’ Claude launched) - **Secrets vault** β€” encrypted API keys, injected per-project - **AI tool watch** β€” Claude Code updated? Cortex tells you. ## Install ```bash # One-liner (recommended) bash <(curl -fsSL https://raw.githubusercontent.com/w-3-art/genius-cortex/main/install.sh) # Or manual git clone https://github.com/w-3-art/genius-cortex.git ~/.genius-cortex-cli cd ~/.genius-cortex-cli && npm install && npm link # Then initialize cortex init ``` ## Uninstall Cortex ships a command that reverses its in-place edits for you: ```bash cortex uninstall # detach from Claude Code, keep your data + vault cortex uninstall --purge-data # ALSO delete ~/.genius-cortex β€” ⚠️ destroys the vault (asks first) ``` `cortex uninstall` removes, non-destructively (each edited file is backed up to a `.bak-*` sibling first): - the `"genius-cortex"` entry under `mcpServers` in `~/.claude.json` β€” your other MCP servers are left untouched; - the Cortex-managed blocks in `~/.claude/CLAUDE.md` (behaviors / rules / `cortex:start…cortex:end`) β€” the rest of your file is preserved; - the Cortex `SessionStart` hook in `~/.claude/settings.json`, so it no longer fires against deleted files. It never deletes the desktop app or the npm package (they are outside its reach), and it only purges `~/.genius-cortex` β€” which holds your **encrypted vault of secrets**, loops, signals, memory and config β€” when you pass `--purge-data` and confirm. After running it, finish up by hand with the steps it prints: ```bash # 1. Remove the CLI npm rm -g genius-cortex # if installed via the one-liner (global npm) # or, for the manual/dev install: cd ~/.genius-cortex-cli && npm unlink -g && cd .. && rm -rf ~/.genius-cortex-cli # 2. Remove the desktop app (macOS) rm -rf "/Applications/Genius Cortex.app" # 3. If you did NOT use --purge-data and want a clean slate β€” ⚠️ DESTROYS the vault rm -rf ~/.genius-cortex ``` ## Commands ``` cortex init β€” Set up Cortex (scan repos, install behaviors) cortex scan β€” Find Genius Team repos cortex status β€” See all projects + versions cortex upgrade β€” Update GT in your repos cortex behaviors β€” Manage coding behaviors (7 starters included) cortex rules β€” Rules you NEVER break (enforced via CC hooks) cortex memory β€” Cross-project knowledge store cortex glossary β€” Shared vocabulary cortex personas β€” Client/project context profiles cortex templates β€” Project starters (SaaS, Landing, API, Mobile) cortex create β€” New project from template cortex vault β€” Encrypted secrets management cortex health β€” Project health scores (0-100) cortex search β€” Search code across all repos cortex codebits β€” Reusable code snippets cortex watch β€” AI tool news feed cortex sessions β€” Session history cortex inject β€” Push behaviors + rules into Claude Code cortex uninstall β€” Detach from Claude Code (optionally --purge-data) ``` ## Behaviors Cortex ships with 7 starter behaviors: | Behavior | What it does | |----------|-------------| | prove-before-fix | Never fix based on assumptions. Read β†’ Reproduce β†’ Identify β†’ Fix. | | post-fix-audit | After every fix: re-test, check regressions, review diff. | | verify-before-code | Read existing code before writing new code. | | no-rush-quality | Quality over speed. Always. | | cumulative-feedback | New feedback adds to previous. Never replaces. | | read-before-write | Read the file/tests/README before editing. | | minimal-change | Change only what needs to change. | Run `cortex behaviors --inject` to activate them in every Claude Code session. ## How it works Cortex writes to `~/.claude/CLAUDE.md` (user-level). Claude Code loads this file in every session, on every project. Your behaviors, rules, and glossary are always active. ## MCP server Cortex exposes 27 tools to Claude Code over stdio (`cortex mcp --start`), built on the official `@modelcontextprotocol/sdk` and targeting the **stable MCP spec `2025-11-25`**. Tool names and schemas are stable; clients configured against them keep working across upgrades. The `2026-07-28` RC (stateless core, extensions, tasks, MCP Apps) will be adopted after its release date without breaking the current tool contract. The 6 `cortex_loop_*` tools (register / heartbeat / report / kill / list / stats) are the loop control plane (LP-06/LP-07): every Genius Team loop registers here, heartbeats each iteration, obeys the kill switch, and reports cost-per-accepted-change for budget enforcement. The 2 `cortex_loop_signal_*` tools (emit / poll) are the inter-loop signal bus (LP-10) β€” what makes loops compose. A loop that hits something outside its own blast radius emits a typed signal `{id, sourceLoop, domain, kind, payload, ts, consumedBy[]}` with kind `finding | blocker | handoff | budget-alert`; loops that declared they listen to that domain (see the `## Signals` section of the CONTRACT.md template in genius-team's `genius-goal-contract`) poll it filtered by domain/repo, with dedupe β€” each signal is delivered at most once per consumer via `consumedBy`. Every emission and consumption lands in the append-only global log `~/.genius-cortex/loop-signals.jsonl`, browsable with `cortex loops --signals` (add `--json` for machines). Past a size/line threshold the log is compacted: `consumedBy` is a per-consumer dedupe advisory, never a suppression criterion, so a signal is never dropped just for having been consumed. Never-consumed signals are kept forever (a future loop may still pick them up) and the `CORTEX_SIGNALS_KEEP_RECENT` most recent signals (default 5000) are kept regardless of consumption. **Guarantee:** a consumer more than `KEEP_RECENT` signals behind may miss a signal that was already consumed by another consumer β€” raise `CORTEX_SIGNALS_KEEP_RECENT` if your loops can lag further. The Genius Store tools (`cortex_skill_list` / `_get` / `_route` / `_card`) enforce a supply-chain policy on every served skill: `cortex_skill_card` exposes owner-qualified provenance (`@owner/slug`), declared permissions, and a sha256 checksum over `SKILL.md` + references; a security lint flags hidden Unicode/bidi, exfiltration (`curl|sh`, secret leaks, reverse shells), crypto miners, and commission-fraud wallet swaps; and a quarantined skill stays listed but is refused by `cortex_skill_get` until vetted. Run `cortex doctor` for the audit and `cortex quarantine` to manage it. See [`docs/SKILL-SUPPLY-CHAIN.md`](docs/SKILL-SUPPLY-CHAIN.md). The vault never exposes secret values through any tool or API surface β€” only key *names* are listable β€” and `test/vault-no-leak.test.ts` (part of `npm test`) locks that contract. See the ecosystem-wide telemetry/privacy policy in [`docs/TELEMETRY-PRIVACY.md`](docs/TELEMETRY-PRIVACY.md). ## Security Found a vulnerability? Do not open a public issue β€” email **benjamin@w3art.io**. Scope, response targets, and safe harbor: [SECURITY.md](SECURITY.md). ## Requirements - Node.js 20.11+ (< 25) - [Genius Team](https://github.com/w-3-art/genius-team) installed on your projects - Claude Code (for hook integration) ## Claude Code compatibility Cortex behaviors and the Genius Store MCP tools attach to your Claude Code sessions, and `cortex watch` surfaces new Claude Code releases. This table is what those sessions run against β€” verified **2026-07-05** against official docs ([Claude Code CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) Β· [Models overview](https://docs.claude.com/en/docs/about-claude/models/overview); latest Claude Code 2.1.201). | Model | API ID | Context | Price in / out (per MTok) | |-------|--------|---------|---------------------------| | Opus 4.8 | `claude-opus-4-8` | 1M tokens | $5 / $25 | | Sonnet 5 | `claude-sonnet-5` | 1M tokens | $3 / $15 β€” intro **$2 / $10 through 2026-08-31** | | Fable 5 | `claude-fable-5` | 1M tokens | $10 / $50 | | Haiku 4.5 | `claude-haiku-4-5` | 200k tokens | $1 / $5 | - **Sonnet 5 is the default Claude Code model** (native 1M context) since Claude Code **2.1.197**. - **Tokenizer drift:** Sonnet 5 / Opus 4.8 / Fable 5 use the Opus-4.7 tokenizer β€” the same text produces **~30% more tokens** than pre-4.7 models (content-dependent). Factored into the `cortex_loop_*` cost-per-accepted-change budgets. - **Agents (Claude Code 2.1.198):** the `/agents` wizard was removed (manage subagents by asking Claude or editing `.claude/agents/` directly); background sessions fire `agent_needs_input` / `agent_completed` Notification hooks; worktree agents commit/push/open a draft PR on completion; team agents report `failed` to the lead. The loop control plane observes these lifecycle states. ## License MIT --- Built with Genius Team. Open source.