cortex

Sync Claude Code sessions between machines with automatic path remapping.

Claude Code stores your session history in ~/.claude/projects/ using absolute paths. Switch from your Mac to a Linux server and those sessions are gone — the paths don't match. cortex fixes that.

npm install -g cortex-cli

How it works

Machine A (Mac)                        Machine B (Linux)
─────────────────────────              ──────────────────────────────
~/.claude/projects/                    ~/.claude/projects/
  -Users-alice-myapp/                    -home-alice-work-myapp/
    abc123.jsonl                           abc123.jsonl
    cwd: /Users/alice/myapp   ──────▶      cwd: /home/alice/work/myapp
                               cortex        ↑ paths remapped automatically
                            sync → pull

cortex identifies your project by its git remote URL (or first commit hash), maps it to the correct path on each machine, and rewrites only the structural path fields inside each JSONL session file — without touching your conversation history.

Quick start

# 1. Install
npm install -g cortex-cli

# 2. Configure on Machine A
cortex init
#  → pick GitHub (PAT) or a local folder (Dropbox / iCloud / Syncthing)
#  → set your encryption passphrase (never stored)

# 3. Push your sessions
cortex sync

# 4. On Machine B — pull and start working
cortex init   # same storage, same passphrase
cortex pull   # downloads, decrypts, remaps paths automatically

Open any project on Machine B — Claude Code shows your full session history.

Commands

| Command | What it does | |---|---| | cortex init | Configure storage, email, and passphrase | | cortex sync | Encrypt ~/.claude/ and upload | | cortex pull | Download, decrypt, remap paths | | cortex status | Show what's out of sync (no download) | | cortex convert <file> --to <target> | Convert a Claude Code skill |

Storage backends

GitHub private repo (recommended)

No OAuth app needed — just a Personal Access Token.

cortex init
# Select "GitHub private repo"
# → Create a PAT at: github.com/settings/tokens/new?scopes=repo
# → Paste the token (ghp_...)
# → cortex validates it and creates the private repo automatically

Local folder

Works with Dropbox, iCloud Drive, Syncthing, NFS, or any shared directory.

cortex init
# Select "Local folder"
# → Enter path: ~/Dropbox/cortex-backup

Skill conversion

Convert Claude Code skills to other AI tool formats using your own Anthropic API key.

# To Antigravity  →  .agent/skills/<name>/SKILL.md
cortex convert ~/.claude/skills/tdd.md --to antigravity --output-dir ./my-project

# To Cursor  →  .cursorrules (intelligent append, no duplicates across runs)
cortex convert ~/.claude/skills/tdd.md --to cursor --output-dir ./my-project

# Both at once
cortex convert ~/.claude/skills/tdd.md --to all --output-dir ./my-project

API key priority: ANTHROPIC_API_KEY env → ~/.cortex/api-key.enc (encrypted) → interactive prompt.

Security

Everything is encrypted before leaving your machine. Your storage provider sees only ciphertext.

| What | How | |---|---| | Encryption | AES-256-GCM (authenticated) | | Key derivation | PBKDF2, 600,000 iterations, SHA-256 | | Salt | SHA-256(lowercase(your email)) | | Passphrase | Never stored anywhere — derived fresh each session | | Secret detection | Warns before encrypting if API keys or PEM keys are found in your files |

The GitHub PAT is stored in ~/.cortex/config.json (your machine, your user). The Anthropic API key — if you choose to save it — goes to ~/.cortex/api-key.enc, encrypted with your sync passphrase.

How path remapping works

Claude Code encodes project paths into directory names by replacing every non-alphanumeric character with -:

/home/alice/work/myapp  →  -home-alice-work-myapp

This encoding is lossy — it cannot be reversed. cortex reads the cwd field inside each JSONL session file, which holds the original absolute path, and uses that as the source of truth.

On cortex pull, for each project:

1. Reads cwd from the session JSONL to get the original path
2. Identifies the project via git remote.origin.url or git rev-list --max-parents=0 HEAD
3. Looks up your local path in ~/.cortex/path-mappings.json (prompts once if unknown)
4. Rewrites only the 4 structural fields per line: cwd, filePath, file_path, file.filePath
5. Renames ~/.claude/projects/<old-encoded>/ → <new-encoded>/

Conversation history, command outputs, and text responses are never modified.

For projects without git, drop a cortex.json in the project root:

{ "projectId": "my-unique-id" }

Requirements

• Node.js ≥ 20
• Claude Code installed on each machine you want to sync

License

AGPL-3.0 — free to use, modify, and distribute. Forks used to run a hosted service must publish their source changes.