Skip to content

About

migrate agent(claude, codex) session tool

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

Repository files navigation

AgentSessionMV

English | 简体中文

AgentSessionMV (asmv) moves one project directory and safely updates its Claude Code and Codex Session associations.

Why AgentSessionMV

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

Install from Source

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 --help

npm 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 --help

Usage

asmv [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.

Destination Semantics

Normal migrations follow Unix mv behavior:

  • If new-path is an existing directory, the project keeps its basename inside that directory.
  • If new-path does 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/myapp

Migrating Multiple Projects

AgentSessionMV 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
done

For 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
done

Each 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.

Safety Model

AgentSessionMV:

  1. Resolves the effective final path before provider discovery.
  2. Builds and validates provider plans before changing live data.
  3. Refuses target Session collisions instead of merging or overwriting them.
  4. Blocks a real matching Codex migration while Codex or its app-server is running.
  5. Creates one provider-namespaced backup for the project.
  6. Journals file and SQLite changes with before/after values and filesystem identity.
  7. Verifies the migration and rolls back in reverse persistence order on failure.
  8. Leaves concurrent or replacement data untouched when safe rollback cannot be proven.
  9. 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}/

Claude Code Data

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.

Codex Data

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.jsonl
  • external_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.

Requirements

  • 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

Development

npm install
npm test
node bin/asmv.js --help

# Link the current source globally
npm link
asmv --help

Origin and License

AgentSessionMV 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.

About

migrate agent(claude, codex) session tool

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages