Skills Sync

Skills are markdown files that agents auto-inject as context when their compatibility filters match. Codemux's skills sync mirrors them across every device you sign into — end-to-end encrypted, so the server only sees ciphertext.

This is part of the Agent Chat (Beta) surface and is hidden when Beta Features is off.

What Counts As A Skill

Codemux watches four directories on every device:

• ~/.codemux/skills/ — Codemux-native skills
• ~/.claude/skills/ — Claude Code skills (also picked up natively by claude)
• ~/.codex/skills/ — Codex skills
• ~/.opencode/skills/ — OpenCode skills

Each skill is a folder with a SKILL.md (or skill.md) plus optional support files. The folder name is the skill ID; the SKILL.md frontmatter declares compatibility (which providers, which workspaces) and the body is the system-prompt fragment that gets injected.

Setting Up Sync

Email/password accounts

Sync turns on automatically the first time you sign in. The encryption key is derived from your password during the sign-in flow (Argon2id → HKDF-SHA256). No extra setup.

GitHub OAuth accounts

The OAuth flow doesn't give Codemux a password, so it can't derive the encryption key on its own. The first time you visit Settings → Account → Sync with an OAuth account, you'll see a one-time "Set sync password" form:

1. Choose a sync password. This is independent of your GitHub login.
2. Codemux derives the encryption key locally.
3. Skills sync turns on for every device that signs in with the same account + sync password.

If you sign in on a second device, you'll see a "Provide password for sync" form instead — enter the same sync password and skills sync resumes.

How It Works (User-Level)

• Encryption: XChaCha20-Poly1305 per skill blob with a fresh OS-RNG nonce per encryption. The server stores opaque ciphertext.
• Key derivation: Argon2id (m=64MiB, t=3, p=4) from your password + email, split via HKDF-SHA256 into an auth secret (sent to the server in place of your password) and an encryption key (32 bytes, never leaves the device).
• Key persistence: cached locally at ~/.local/share/codemux/sync-key.enc, AES-GCM-wrapped under your machine ID. The wrapped key cannot be copied between machines — a different machine ID produces a different wrap key.
• Sync triggers:
  • File watcher pushes ~1.5s after you save a skill.
  • Periodic 5-minute pulse when the window is visible.
  • Manual "Sync now" button in Settings.
• Conflict resolution: last-write-wins by updated_at. If you edit the same skill on two devices simultaneously, the newer timestamp wins.

The Sync Status Panel

Open Settings → Account → Sync to see:

• Sync state — On / Off / Setup needed / Repair needed.
• Last sync — relative time ("3 minutes ago").
• Sync now — manual trigger.
• Export skills… — write all current skills to a .zip for backup.
• Import skills… — restore from an export.
• Forgot password / reset sync… — opens the destructive reset flow (see below).

Reset Flow

If you forget your sync password, the data is unrecoverable — that's the design. The reset flow:

1. Opens a multi-step dialog that forces you to export-or-explicit-skip your current skills before wiping.
2. Walks you through setting a new sync password.
3. Wipes the server-side ciphertext (it would be undecryptable anyway).
4. Re-encrypts your locally-imported skills (if any) with the new key and uploads them.

The "explicit skip" step is intentional friction so you don't accidentally lose months of skill authoring by clicking through a wizard.

What Doesn't Sync

• Project-scoped skills. Skills tied to specific git repos are planned but not yet shipping. Today every synced skill is user-global.
• Anything outside the four watched directories. Symlinks pointing into the watched dirs are followed; skills authored elsewhere aren't picked up.
• Skills you've explicitly disabled. The disable state is local-only.

Privacy

• On the server: ciphertext only. Skill names, contents, frontmatter — all encrypted before upload.
• In transit: HTTPS to api.codemux.org (override with CODEMUX_API_URL for self-hosting).
• On disk: plaintext in your skills directories (so the providers can read them), encrypted ciphertext for the local sync key wrap.
• Cross-product compatibility: skills sync is byte-identical with Vexis — the same account roams across both products. The shared codemux-api-* HKDF protocol is pinned in CI for both clients.

Related

• Agent Chat — where skills are consumed at chat time
• Authentication — account setup and password derivation
• Settings — the Sync, Skills, and Account sections