claude-mdx

Multi-user CLAUDE.md management for teams. One file, personal views, zero merge conflicts.

The Problem

• CLAUDE.md in .gitignore → worktrees lose it, Claude becomes "dumb"
• CLAUDE.md tracked in git → 5 people, 5 styles, constant merge conflicts
• ~/.claude/CLAUDE.md → not project-specific

The Solution

claude-mdx uses git smudge/clean filters to give each team member their own view of every CLAUDE.md in the repo — while storing all versions in a single tracked file.

IN GIT (what's stored)              ON YOUR DISK (what you see)
┌─────────────────────────┐         ┌─────────────────────────┐
│ <!--@shared-->           │ smudge  │ <!--@shared-->           │
│ # API Module             │ ──────► │ # API Module             │
│ Express.js + Jest        │         │ Express.js + Jest        │
│                          │         │                          │
│ <!--@umut-->             │         │ <!--@personal-->         │
│ Türkçe yorum yaz        │         │ Türkçe yorum yaz        │
│                          │         └─────────────────────────┘
│ <!--@ahmet-->            │         Umut only sees his section
│ English comments only    │
│                          │  clean
│ <!--@elif-->             │ ◄──────  Edits merge back safely
│ Always suggest perf tips │
└─────────────────────────┘

Works with every CLAUDE.md in every subdirectory. Works with worktrees.

Quick Start

First person (sets up the repo):

npx claude-mdx init
npx claude-mdx migrate     # converts existing CLAUDE.md files
git add .claude-mdx .gitattributes
git commit -m "chore: add claude-mdx multi-user support"

Teammates (after cloning):

bash .claude-mdx/setup.sh

That's it. Git filters handle everything automatically.

How It Works

1. CLAUDE.md files are tracked in git (not gitignored)
2. They contain sections for each team member, separated by <!--@name--> markers
3. On checkout (smudge): you see only <!--@shared--> + your section
4. On commit (clean): your edits merge back, other people's sections are preserved
5. No conflicts: each person edits different sections of the file

Worktree Support

Since CLAUDE.md is tracked, git worktree add copies it automatically. The smudge filter runs on checkout → your worktree gets your personal view.

User Identity

Your identity is determined by (in order):

1. git config claude-mdx.user (custom override)
2. git config user.name (lowercased, normalized)
3. $USER / $USERNAME environment variable

Set a custom identity:

git config claude-mdx.user your-name

Commands

| Command | Description | |---------|-------------| | claude-mdx init | Set up filters in current repo | | claude-mdx migrate | Convert plain CLAUDE.md files to multi-user format | | claude-mdx whoami | Show your identity | | claude-mdx status | Show filter configuration | | claude-mdx preview [file] | Preview your view of a file | | claude-mdx users [file] | List users with sections in a file |

File Format

<!--@shared-->
# Project Architecture
This content is visible to everyone.
Use Express.js with TypeScript.

<!--@umut-->
- Write comments in Turkish
- Use AAA pattern for tests
- Suggest custom AppError class for error handling

<!--@ahmet-->
- English comments only
- Prefer early returns
- Always mention performance implications

HTML comment markers are invisible in rendered markdown and ignored by Claude.

FAQ

Can I edit the shared section? Yes. Changes to <!--@shared--> propagate to everyone on next pull.

What if two people edit shared at the same time? Normal git merge — conflict only on the shared section, not personal sections.

What if I'm a new team member with no section yet? You'll see shared content + an empty personal section. Just add your preferences.

Does Claude see the markers? The markers are HTML comments. Claude processes the markdown content, the markers don't interfere.

License

MIT