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 ".
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
- Detects the active CLI session via env var → newest session-state dir.
- Bootstraps the destination (idempotent): node, npm, gh, uv, copilot,
amplihack — skips tools already installed at a matching version.
- 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).
- Ships the tarball to the destination via
azlin cp, extracts it.
- Verifies
gh auth, copilot --version, and session-state integrity.
- Runs a final delta
rsync of the active session-state to capture
events written during the transfer.
- 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).
- 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
1---2name: amplihack-migrate3description: Move the active amplihack CLI session (Copilot/Claude/Amplifier) to a fresh azlin-managed VM, preserving auth, plugins, skills, plan.md, todos, and conversation history. Resumes the session in a detached tmux on the destination host.4version: 1.0.05author: amplihack6activation_keywords:7 - amplihack-migrate8 - migrate session9 - move session to host10 - resume on azlin11min_tokens: 80012max_tokens: 200013metadata:14 source: https://skillmd.com/skills/rysweet/amplihack-migrate15---1617# Migrate Session Skill1819Move the currently running amplihack CLI session to a fresh azlin-managed VM20and resume it there in a detached tmux. One command end-to-end.2122> ⚠️ Do not activate this skill on any natural-language prompt that merely23> contains the word "migrate" (e.g. "migrate from Python", "data migration",24> "memory backend migration"). Activate only when the user explicitly types25> the `/amplihack:migrate` slash command or asks to "move the current session26> to <host>".2728## When to Use2930- Local host is low on disk/RAM under heavy orchestrator load31- You want to move long-running OODA work to a beefier Azure VM32- You need to hand off the session to an unattended cloud host so the laptop33 can sleep34- You are switching from a constrained dev container to a full Linux VM3536## Usage3738```text39/amplihack:migrate <hostname>40/amplihack:migrate <hostname> --session <session-id>41```4243The destination `<hostname>` must be an azlin-managed VM (reachable via44`azlin connect` / `azlin cp`).4546## What It Does47481. Detects the active CLI session via env var → newest session-state dir.492. Bootstraps the destination (idempotent): node, npm, gh, uv, copilot,50 amplihack — skips tools already installed at a matching version.513. Builds a selective `zstd`-compressed tarball containing only:52 - `~/.config/`, `~/.copilot/skills/`, `~/.amplihack/`, `~/.ssh/`53 - The **active** `~/.copilot/session-state/<id>/` directory only54 - `~/.simard/` **only** when `--include-simard` is passed. It is host-local55 runtime state, not session state, and the destination is often a live56 Simard host whose own store must not be replaced (issue #1166).574. Ships the tarball to the destination via `azlin cp`, extracts it.585. Verifies `gh auth`, `copilot --version`, and session-state integrity.596. Runs a final delta `rsync` of the active session-state to capture60 events written during the transfer.617. Reconstructs the project tree on the destination so the resumed session62 lands in a valid git checkout instead of `$HOME`:63 - Reads `cwd`, `git_root`, `repository`, `host_type`, `branch` from the64 active session's `workspace.yaml` (flat `grep`/`sed` parsing, no `yq`).65 - **Skips** (warn + resume in `$HOME`, no hard-gate) when the session has no66 reconstructable project: no `workspace.yaml`, absent `repository`/`git_root`,67 or a non-github `host_type`.68 - Validates the untrusted fields (repo/branch/host_type regex + allowlist);69 a malformed field on a github session is fatal (exit 11).70 - Re-derives destination paths from the **validated** `repository`/`branch`71 (the source `git_root`, which amplihack records equal to `cwd`, is not72 reused): `$HOME/src/<repo>` for the clone and73 `$HOME/src/<repo>/worktrees/<branch>` for worktree sessions (detected by74 `/worktrees/` in `cwd`; double-nested worktrees normalized to one level).75 - `gh repo clone <repository>` (idempotent fetch+checkout if `.git` exists);76 `git worktree add` for worktree sessions, falling back to a standalone77 clone/checkout at `cwd` so the hard-gate still passes.78 - All GitHub network calls (clone/fetch) use bounded retry-with-backoff79 (`AMPLIHACK_MIGRATE_RETRIES` / `AMPLIHACK_MIGRATE_RETRY_DELAY`) so a80 transient network failure retries before the exit-13 hard failure.81 - Rewrites `cwd` **and** `git_root` in the destination `workspace.yaml`.82 - Hard-gates before resume: aborts if `cwd` is missing or not a git83 checkout on the recorded branch (unless reconstruction was skipped).848. Starts the CLI in a detached tmux on the destination:85 - copilot: `copilot --resume <id>`86 - claude: `claude --resume <id>` (best-effort)87 - amplifier: prints manual-attach instructions (v1)8889Prints an `azlin connect -y <hostname>:session-<id>` command you can paste on90your laptop to attach.9192## What Is Not Migrated9394- `~/src/*` source trees — **reconstructed** on the destination via95 `gh repo clone` / `git worktree add` from the paths recorded in the session's96 `workspace.yaml` (cross-user paths remapped under `$HOME`), not copied in the97 tarball. Uncommitted / unpushed changes are not carried over.98- Caches: `**/target/`, `**/.venv/`, `**/node_modules/`, `~/.cache/`,99 `**/__pycache__/`, and any directory tagged `CACHEDIR.TAG`100- Inactive sessions under `~/.copilot/session-state/`101102## Security Note103104Unlike the `remote-work` skill, this migration **intentionally** copies105credentials (`~/.ssh`, `~/.config/gh/hosts.yml`) to the destination. The106skill prints a warning before transfer. Only use with trusted destinations.107108**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.109110## Invocation111112The slash command resolves to this skill's helper script, which is staged by113the bundle installer into `~/.amplihack/.claude/skills/migrate/scripts/`.114115```bash116bash "$AMPLIHACK_HOME/.claude/skills/migrate/scripts/migrate.sh" <hostname> [--session <id>]117```118119The script is idempotent: re-running against the same destination skips120already-installed toolchain, overwrites the active session-state on the121destination (source is authoritative until resume), and re-extracts122`~/.config/` / `~/.amplihack/` (cheap; ensures freshness).123124## See Also125126- Full documentation: [docs/skills/migrate.md](../../../docs/skills/migrate.md)127- `azlin` skill — destination provisioning and transport128- `remote-work` skill — related but does not copy credentials