aisync-ship

name	aisync-ship
description	Use when the user wants to copy/sync their Claude Code configuration (~/.claude/) from this machine to (a) another machine over SSH, and/or (b) other agent CLI user dirs (~/.codex, ~/.gemini, ~/.cursor, ~/.codeium/windsurf, ~/.cline) on the same or remote machine. Handles path rewriting, local-bound hook stripping, runtime-data isolation, and Claude → other-tool fan-out. Credentials are NOT shipped by default. Target machine only needs ssh + tar.
tools	Read, Bash, Edit

aisync-ship

Sync user-level Claude Code configuration to a remote machine. Target machine zero-dependency — only ssh + tar + sh required (no rsync, no Claude pre-installed strictly necessary).

When to use

User says any of:

• "把配置同步到 evan@x.x.x.x" / "把 Claude 配置同步到 192.168.x.x"
• "ship my Claude setup to "
• "把 ~/.claude 也同步到 ~/.codex / 让 Codex 也用一样的 skills/rules"
• "fan out my Claude config to all the agent CLIs on this machine"
• "把 Claude 的 skill 和 rule 也复制到 Codex 和 Gemini" (cross-tool, same machine)
• "let me login to Claude on machine Y / 让我在 Y 机器上登录 Claude"

Capability matrix

Scenario	Command
A. Same machine, cross-tool fan-out (Claude → Codex/Gemini/Cursor/Windsurf/Cline on this host)	scripts/fanout.py --dry-run (auto-detects which user_dirs exist) → review → re-run without --dry-run
B. Cross-machine, single tool (Claude on src → Claude on remote)	scripts/ship.sh --dry-run <user@host> → review → --apply
C. Cross-machine + cross-tool (Claude on src → Claude + Codex + ... on remote)	scripts/ship.sh --dry-run --also codex,gemini <user@host> → review → --apply

When NOT to use

• For project-level .agents/ rule sync between AI tools (Claude/Codex/Gemini/Cursor/...) — use aisync sync instead. This skill is user-level (~/.claude → ~/.<other-tool>), not project-level.
• For pulling configuration FROM a remote source onto this machine, use ship.sh --pull <user@host> (reverse direction; Phase 2). It's mutually exclusive with --also and --include-credentials.

Pre-flight checklist (MUST execute before any transfer)

Run these in order. STOP if any fails and report to user.

1. Reachability + tar present:

   ssh -o BatchMode=yes -o ConnectTimeout=5 <target> 'uname -a && command -v tar'
   

2. Existing remote config?:

   ssh <target> 'ls -la ~/.claude/ 2>/dev/null | head -5'
   

   If the remote already has ~/.claude/, the ship script will back it up to ~/.claude.bak.<timestamp> before overwrite. Confirm with user that overwrite is intended.
3. Claude Code installed on remote? (informational, not blocking):

   ssh <target> 'command -v claude || echo NOT_INSTALLED'
   

Transformation rules (applied to staged copy, NEVER to source)

The scripts/ship.sh helper applies the rules below. Always run with --dry-run first, show the plan + diff to the user, get confirmation, THEN run with --apply.

Both settings.json AND .mcp.json are passed through the same transformer; .mcp.json typically only triggers rules 1 + 4.

#	Rule	Source	Action
1	Path rewrite	settings.json, .mcp.json (any string value)	/Users/<u> → /home/<remote-user>/ (POSIX-Linux assumption)
2	Local-bound hook commands	settings.json hooks[*].hooks[*]	Drop entries whose command contains /Users/.../sweatshop/ (or any local-fs path that will not exist remotely). Empty hook groups + empty events are removed.
3	Localhost HTTP hooks	settings.json hooks[*].hooks[*]	Drop entries with type:"http" and url containing 127.0.0.1 or localhost
4	Local MCP server	settings.json/.mcp.json mcpServers.*	Drop servers whose args contain a non-portable absolute path (e.g. /Users/.../sweatshop/...)
5	Runtime data	sessions/, history.jsonl, session-env/, projects/, file-history/, paste-cache/, shell-snapshots/, debug/, telemetry/, usage-data/, cache/, downloads/, plans/, tasks/, teams/, backups/, stats-cache.json, mcp-needs-auth-cache.json	Exclude from tarball (privacy + size)
6	Plugin cache	plugins/ (entire dir, ~200 MB cache + marketplaces re-fetchable)	Exclude; remote re-resolves from enabledPlugins in settings.json
7	AppleDouble	._*, .DS_Store	Exclude from tarball
8	Credentials	macOS Keychain Claude Code-credentials	NOT shipped by default. Each machine should claude login independently. Opt in with --include-credentials only when explicitly requested.

Execution flow

1. scripts/ship.sh --dry-run <target>     (default mode)
   → stages source via tar | tar (no source-side rsync needed)
   → transforms settings.json + .mcp.json (transform-settings.py)
   → if (and ONLY if) --include-credentials was passed: extracts Keychain
     credential via extract-credentials.sh
   → prints plan: stage dir, file count, transformation log, unified diff
2. User reviews diff + confirms
3. scripts/ship.sh --apply <target>
   → streams `tar (.claude + install-remote.sh) | ssh sh install-remote.sh`
   → install-remote.sh on the remote does an ATOMIC mv-swap:
       mv ~/.claude → ~/.claude.bak.<timestamp>   (only if existing)
       mv staged    → ~/.claude
   → on any error mid-install, the backup is auto-restored (trap-on-error)
   → if --no-credentials and remote already has .credentials.json, it is preserved
   → final chmod 600 on the credential file
4. Post-ship verify (suggest to user):
   ssh <target> 'claude --version && ls -la ~/.claude/.credentials.json'
   ssh <target> 'echo hi | claude -p "say hi"'   # smoke test

Decision points (require user confirmation, do NOT default)

• Include credentials: default OFF. The user's standing preference is one claude login per machine — do not ship Keychain credentials unless they explicitly ask. If asked, use --include-credentials.
• Wipe remote-only files (mirror mode): superseded by Phase 2 marker-based delete propagation. fan-out targets get precise per-file delete based on the .aisync-ship-managed marker; user-authored files in dest are preserved automatically.
• Plugin cache cleanup on remote: ship.sh already excludes plugins/ so the staged side is clean; remote plugins/cache/ survives unless user asks to wipe.

Anti-patterns (what NOT to do)

• DO NOT scp -r ~/.claude <target>:~/.claude — captures sessions/history (privacy leak) and session-env (12K+ files, slow + brittle).
• DO NOT silently apply settings.json transformations — always show the unified diff and get explicit user OK.
• DO NOT assume target has rsync — use the tar | ssh tar pipe in ship.sh.
• DO NOT push to a remote ~/.claude without backing up — ship.sh does this automatically; if you bypass the script, replicate the backup.
• DO NOT ship credentials by default. The script default is --no-credentials and the user's standing preference is to claude login on each machine independently. Only pass --include-credentials when the user explicitly asks ("把凭证也带过去" / "include creds").
• DO NOT shell out to extract-credentials.sh or copy ~/.claude/.credentials.json "just in case" — the per-machine login model is the contract.

Cross-tool fan-out (A and C scenarios)

fanout.py mirrors ~/.claude/'s portable parts (root MD, rules/, skills/, agents/) into other agent CLIs' user dirs per src/platforms.rs. What is NOT fanned out (Claude-specific format, would corrupt other tools): settings.json, .mcp.json, hooks/, commands/, lib/, scripts/, statusline-command.sh, .credentials.json.

⚠️ Subtree ownership — fan-out claims full ownership of rules/, skills/, agents/ subtrees on the target for every platform you include in --also / --to-platforms, but only when the source actually has content for that subtree (evidence-based — see fanout.py's replace_subtree). Concretely: if you fan out to codex and your source has 7 rules, the resulting ~/.codex/rules/ will contain exactly those 7 rules. Any rule that lived in ~/.codex/rules/ independently (e.g. one you wrote by hand against Codex specifically) will be deleted. Files in dest outside those subtrees (~/.codex/auth.json, config.toml, sessions/, memories/) are preserved.

Implications:

• To preserve a tool-specific rule on the fan-out target, move it into ~/.claude/rules/ so the source becomes authoritative.
• To not have your codex/gemini/cursor independent setup mass-edited, simply don't include that platform in --also / --to-platforms.
• Symlinks inside ~/.claude/skills/<name>/ are preserved as symlinks (not dereferenced) — fan-out will not silently materialize symlink targets into other tools' dirs.

Fan-out target detection: fanout.py (no flags) auto-detects which agent user_dirs exist on this host (e.g., if ~/.cursor/ exists, Cursor is in scope). Override with --to-platforms <list> or --all-platforms.

Per-platform mapping (from platforms.rs):

Source	codex	gemini	cursor	windsurf	cline
CLAUDE.md	~/.codex/AGENTS.md	~/.gemini/GEMINI.md	(no user root md)	(no user root md)	(no user root md)
rules/*.md	~/.codex/rules/*.md	(no rules dir)	~/.cursor/rules/*.mdc (ext rewrite)	~/.codeium/windsurf/rules/*.md	(no rules dir)
skills/<n>/SKILL.md	~/.codex/skills/<n>/SKILL.md	~/.gemini/skills/<n>/SKILL.md	(no skills dir)	(no skills dir)	(no skills dir)
agents/*.md	(no agents dir)	(no agents dir)	(no agents dir)	(no agents dir)	(no agents dir)

Helper scripts

• scripts/extract-credentials.sh — platform-aware. macOS: security find-generic-password -s 'Claude Code-credentials' -w. Linux: cat ~/.claude/.credentials.json. Sanity-checks JSON shape (first byte { or [). Exits non-zero on failure. Not invoked by default (credentials opt-in via --include-credentials).
• scripts/transform-settings.py — JSON-aware transformation engine for settings.json AND .mcp.json. Reads from --in path, writes to --out path, emits a human-readable transformation log. Idempotent on already-transformed input.
• scripts/fanout.py — Claude → other-tool user-dir fan-out engine. Standalone for A-mode (--dry-run then re-run); invoked by ship.sh --also for C-mode (writes to a stage dir + emits manifest TSV).
• scripts/install-remote.sh — POSIX sh script that runs on the REMOTE inside a tmpdir. Reads a manifest TSV (<stage_subpath>\t<home_subpath>) and atomically mv-swaps each entry, with cross-platform restore-on-error. Credential preservation only applies to .claude.
• scripts/ship.sh — orchestrator. ship.sh --help for full usage. Calls extract-credentials.sh + transform-settings.py + fanout.py locally; ships install-remote.sh + manifest.tsv along with all staged platform subdirs so the remote does the install transactionally.

Recovery

install-remote.sh rollback covers most failure modes automatically, but is NOT a magic transaction — read the cases below before assuming "no manual recovery needed":

Failure mode	Auto-rollback?	Side effects
Apply step (cp -aR staged/. dest/ or mv staged dest) fails partway	Yes — restores from snapshot backup	None; dest looks pre-install
Snapshot itself fails (cp -aR dest backup hits permission/space)	No — dest is untouched (we never started writing it) but the script logs cannot rollback ... backup missing and exits non-zero	A .partial snapshot may be left as garbage for diagnosis
Multi-platform: one platform's snapshot fails after others succeeded	Successful platforms roll back; the one with missing snapshot leaves dest untouched	Newly-created intermediate dirs from mkdir -p $(dirname dest) may stay (e.g. ~/.codeium/ if it didn't pre-exist and .codeium/windsurf install never ran)

To roll back a successful install manually:

ssh <target> 'ls -d ~/.claude.bak.* 2>/dev/null'                    # find backups
ssh <target> 'rm -rf ~/.claude && mv ~/.claude.bak.<ts> ~/.claude'  # restore

To clean diagnostic .partial garbage from a previous failed snapshot:

ssh <target> 'ls -d ~/.*.bak.*.partial 2>/dev/null && rm -rf ~/.*.bak.*.partial'

The source side is never modified — staging happens in /tmp/aisync-ship-<ts>/, which is left in place after dry-run for inspection (cleaned up after a successful --apply, unless --keep-stage is given).