docs/commands/migrate.md
Move or copy a project folder to a new location, preserving symlinks and AI sessions.
Relocates a project directory and automatically migrates Claude and Codex AI sessions so conversation history follows the project. Also relinks any ~/bin symlinks that pointed into the old path (move only).
# Move current directory into ~/code/lang/cpp/stream
cd ~/code/lang/cpp/stream
f migrate code stream
# Move current directory to an arbitrary path
f migrate ~/code/stream
# Move a specific source to a target
f migrate ~/code/lang/cpp/stream ~/code/stream
# Preview what would happen (no changes)
f migrate --dry-run code stream
# Copy instead of move (keeps original)
f migrate --copy code stream
To migrate ~/code/lang/cpp/stream to ~/code/stream:
cd ~/code/lang/cpp/stream
f migrate code stream
Or without cd:
f migrate ~/code/lang/cpp/stream ~/code/stream
Preview first with --dry-run:
f migrate --dry-run ~/code/lang/cpp/stream ~/code/stream
f migrate code <relative>Moves the current directory into ~/code/<relative>. This is the most common form.
cd ~/old/location/myproject
f migrate code myproject # -> ~/code/myproject
f migrate code lang/rust/mylib # -> ~/code/lang/rust/mylib
f migrate <target>Moves the current directory to <target> (any absolute or relative path).
cd ~/old/location/myproject
f migrate ~/code/myproject
f migrate <source> <target>Moves <source> to <target> without needing to cd first.
f migrate ~/code/lang/cpp/stream ~/code/stream
| Option | Short | Description |
|---|---|---|
--copy | -c | Copy instead of move (keeps the original intact) |
--dry-run | Show what would change without writing anything | |
--skip-claude | Skip migrating Claude Code sessions | |
--skip-codex | Skip migrating Codex sessions |
The project directory is moved (or copied with --copy) to the target path. Parent directories are created automatically. Cross-device moves are handled transparently (copy + delete).
Any symlinks in ~/bin that pointed into the old path are updated to point to the new location. Skipped when using --copy.
Claude and Codex store project sessions keyed by filesystem path. Migrate updates these so conversation history is preserved at the new location.
~/.claude/projects/ are renamed from the old path-based key to the new one..jsonl session files referencing the old path are updated in-place.A summary is printed showing how many session dirs/files were migrated.
# Move project into ~/code, nested path
cd ~/downloads/cool-project
f migrate code tools/cool-project
# Copy a project (keeps original)
f migrate --copy ~/code/app ~/backup/app
# Dry run to preview
f migrate --dry-run code stream
# Move without migrating AI sessions
f migrate --skip-claude --skip-codex ~/old/path ~/new/path
# Move and only migrate Claude (skip Codex)
f migrate --skip-codex code myproject
The target path must not exist. Remove or rename the existing directory first, or choose a different target.
Both paths resolve to the same location. Double-check your arguments.
After a move, you may see warnings like:
WARN Claude session dir still present: ...
WARN Codex sessions still reference the old path:
/path/to/file.jsonl
These mean some sessions couldn't be fully migrated. You can manually inspect or delete the referenced files.