rysweet/amplihack-rs/migrate

Migrate Session Skill

Move the currently running amplihack CLI session to a fresh azlin-managed VM and resume it there in a detached tmux. One command end-to-end.

⚠️ Do not activate this skill on any natural-language prompt that merely

contains the word "migrate" (e.g. "migrate from Python", "data migration",

"memory backend migration"). Activate only when the user explicitly types

the /amplihack:migrate slash command or asks to "move the current session

to <host>".

When to Use

• Local host is low on disk/RAM under heavy orchestrator load
• You want to move long-running OODA work to a beefier Azure VM
• You need to hand off the session to an unattended cloud host so the laptop

can sleep

• You are switching from a constrained dev container to a full Linux VM

Usage

/amplihack:migrate <hostname>
/amplihack:migrate <hostname> --session <session-id>

The destination <hostname> must be an azlin-managed VM (reachable via azlin connect / azlin cp).

What It Does

1. Detects the active CLI session via env var → newest session-state dir.
2. Bootstraps the destination (idempotent): node, npm, gh, uv, copilot,

amplihack — skips tools already installed at a matching version.

1. Builds a selective zstd-compressed tarball containing only:

• ~/.config/, ~/.copilot/skills/, ~/.amplihack/, ~/.ssh/
• The active ~/.copilot/session-state/<id>/ directory only
• ~/.simard/ only when --include-simard is passed. It is host-local

runtime state, not session state, and the destination is often a live Simard host whose own store must not be replaced (issue #1166).

1. Ships the tarball to the destination via azlin cp, extracts it.
2. Verifies gh auth, copilot --version, and session-state integrity.
3. Runs a final delta rsync of the active session-state to capture

events written during the transfer.

1. Reconstructs the project tree on the destination so the resumed session

lands in a valid git checkout instead of $HOME:

• Reads cwd, git_root, repository, host_type, branch from the

active session's workspace.yaml (flat grep/sed parsing, no yq).

• Skips (warn + resume in $HOME, no hard-gate) when the session has no

reconstructable project: no workspace.yaml, absent repository/git_root, or a non-github host_type.

• Validates the untrusted fields (repo/branch/host_type regex + allowlist);

a malformed field on a github session is fatal (exit 11).

• Re-derives destination paths from the validated repository/branch

(the source git_root, which amplihack records equal to cwd, is not reused): $HOME/src/<repo> for the clone and $HOME/src/<repo>/worktrees/<branch> for worktree sessions (detected by /worktrees/ in cwd; double-nested worktrees normalized to one level).

• gh repo clone <repository> (idempotent fetch+checkout if .git exists);

git worktree add for worktree sessions, falling back to a standalone clone/checkout at cwd so the hard-gate still passes.

• All GitHub network calls (clone/fetch) use bounded retry-with-backoff

(AMPLIHACK_MIGRATE_RETRIES / AMPLIHACK_MIGRATE_RETRY_DELAY) so a transient network failure retries before the exit-13 hard failure.

• Rewrites cwd and git_root in the destination workspace.yaml.
• Hard-gates before resume: aborts if cwd is missing or not a git

checkout on the recorded branch (unless reconstruction was skipped).

1. Starts the CLI in a detached tmux on the destination:

• copilot: copilot --resume <id>
• claude: claude --resume <id> (best-effort)
• amplifier: prints manual-attach instructions (v1)

Prints an azlin connect -y <hostname>:session-<id> command you can paste on your laptop to attach.

What Is Not Migrated

• ~/src/* source trees — reconstructed on the destination via

gh repo clone / git worktree add from the paths recorded in the session's workspace.yaml (cross-user paths remapped under $HOME), not copied in the tarball. Uncommitted / unpushed changes are not carried over.

• Caches: **/target/, **/.venv/, **/node_modules/, ~/.cache/,

**/__pycache__/, and any directory tagged CACHEDIR.TAG

• Inactive sessions under ~/.copilot/session-state/

Security Note

Unlike the remote-work skill, this migration intentionally copies credentials (~/.ssh, ~/.config/gh/hosts.yml) to the destination. The skill prints a warning before transfer. Only use with trusted destinations.

tmux: run kill-server and kill-session -a only with -S <private socket> or -L <name>, for a server you started; inside a tmux pane $TMUX overrides TMUX_TMPDIR, so without them the command reaches the user's own server, and a PreToolUse hook denies it.

Invocation

The slash command resolves to this skill's helper script, which is staged by the bundle installer into ~/.amplihack/.claude/skills/migrate/scripts/.

bash "$AMPLIHACK_HOME/.claude/skills/migrate/scripts/migrate.sh" <hostname> [--session <id>]

The script is idempotent: re-running against the same destination skips already-installed toolchain, overwrites the active session-state on the destination (source is authoritative until resume), and re-extracts ~/.config/ / ~/.amplihack/ (cheap; ensures freshness).

See Also

• Full documentation: docs/skills/migrate.md
• azlin skill — destination provisioning and transport
• remote-work skill — related but does not copy credentials