[FEATURE] Separate configs that you'd want to backup from those you wouldn't

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Like many people I use a dotfile manager so I can replicate my setup on another machine (cloud instance, home and work, etc.). e.g. I use https://yadm.io. It is also, obviously, a good idea to backup a laboriously created Claude configuration. I'd love to manage my Claude Code configuration so if I have to code on an ephermeral cloud instance I can check out my dotfile, maybe login to an MCP server or two, and get to work. But the current configuration setup makes that very difficult.

I asked Claude about how to do this and it's advice was:

Track these (safe, portable, no secrets):

~/.claude/settings.json — Your user-level settings: preferred model, permissions, hooks, env vars. This is the main one you want synced across machines.
~/.claude/CLAUDE.md — Global instructions that apply to all projects. Pure text, no secrets.
~/.claude/commands/ — Any global slash command definitions you've created.
~/.claude/agents/ — Global subagent definitions (markdown files).
~/.claude/plugins/ — If you've installed plugins, these are collections of commands/agents/hooks/MCP configs.

Do NOT track (secrets, session state, or machine-specific):

~/.claude.json — This is the big one to avoid. It contains your OAuth session, per-project state (allowed tools, trust settings), and various caches [Claude](https://code.claude.com/docs/en/settings), plus MCP server configurations at the user scope. The auth tokens make it unsuitable for version control.
~/.claude/.credentials.json — On Linux, this stores your authentication credentials directly.
~/.claude/projects/ — Full conversation history with metadata. Machine-specific, large, and private.
~/.claude/debug/, ~/.claude/file-history/, ~/.claude/history.jsonl — Debugging logs, file edit snapshots, message history. All ephemeral.
~/.claude/session-env/ — Session-specific environment state.
~/.claude/ide/, ~/.claude/config/ — IDE links and runtime state.

The MCP server situation is the tricky part. User-scope MCP server configurations live inside ~/.claude.json [Claude](https://code.claude.com/docs/en/settings), which is the same file that has your OAuth tokens. You can't cleanly track just the MCP config without also tracking secrets.

And, indeed, the MCP setup is nearly impossible to manage with a dotfile manager.

Proposed Solution

Cleanly separate user configuration into a single directory so that can be easily backed up or managed with a dotfile manager. Other state, like memory, OAuth tokens, etc. would never be saved in this directory.

Alternative Solutions

The closest I can find is:

1. Backup/manage the files Claude suggested and ignore the ones it said to ignore
2. For MCP servers, write a script that does an claude mcp list to see what's setup and then runs claude mcp add commands as necessary to try to replicate a given state. But:
3. That's kind of a pain.
4. It's not really idempotent as if you change an MCP configuration this doesn't work

Another alternative would be a script that parses ~/.claude.json for the MCP servers, and does a comparison of all configuration fields except the authentication ones, and then replaces the configuration (or not) as necessary.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

I configure a new MCP server. In some cases this can be complex (e.g. I have an SQL MCP server but I didn't want to have it store my DB credentials in plain text so it's wrapped in a script that retrieves my credentials and then injects them into the MCP server). Then I need to work on a different machine (e.g. a cloud instance with a GPU to train a model) and I'd like to use Claude there to help me code. For 99% of my configuration I can yadm clone and I get my ~/.bashrc, my ~/.vimrc, etc., etc. and I can start working productively on a new instance. But I'd have to manually re-create big chunks of my Claude Code setup.

Additional Context

_No response_