Install

Cortex is a single, dependency-free Node.js CLI (Node 18.17+).

npm install -g github:Phani3108/Cortex
cortex --version

Or run it once without installing: npx github:Phani3108/Cortex init. From a clone: npm install -g .

Quick start

cd your-repo
cortex init              # detects stack + tools, imports existing CLAUDE.md / AGENTS.md / …
$EDITOR .cortex/rules/project.md
cortex compile           # writes native files for every enabled tool
git add .cortex CLAUDE.md AGENTS.md .cursor .github && git commit -m "Add Cortex"

If init imported hand-written files, run cortex compile --force once so the generated versions replace the originals (your content now lives in .cortex/rules/imported-*.md).

The .cortex/ folder

.cortex/
  config.yaml          which tools to compile for, per-tool model, output options
  rules/
    project.md         always-on rules (## headings become categories)
    react.md           rules with scope: frontmatter apply only to matching paths
  skills/
    code-review.md     or code-review/SKILL.md — compiled to Agent Skills

Personal rules in ~/.cortex/rules/ and ~/.cortex/profile.yaml are merged into every project you compile.

Rules

Plain markdown. Every bullet under a ## heading is one rule; the heading is its category. Nested bullets and indented continuation lines stay with their parent rule, and a paragraph under a heading counts as one rule.

## Architecture
- Business logic lives in `src/services/`; route handlers stay thin
- Don't add a dependency without a one-line justification

## Safety
- ! Never commit secrets or `.env` files
- ! Validate external input at the boundary

A leading ! marks a rule critical: it is emphasised in every output and is the last thing dropped when a tool has a hard size limit. Duplicate rules across files are merged automatically.

Path-scoped rules

Add scope: frontmatter and the whole file applies only to matching paths. Cortex translates it into each tool’s native mechanism.

---
scope: ["src/**/*.tsx"]
description: React component conventions
---
## Components
- Keep components under 150 lines; extract hooks for state

Skills

Skills are on-demand playbooks (code review, release, incident triage). Write them as .cortex/skills/<name>.md or .cortex/skills/<name>/SKILL.md. Cortex emits the open Agent Skills format — only loaded when relevant, so they don’t cost tokens on every request.

---
name: code-review
description: Review a diff for correctness, security and maintainability before merge.
---
# Code review
1. Read the diff; list behaviour changes.
2. Check error handling, input validation and secrets.

Output locations: .claude/skills/ (Claude Code), .agents/skills/ (Codex, Cursor, Copilot, Gemini CLI, Antigravity, Windsurf/Devin Desktop), .kiro/skills/ (Kiro). cortex add skill tdd installs a bundled template.

config.yaml

version: 2
project:
  name: storefront
  language: TypeScript
  framework: Next.js
providers:
  claude: true
  codex: true                  # AGENTS.md
  cursor:
    enabled: true
    model: gpt-6.1-sol         # format for this model family
  copilot: true
  gemini: false
  windsurf: false
  kiro: false
  antigravity: false
  gemini-review: false         # .gemini/styleguide.md for PR reviews
  openai: false                # chatgpt-instructions.md export
output:
  agentsMd: shared             # shared | duplicate
  skills: true

Setting model: for a tool changes the formatting style: Claude models get XML sections, GPT models numbered lists, reasoning models compact constraints, Gemini context-first markdown, open-weights models explicit instructions.

Tools & files

Generated from the same table the CLI uses (src/engine/targets.js).

AGENTS.md sharing

Cursor, Copilot, Windsurf, Kiro and Antigravity all read AGENTS.md natively. Writing the same rules into their own files as well means every request carries them twice. With output.agentsMd: shared (the default, when AGENTS.md is enabled) those tools get their always-on rules from AGENTS.md, and Cortex only writes their path-scoped rules and skills. Claude Code and Gemini CLI always get their own file because they don’t read AGENTS.md when their own file exists. Set duplicate if a tool in your team has AGENTS.md reading turned off.

Ownership & safety

• Every generated file starts with a “Generated by Cortex” marker.
• A file without the marker (hand-written) is never overwritten without --force — compile skips it and exits 1 with instructions.
• A generated file someone edited since the last compile is also skipped (detected by content hash), so edits are never lost silently. Move the edit into .cortex/ or use --force.
• Files Cortex generated before but no longer produces (renamed skills, disabled tools, v1 legacy paths) are removed only if untouched.
• After an import, compile warns about original files that now duplicate your sources.

CI drift check

Commit .cortex/ and the generated files — cloud agents (Copilot coding agent, Codex, Claude Code on the web) read them straight from the repository. Then block drift:

name: cortex
on: [pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx --yes github:Phani3108/Cortex compile --check

Locally, cortex hooks install adds a pre-commit hook that runs the same check when .cortex/ changes.

CLI commands

Options

Model data

registry/latest.json holds pricing and context windows for 200+ models. A GitHub Action rebuilds it from the OpenRouter catalog every day and commits only real changes; the website redeploys with it. cortex update pulls the latest copy (or --source openrouter to build it locally). Models released after your last update are still priced — Cortex uses the newest model of the same family and tier and labels it as an estimate.

FAQ