Cortex

Write your AI knowledge once. Distribute it everywhere.

AI coding assistants like GitHub Copilot, Gemini, and Claude read instructions from platform-specific directories (~/.copilot/, ~/.gemini/, ~/.claude/). If you use multiple assistants, you end up duplicating the same agent definitions and skill prompts in each — keeping them in sync is tedious and error-prone.

Cortex solves this by storing your knowledge in one central place (~/.cortex/ai/) and copying it to each platform's global directory. Edit the source once — run cortex sync to propagate the changes everywhere.

Install

npm install -g @ignaciocastro0713/cortex

Requirements: Node.js >= 22 · Git (for cortex update)

Quick start

1. Initialize (run once)

cortex init

Creates the following structure in your home directory:

~/.cortex/
  cortex.toml       ← configuration file
  ai/
    agents/         ← AI agent definitions (.md files)
    skills/         ← skill and instruction prompts (.md files)
  deps/             ← third-party knowledge cloned from Git

2. Add your knowledge files

Create .md files in ~/.cortex/ai/agents/ and ~/.cortex/ai/skills/. These are plain Markdown files that your AI assistant will read as instructions.

Example — ~/.cortex/ai/agents/code-review.md:

# Code Review Agent
Review code for correctness, edge cases, and style issues.
Always suggest tests for uncovered paths.

Example — ~/.cortex/ai/skills/testing.md:

# Testing Skill
Write unit tests using the AAA pattern (Arrange, Act, Assert).
Prefer pure functions and avoid mocking unless necessary.

3. Configuration

~/.cortex/cortex.toml controls everything:

platforms = ["copilot", "gemini", "claude"]

[deps]
# Clone a third-party knowledge repo as a dependency
design-doc-mermaid = "https://github.com/SpillwaveSolutions/design-doc-mermaid"

[skills]
paths = [
  "~/.cortex/ai/skills/*",   # your own skills
  "@design-doc-mermaid",     # all files from the dep above
]

[agents]
paths = ["~/.cortex/ai/agents/*"]

# MCP servers synced globally to ~/.copilot/mcp-config.json and ~/.gemini/settings.json
[mcp.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

[mcp.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

4. Sync

cortex sync

Cortex copies your files to ~/.copilot/ (Copilot), ~/.gemini/ (Gemini), and ~/.claude/ (Claude). Run this once after editing your knowledge sources — the files are available globally in every project. Only files managed by Cortex are overwritten — files you created manually are left untouched. If Cortex previously synced a file and you've edited it locally, that file is skipped with a ⚠ warning in the tree; use --force to overwrite it.

Files removed from your config are automatically detected and deleted on the next sync. Empty directories are cleaned up automatically; directories containing files not managed by Cortex are preserved.

MCP server configs defined in [mcp] are synced to each platform's config file using a merge strategy — your manually-defined servers are preserved, and Cortex-managed servers are added or updated.

How it works

graph TB
    Source["🧠 ~/.cortex/ai/
    ─────────────────
    agents/
      └─ code-review.md
    skills/
      ├─ planning/
      └─ implementation/"]

    subgraph cortex sync
        CMD["cortex sync"]
    end

    Source -->|copies| CMD

    CMD --> PA["💻 ~/.copilot/
      agents/
      skills/"]

    CMD --> PB["💻 ~/.gemini/
      agents/
      skills/"]

    CMD --> PC["💻 ~/.claude/
      agents/
      skills/"]

    style Source fill:#2d5a27,color:#fff,stroke:#4a9e42
    style CMD fill:#1a3a5c,color:#fff,stroke:#2e6da4

Loading

Commands

Command	Description
cortex init	Create ~/.cortex/cortex.toml and the ~/.cortex/ai/ folder structure
cortex sync	Copy knowledge files to global platform directories and sync MCP configs
cortex list	Show the map of knowledge sources configured in cortex.toml
cortex clean	Remove all cortex-managed files and MCP entries from platform directories. Asks for confirmation unless --force is passed. Also cleans files from platforms removed from the config.
cortex update	Pull latest changes for ~/.cortex/ai/ and all deps

Options

Flag	Short	Description
--dry-run	-d	Preview sync without making any changes
--force	-f	sync: overwrite locally modified files · clean: skip confirmation prompt
--version	-v	Print the current version and exit
--help	-h	Show the help message

Configuration reference

Path prefixes

Prefix	Resolves to
~	User home directory
@alias	~/.cortex/deps/{alias} (a cloned dependency)

Platforms

Platform	Files copied to	MCP config path
copilot	~/.copilot/	~/.copilot/mcp-config.json
gemini	~/.gemini/	~/.gemini/settings.json
claude	~/.claude/	~/.claude.json

Project structure

src/
  index.ts          Entry point and argument parsing
  core/
    constants.ts    Shared paths and platform definitions
    hash-db.ts      MD5 hash tracking for dirty-file detection
    mcp.ts          MCP server config merge into platform JSON files
    parser.ts       TOML config reader/writer
    resolver.ts     Config resolution and entry deduplication
  utils/
    fs-utils.ts     Filesystem operations (copy, glob, path expansion)
    git-utils.ts    Git wrapper (clone, pull)
    log.ts          Colored terminal output via node:util styleText
    tree.ts         ASCII tree renderer
  commands/
    init.ts
    update.ts
    sync.ts
    list.ts
    clean.ts
test/
  commands/
    init.test.ts
    sync.test.ts
    list.test.ts
    clean.test.ts
    update.test.ts
  fs-utils.test.ts
  fs-utils-io.test.ts
  mcp.test.ts
  resolver.test.ts
  parser.test.ts
  sync-filters.test.ts
  git-utils.test.ts

License

MIT — see LICENSE for details.