Claude Code teleport safety: protect local work before handoff

A session handoff is a filesystem operation, not just a conversation change.

Published . If you move Claude Code work between sessions or machines, the important question is not whether the conversation arrives. It is whether the destination repository still contains everything you had before the move. A small release-note entry gives developers a concrete reason to inspect that boundary before trusting a convenient handoff.

What the Claude Code changelog actually confirms

Anthropic's version 2.1.290 changelog says it fixed claude --teleport and /teleport deleting files inside a directory that had replaced a tracked file of the same name when the user chose to stash. The stated remedy is specific: the unsafe stash is now refused, with an explanation. That is a guard against one destructive path, not a promise that every interrupted handoff is recoverable.

For example, suppose Git tracks a file named fixture. Locally, you replace it with a directory named fixture containing new work. Git's recorded path and the filesystem's current path now represent different kinds of objects. The release note describes that shape of collision, not ordinary edits to an existing source file. Do not generalize it into a claim that every stash deletes data, or that all Claude Code sessions are affected.

This is an October 18 editorial finding, not an assertion that 2.1.290 shipped today. The pinned changelog verifies the fix description; it does not establish your installed binary, rollout channel, or the behavior of a customized environment. We have not run a live Claude Code teleport reproduction for this guide. The rehearsal below is a proposed acceptance test, not a benchmark or a claim of hands-on product validation.

Before teleport: inventory the destination, not just the session

Pause other agents and file watchers that can write to the checkout. Then inspect the destination repository before approving any stash or branch transition. These read-only commands provide a useful starting inventory; run them from the repository root, and inspect their output locally rather than uploading it to a chat or issue:

claude --version
git status --short --branch
git diff --stat
git diff
git diff --cached
git ls-files --others --exclude-standard
git status --short --ignored

Record the client version alongside the handoff result. The distinction between staged, unstaged, untracked, and ignored files matters. A source diff alone will miss an untracked migration draft or an ignored local dataset. The Git stash documentation distinguishes ordinary stash behavior from options that include untracked or ignored files. Do not assume the agent's stash prompt includes those options, and do not enable broader collection without checking what it would capture.

Preserve valuable work independently before proceeding. A reviewed local commit can protect appropriate tracked changes, but do not blindly stage everything: credentials and private configuration do not belong in Git. Use an approved backup location outside the working tree for other necessary files, retain access controls, and verify that the copy is readable. A patch is useful for review, but it is not a complete backup of untracked files, ignored files, or external state.

If a path changed from file to directory, resolve that layout intentionally before attempting the handoff again. Stop on a stash refusal; do not treat it as permission to delete the directory or force a reset. A clean checkout is useful only after you know how the dirty checkout's work was preserved.

A disposable-repository test for the exact collision

Use a scratch directory with synthetic data, not a production checkout. The following POSIX-shell example creates a tracked file, moves its original bytes aside, and replaces its path with a directory. It does not invoke teleport, change your real project, or require a remote repository:

mkdir teleport-rehearsal
cd teleport-rehearsal
git init
printf 'tracked baseline\n' > fixture
git add fixture
git -c user.name=Rehearsal -c user.email=rehearsal@localhost commit -m "Add fixture"
mv fixture fixture.original
mkdir fixture
printf 'untracked work to preserve\n' > fixture/note.txt
git status --short
sha256sum fixture.original fixture/note.txt

Start in an empty scratch parent directory so the first mkdir succeeds; stop if any command fails. Save the two hashes outside this scratch checkout. On systems without sha256sum, use the operating system's SHA-256 utility. The key assertion is byte preservation, not a particular checksum command. In our setup check, Git reported the deleted tracked file and the untracked moved original, but did not list fixture/note.txt. Inspect the replacement directory directly: Git status alone is not a complete filesystem inventory in this collision.

If your account and environment support the relevant teleport flow, create a synthetic source session using the product's current instructions. Attempt the handoff into this prepared destination and exercise the stash choice only inside this disposable test. The expected behavior described by the 2.1.290 fix is refusal with an explanation while both synthetic files remain unchanged. Record the message, installed version, before-and-after Git status, and hashes. If the setup cannot reach that choice, mark the test unexercised—not passed.

Do not install an older vulnerable client just to obtain a failure screenshot. Test the supported build you intend to deploy. Follow this collision case with an ordinary tracked edit and an ordinary untracked file so your check distinguishes a safe refusal from a generally broken handoff. Use a clean destination as a control, and keep test accounts, credentials, and network access restricted.

If work is missing, stop changing the evidence

Stop the agent and any process still writing into the directory. Avoid repeated teleport attempts, stash operations, destructive cleanup, or checkout resets. Preserve the remaining working tree, Git metadata, and relevant session logs to an access-controlled recovery location before experimenting. Session logs and diffs can contain proprietary code or secrets; redact them before requesting public support.

Inspect the backup, local commits, and available stash entries without applying anything over the affected checkout. Recover into a separate directory first and compare the result against your inventory. If a lost file was never tracked, committed, stashed, or backed up, Git history may have no copy to recover. Do not promise a reflog command can restore arbitrary untracked content.

A conversation transcript is not a backup. Do not assume /rewind can undo shell commands, database writes, dependency changes outside the checkout, or actions taken through a remote service. Treat each external system as a separate recovery boundary until its own rollback mechanism has been verified. This guide deliberately does not assert current checkpoint coverage or retention limits: the official documentation could not be retrieved during this research pass.

What this changes for teams using Claude Code alongside Codex or Copilot

The useful comparison is ownership of state, not which model sounds more confident. In a mixed Claude Code, Codex CLI, and Copilot workflow, give each concurrent writer its own checkout or worktree, then review changes through ordinary version control. The Git worktree documentation explains separate working trees; a worktree is not a sandbox and does not isolate credentials, network access, or external services.

For a small pilot, record ten handoff attempts: version, starting Git state, whether the operation completed or refused, whether all sentinel hashes matched, and minutes needed to resume productive work. Ten is a suggested trial size, not measured evidence. Any missing sentinel is a stop condition. An explained refusal that preserves work is a better outcome than apparent success followed by an hour of reconstruction.

Keep the same human review and CI checks after a successful handoff. File preservation does not prove the generated code is correct. For broader tool selection, see our Claude Code vs Codex CLI workflow comparison; for parallel-session supervision, see Copilot worktrees vs Claude Code Needs input. This narrower rule comes first: protect local state before optimizing how quickly an agent can take over.

Sources and evidence limits