contextshift

Translate AI context files between tools — CLAUDE.md, AGENTS.md, SOUL.md, .cursorrules, copilot-instructions.md, and more.

Every AI coding tool now reads a config file. They all encode the same thing — your project, your conventions, your rules — in completely incompatible formats. When you switch tools or use multiple tools in parallel, your context gets stranded.

contextshift solves this. Paste in any format, get out any other format. No rewrites. No starting over.

---

Supported formats

Key	Tool	File
claude	Claude Code	CLAUDE.md
agents	Codex CLI	AGENTS.md
gemini	Gemini CLI	GEMINI.md
cursor	Cursor	.cursor/rules/*.mdc
copilot	GitHub Copilot	.github/copilot-instructions.md
windsurf	Windsurf	.windsurfrules
soul	OpenClaw	SOUL.md
cowork	Claude Cowork	cowork-instructions.md

---

Install

npm install -g contextshift

Or use without installing:

npx contextshift CLAUDE.md --to cursor

---

CLI

# Translate to a single format
contextshift CLAUDE.md --to cursor

# Translate to multiple formats at once
contextshift CLAUDE.md --to agents --to copilot --to windsurf

# Translate to every supported format
contextshift CLAUDE.md --to all

# Write output to a specific directory
contextshift CLAUDE.md --to all --out ./generated

# Preview without writing files
contextshift CLAUDE.md --to cursor --dry-run

# Inspect what contextshift parsed from your file
contextshift CLAUDE.md --inspect

# SOUL.md → Codex CLI after the April 4 OpenClaw/Claude ban
contextshift SOUL.md --to agents

---

Node.js API

const { translate, translateAll, parse } = require('contextshift');

// Translate one format to another
const result = translate({
  content: fs.readFileSync('CLAUDE.md', 'utf-8'),
  from: 'claude',
  to: 'cursor',
});

console.log(result.filename);  // '.cursor/rules/global.mdc'
console.log(result.content);   // rendered file content
console.log(result.warnings);  // what couldn't be translated cleanly
console.log(result.ir);        // the intermediate representation

// Translate to all formats at once
const all = translateAll({
  content: fs.readFileSync('CLAUDE.md', 'utf-8'),
  from: 'claude',
});
// all.agents.content, all.cursor.content, all.soul.content ...

// Inspect the parsed intermediate representation
const ir = parse({
  content: fs.readFileSync('SOUL.md', 'utf-8'),
  from: 'soul',
});
// ir.personality, ir.prohibitions, ir.conventions ...

---

How it works

Every context file format encodes the same underlying intent:

• What is this project? (name, stack, architecture)
• How should you write code? (conventions, style)
• What must you never do? (prohibitions, safety rules)
• How should you communicate? (personality, tone)

contextshift parses your file into a neutral intermediate representation (IR), then renders the IR into the target format — adapting structure, syntax, and constraints for each platform.

CLAUDE.md ─── parse ──→ IR ──→ render ──→ .cursor/rules/global.mdc
                                    └──→ AGENTS.md
                                    └──→ copilot-instructions.md
                                    └──→ SOUL.md

What can't translate cleanly is flagged as a warning, not silently dropped. You always know what was lost.

---

Translation fidelity

Some things translate cleanly. Others don't. Here's what to expect:

Content type	Fidelity	Notes
Project name, stack, architecture	✅ Full	Universal across all formats
Code conventions	✅ Full	Syntax adapts per format
Prohibitions ("never do X")	✅ Full
Commands (npm run test)	⚠️ Partial	Copilot and Windsurf have no command support
Path-scoped rules	⚠️ Partial	Only Claude Code and Cursor support scoping
Personality / tone	⚠️ Partial	Only SOUL.md and Cowork use this
MCP server config	❌ Not portable	Tool-specific infrastructure
Claude Code hooks	❌ Not portable	No equivalent in other formats

Warnings are always printed. Nothing is silently discarded.

---

GitHub Action — keep all formats in sync

Add this to .github/workflows/contextshift.yml to auto-generate all context files on every push to main:

name: Sync context files
on:
  push:
    branches: [main]
    paths: ['CLAUDE.md']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g contextshift
      - run: contextshift CLAUDE.md --to all --out .
      - uses: EndBug/add-and-commit@v9
        with:
          message: 'chore: sync context files from CLAUDE.md [skip ci]'
          add: 'AGENTS.md GEMINI.md .cursorrules .github/copilot-instructions.md .windsurfrules'

---

Adding a new format

contextshift uses a parser/renderer architecture. Adding a new tool takes two files:

1. Parser — src/parsers/mytool.js — reads the format into IR
2. Renderer — add a function to src/renderers/index.js — writes IR to the format
3. Register both in src/index.js

The IR schema is the contract between parsers and renderers.

Pull requests for new formats are welcome.

---

Why this exists

As of April 2026:

• 8+ AI coding tools each have their own context file format
• Anthropic blocked Claude subscription tokens from OpenClaw on April 4, 2026 — thousands of users needed to migrate their SOUL.md files immediately, with no tooling to help
• Developers routinely run multiple tools in parallel (Claude Code in terminal, Cursor in IDE) and maintain diverging context files by hand
• Claude Code's own docs confirm it reads AGENTS.md as a fallback — the ecosystem is already trying to converge

contextshift is the missing bridge.

---

Contributing

git clone https://github.com/steffenpharai/ContextShift.git
cd ContextShift
node test/index.test.js   # run the test suite

See CONTRIBUTING.md for details.

Issues and PRs welcome. Especially:

• New format parsers and renderers
• Better heuristics for section classification
• Real-world CLAUDE.md / SOUL.md test fixtures

---

License

MIT