🧠 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

# 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:

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:

# 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.

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.

Security

Found a vulnerability? Do not open a public issue — email [email protected]. Scope, response targets, and safe harbor: SECURITY.md.

Requirements

• Node.js 20.11+ (< 25)
• 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 · 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.