Migrar Claude Code a otro ordenador: qué copiar de ~/.claude y qué dejar atrás

Mi ~/.claude pesa 2,8 GB. Lo que he escrito yo dentro de esa carpeta (instrucciones, settings, skills) no llega a un megabyte. El resto lo ha escrito Claude Code por mí, o lo ha escrito la máquina sobre sí misma. Copiar la carpeta entera al ordenador nuevo parece lo más rápido y es lo que más problemas da: en macOS el login ni siquiera viaja (vive en el Keychain), en Linux viaja un token que preferirías no transportar, los transcripts quedan colgados de rutas que ya no existen y el identificador de máquina es de otra máquina.

Resultado real, medido antes de escribir esto:

$ du -sh ~/.claude ~/.claude/projects ~/.claude/plugins ~/.claude/file-history
2.8G    /Users/juan.nunez/.claude
1.1G    /Users/juan.nunez/.claude/projects
691M    /Users/juan.nunez/.claude/plugins
 70M    /Users/juan.nunez/.claude/file-history

$ ls -la ~/.claude/CLAUDE.md ~/.claude/settings.json
-rw-r--r--  1 juan.nunez  staff  2386 Sep  3 11:18 /Users/juan.nunez/.claude/CLAUDE.md
-rw-------  1 juan.nunez  staff  2515 Sep 11 21:40 /Users/juan.nunez/.claude/settings.json

Las tres capas de ~/.claude

Todo lo que hay en esa carpeta cae en una de tres capas, y cada capa se migra de una forma distinta.

Lo que escribiste tú. CLAUDE.md, settings.json, skills/, commands/, agents/, workflows/, keybindings.json, themes/, output-styles/, y los scripts a los que apunta settings.json (un statusLine, un hook), en mi caso statusline.sh. Es texto plano, no depende de la máquina y se copia tal cual. Aquí también entra un bloque que no vive en ~/.claude sino en ~/.claude.json: tus servidores MCP de usuario, los que añadiste con claude mcp add --scope user. Si dudas de qué archivo guarda qué, este tip lo desglosa.

Lo que Claude escribió para ti. projects/ guarda cada transcript y la memoria automática de cada proyecto, history.jsonl guarda cada prompt que has tecleado, file-history/ guarda las copias que usa /rewind. Se puede mover, pero con una condición: projects/ está indexado por la ruta absoluta del repo, codificada en el nombre del directorio.

$ ls ~/.claude/projects | grep -- -code- | head -3
-Users-juan-nunez-code-ai-infra
-Users-juan-nunez-code-ai-plugins
-Users-juan-nunez-code-craft

Si en el ordenador nuevo tu usuario se llama distinto, o los repos cuelgan de otra ruta, esas sesiones no aparecen en el selector de /resume ni en --continue desde el repo, y la memoria automática de ese repo no se carga. claude --resume <id> sí las abre desde cualquier directorio (desde la v2.1.223), pero tienes que conocer el id.

Lo que escribió la máquina sobre sí misma. El login, que en macOS no es un archivo sino una entrada del Keychain. ~/.claude.json, que además de tus MCP guarda machineID, anonymousId, el trust de cada carpeta que has aprobado (51 en mi caso) y caches de features. Y plugins/, cuyo installed_plugins.json apunta a rutas absolutas de tu disco actual. Nada de esto se copia. Se regenera en un minuto.

Cómo montarlo

1. Empaqueta la capa que es tuya

cd ~ && tar czf claude-config.tgz \
  .claude/CLAUDE.md .claude/settings.json .claude/statusline.sh \
  .claude/skills .claude/commands .claude/agents .claude/workflows \
  .claude/keybindings.json .claude/themes .claude/output-styles

tar avisa de los archivos que no existen y sigue. En mi caso el paquete pesa 9 KB. Si tus skills son enlaces simbólicos a un repo, como los míos, tar guarda el enlace, no el contenido: en el ordenador nuevo clonas el repo y los enlaces vuelven a resolver.

Antes de cerrar la lista, comprueba qué archivos de ~/.claude referencia tu settings.json y añádelos:

grep -o '~/.claude/[^"]*' ~/.claude/settings.json

Descomprime en el destino con tar xzf claude-config.tgz -C ~.

2. Haz login, no copies el login

En macOS el token vive en el Keychain bajo Claude Code-credentials, no en un archivo. En Linux y Windows vive en ~/.claude/.credentials.json. En los tres casos la respuesta es la misma: en el ordenador nuevo, claude y /login. Un minuto de navegador contra el riesgo de transportar un token en un disco externo.

3. Lleva solo tus MCP de usuario

~/.claude.json no se copia entero. Se extrae el bloque mcpServers y se fusiona en el archivo que Claude Code cree en la máquina nueva:

# origen
jq '{mcpServers}' ~/.claude.json > mcp-servers.json

# destino, con Claude Code cerrado, después del paso 2
jq -s '.[0] * .[1]' ~/.claude.json mcp-servers.json > /tmp/c.json && mv /tmp/c.json ~/.claude.json

Lo probé con un CLAUDE_CONFIG_DIR limpio y solo ese bloque copiado:

$ claude mcp list
context7: https://mcp.context7.com/mcp (HTTP) - ✔ Connected
wmedia: https://wmedia.es/mcp/wmedia (HTTP) - ✔ Connected
frontendleap-changelog: https://frontendleap.com/mcp/changelog (HTTP) - ✔ Connected

Ese bloque incluye las cabeceras con tus claves de API. Trátalo como un secreto durante el traslado.

4. Reinstala los plugins desde tu settings.json

Tu settings.json ya lleva la lista completa: extraKnownMarketplaces dice de dónde viene cada marketplace y enabledPlugins qué plugins tienes activos. Dos líneas de jq la imprimen:

jq -r '.extraKnownMarketplaces | to_entries[] | .value.source.repo' ~/.claude/settings.json
jq -r '.enabledPlugins | keys[]' ~/.claude/settings.json

Y por cada línea, en el ordenador nuevo:

$ claude plugin marketplace add juanwmedia/craft
✔ Successfully added marketplace: craft (declared in user settings)

$ claude plugin install craft@craft
✔ Successfully installed plugin: craft@craft (scope: user)

Los 691 MB de plugins/ se quedan en el disco viejo. Lo que vuelve a bajar son solo las versiones que usas.

5. Opcional: llévate las sesiones

Solo tiene sentido si la ruta absoluta de cada repo es idéntica en las dos máquinas. Si lo es, copia el directorio del proyecto que te importe, no projects/ entero:

scp -r ~/.claude/projects/-Users-juan-nunez-code-ai-infra nuevo:~/.claude/projects/

Con eso el selector de /resume y la memoria automática de ese repo aparecen en el ordenador nuevo. Si la ruta no coincide, el transcript sigue siendo utilizable por id: desde ~/code/ai-infra lancé claude -p --resume <id> contra una sesión guardada bajo otra ruta y respondió. Lo que no cruza rutas es el selector y la memoria. history.jsonl se puede copiar con la misma condición: cada línea lleva la ruta del proyecto.

Qué copiar y qué no

Un detalle que lleva unos minutos la primera vez: si alguna vez lanzaste Claude Code con CLAUDE_CONFIG_DIR=~/.claude para probar perfiles separados, tienes un segundo ~/.claude/.claude.json dentro de la carpeta. Claude Code compone la ruta como $CLAUDE_CONFIG_DIR/.claude.json, así que ese archivo es de aquel perfil, no del tuyo. El que importa es ~/.claude.json, en tu home.

Si lo que quieres no es mover archivos sino dejar por escrito cómo está montado tu entorno, /team-onboarding genera esa guía a partir de tus propias sesiones.

Documentación oficial: The .claude directory y Authentication: credential management

Requisitos

• jq para los dos extractos; sin él, el bloque mcpServers se copia a mano desde ~/.claude.json
• Claude Code cerrado en la máquina nueva mientras editas ~/.claude.json