Using claude-symlink.

Configuration

Adding a new project

1. In user-config.js, add an entry to the PROJECTS block with absolute paths for Win and Mac:

   const PROJECTS = {
     'demo-backend':  { win: 'C:\\Projects\\demo-backend',  mac: path.join(os.homedir(), 'Projects/demo-backend')  },
     'demo-frontend': { win: 'C:\\Projects\\demo-frontend', mac: path.join(os.homedir(), 'Projects/demo-frontend') },
     // 'new-project': { win: 'C:\\Path\\new', mac: path.join(os.homedir(), 'Projects/new') },
   };

   Keep the root inside FILESYSTEM_MCP_PATH on both OSes. Otherwise Claude Desktop’s filesystem MCP won’t be able to see the project, and the doctor will warn.

2. Create the source folder in the repo:

   projects/<new-project>/
   ├── claude/              # (optional) .claude content — CLAUDE.md, plans/, agents/, etc.
   └── mcp/
       └── base.json        # MCP server list (Windows format: "cmd", "/c", "npx", …)

3. (Optional) If an MCP server has OS-specific args beyond the cmd /c transform (e.g. different browser executable paths), add mcp/base.win.json and/or mcp/base.mac.json. They merge into base.json at render time.

4. Run node setup-claude.js --fix-issues on each machine.

Opt-in / opt-out flags

Each PROJECTS entry accepts optional fields. Defaults match the full flow above.

extras: src is relative to projects/<name>/ in the repo; dst is relative to the project root on disk. Files only. Good for env files, secrets, any shared file.

Env-only project (no .claude/, no .mcp.json):

'demo-env-only': {
  win: 'C:\\Projects\\demo-env-only',
  mac: path.join(os.homedir(), 'Projects/demo-env-only'),
  claude: false,
  mcp: false,
  extras: [{ src: '.env', dst: '.env' }],
},

Place the source at projects/demo-env-only/.env. Run --fix-issues; <project>/.env becomes a symlink to it.

Full flow plus an extra file:

'demo-backend': {
  win: 'C:\\Projects\\demo-backend',
  mac: path.join(os.homedir(), 'Projects/demo-backend'),
  extras: [{ src: '.env.local', dst: '.env.local' }],
},

.env* files in projects/*/ are gitignored — put them in your sync folder (Dropbox/iCloud) to share across machines; Git doesn’t carry them.

FILESYSTEM_MCP_PATH

Defined in user-config.js. It’s the root directory handed to Claude Desktop’s filesystem MCP server. Everything under it is readable/writable by Claude Desktop via the filesystem tool; anything outside is invisible to it.

Default:

In claude-desktop/base.json the filesystem MCP uses <FS_PATH> as the placeholder, substituted at render time with the per-OS value.

Practical rule: keep every project root listed in PROJECTS inside this path on both OSes. If a project lives outside, the doctor warns (root outside FILESYSTEM_MCP_PATH) and Desktop-level filesystem access breaks (project-level .mcp.json still works). Fix by moving the project under the path, or widening FILESYSTEM_MCP_PATH to a common parent.

Placeholders

In any base.json under projects/*/mcp/ or claude-desktop/:

• <AUTO> — detected IDEA MCP port at render time
• <FS_PATH> — FILESYSTEM_MCP_PATH[os] (see above)

Other <TOKEN> patterns are flagged by the doctor as unknown — add a substitution in lib/render.js or remove it from the base file.

Mac cmd /c transformation

Source files are written in Windows format ("command": "cmd", "args": ["/c", "npx", …]). On Mac, the renderer strips cmd and /c, producing "command": "npx". You only maintain one format.

OS-specific base.win.json / base.mac.json also go through the transform — write them in Windows format too (unless Mac genuinely needs a different command).

Maintenance

Environment doctor (self-test)

Every run prints an Environment: block after the status table; --check runs it alone. It checks:

1. Each project root in PROJECTS exists on this machine
2. All project roots are inside FILESYSTEM_MCP_PATH
3. Claude Desktop is installed (config directory present)
4. IDEA’s MCP server answered the HTTP probe (fallback port warning otherwise)
5. Source files complete: projects/<name>/claude/, mcp/base.json, each extras.src
6. Base files parse as JSON and contain no unknown <PLACEHOLDER> tokens
7. No orphan projects/<foo>/ folders (disk matches PROJECTS)

Projects whose root is missing are automatically skipped during apply — their row shows (root missing) in red. Rendered targets whose source base.json was edited more recently get a yellow (stale) tag; re-run --render-only (or any flow that renders) to clear it.

Safety

• Idempotent: correct symlinks are left alone.
• Any real (non-symlink) file at a target is renamed to <name>.bak-YYYYMMDD-HHmmss before replacement.
• --dry-run shows planned actions without touching anything.
• --uninstall only removes symlinks that point at our managed targetPath. Real files, foreign symlinks (pointing elsewhere), and already-missing links are untouched. The repo source is never touched.

Paths

Git + sync folder

The repo can live inside a sync folder (Dropbox, iCloud Drive, …) for cross-machine sync of content that’s too sensitive for Git — typically .env* files. Git is the primary version history; the sync folder is optional.

• link.*.json and *.bak-* are gitignored because they’re OS-specific / regenerated.
• projects/*/.env* are gitignored too — rely on the sync folder (or manual placement) to carry them across machines.