English | 简体中文
AgentSessionMV (asmv) moves one project directory and safely updates its Claude Code and Codex Session associations.
Moving or renaming a project can leave absolute paths behind in Claude Code and Codex data. AgentSessionMV resolves one final project path, discovers whichever supported providers reference the old path, and migrates those structured references as one guarded operation.
Provider selection is automatic:
| Matching data | Result |
|---|---|
| Claude Code only | Move the project and migrate Claude Code |
| Codex only | Move the project and migrate Codex |
| Both | Move once and migrate both providers |
| Neither | Move only the project directory |
Neither with --refs-only |
Successful no-op |
AgentSessionMV is currently distributed from its Git repository rather than the npm registry.
git clone https://github.com/life-go-on/asmv.git
cd asmv
npm install
npm link
asmv --helpnpm link installs the asmv command globally as a symbolic link to the cloned source directory. Pulling later changes updates the linked command without reinstalling the package.
You can also run the CLI directly without creating a global link:
node bin/asmv.js --helpasmv [OPTIONS] <old-path> <new-path>
Options:
--refs-only Only update references; new-path is the exact final project path
--dry-run Preview changes without executing
--keep-backup Keep backup after successful migration
--verbose Show detailed output (default)
--quiet Suppress detailed output
--help Show help
Each invocation accepts exactly one source project and one destination argument.
Normal migrations follow Unix mv behavior:
- If
new-pathis an existing directory, the project keeps its basename inside that directory. - If
new-pathdoes not exist, it is the exact final path, allowing move-and-rename in one operation. - A trailing
/requires an existing directory.
With --refs-only, no filesystem move occurs. The second argument is always the project's exact current path and never receives an automatic basename.
# Existing ~/work directory: result is ~/work/myapp
asmv ~/projects/myapp ~/work/
# Move and rename: result is ~/work/renamed-app
asmv ~/projects/myapp ~/work/renamed-app
# Rename without changing the parent directory
asmv ~/projects/myapp ~/projects/renamed-app
# Preview the complete plan
asmv --dry-run ~/projects/myapp ~/work/
# The project was already moved with regular mv
asmv --refs-only ~/projects/myapp ~/work/myappAgentSessionMV intentionally does not implement a multi-project transaction. Run one independent asmv process for each project, and preview every project first.
For zsh, *(/) matches directories only:
for project in ~/aaa/*(/); do
asmv --dry-run "$project" ~/bbb/ || break
done
for project in ~/aaa/*(/); do
asmv "$project" ~/bbb/ || break
doneFor bash:
for project in ~/aaa/*; do
[ -d "$project" ] || continue
asmv --dry-run "$project" ~/bbb/ || break
done
for project in ~/aaa/*; do
[ -d "$project" ] || continue
asmv "$project" ~/bbb/ || break
doneEach loop iteration has its own backup and rollback journal. If a later project fails, earlier successful migrations are not rolled back. Close Codex before the real loop when any project has matching Codex data.
AgentSessionMV:
- Resolves the effective final path before provider discovery.
- Builds and validates provider plans before changing live data.
- Refuses target Session collisions instead of merging or overwriting them.
- Blocks a real matching Codex migration while Codex or its app-server is running.
- Creates one provider-namespaced backup for the project.
- Journals file and SQLite changes with before/after values and filesystem identity.
- Verifies the migration and rolls back in reverse persistence order on failure.
- Leaves concurrent or replacement data untouched when safe rollback cannot be proven.
- Keeps the backup after every failed migration.
Successful backups are removed unless --keep-backup is supplied. Backup roots are stored under:
${TMPDIR}/asmv-backups/asmv-{timestamp}/
Supported Claude Code locations include:
~/.claude/
├── projects/{encoded-project-path}/
├── sessions/*.json
└── history.jsonl
AgentSessionMV renames the encoded project directory and updates known project path fields in project JSONL, active-session metadata, global history, and sessions-index.json. Session file modification times are preserved.
Claude Code path encoding replaces every non-ASCII-alphanumeric character with -. Encoded values longer than 200 characters use Claude Code's truncated form and hash suffix. Distinct paths that map to the same slug are rejected.
Supported Codex locations include:
~/.codex/
├── state_*.sqlite
├── sqlite/codex-dev.db
├── sessions/.../rollout-*.jsonl
├── archived_sessions/...
├── .codex-global-state.json
├── .codex-global-state.json.bak
└── config.toml
Path matching is boundary-safe: the exact old root and its descendants are migrated, while a lookalike such as /project-other is not.
Only allowlisted structured fields are changed. AgentSessionMV deliberately excludes:
~/.codex/history.jsonl~/.codex/session_index.jsonlexternal_agent_session_imports.json- messages, prompts, responses, content, and other free text
- unrelated rollout files
The JSON editor preserves unrelated bytes, including whitespace, escape spelling, and large numeric literals. SQLite updates use integrity checks, consistent backups, explicit transactions, stable row locators, and cell-level rollback journals.
Close Codex completely before a real migration. A dry-run reports the running-process condition but makes no changes.
- Node.js 18.0.0 or later for Claude-only migrations and plain project moves
- Node.js 22.5.0 or later when Codex SQLite data must be inspected or migrated
- macOS or Linux
- No runtime npm dependencies
npm install
npm test
node bin/asmv.js --help
# Link the current source globally
npm link
asmv --helpAgentSessionMV is an MIT-licensed derivative of ccmv, originally created by Saqoosha. The imported upstream baseline ends at commit 0b45d0e; later safety, transaction, Claude Code, Codex, and AgentSessionMV changes are maintained by life-go-on and other contributors.
See NOTICE for provenance and LICENSE for the complete MIT terms and copyright notices.