codex-mover

codex-mover packages portable Codex and Claude Code history into a tarball and merges it into another machine's local data.

It is meant for moving useful context between machines without copying machine-local or account-local state.

Install

Run without installing:

npx @propel-code/codex-mover --help

Install globally:

npm install -g @propel-code/codex-mover
codex-mover --help

Run with Bun:

bunx @propel-code/codex-mover --help

Usage

codex-mover pack [--output ./codex-mover-archive.tar.gz] [--provider codex|claude|all]
codex-mover merge --input ./codex-mover-archive.tar.gz [--provider codex|claude|all] [--path-map /old=/new]

Commands print a JSON summary to stdout.

Examples

codex-mover pack --output ./context.tar.gz
codex-mover merge --input ./context.tar.gz
codex-mover merge --input ./context.tar.gz --provider codex
codex-mover merge --input ./context.tar.gz --path-map /old/workspace=/new/workspace

Options

• --input Archive path to merge in merge mode.
• --output, -o Archive path to create in pack mode. Defaults to ./codex-mover-<timestamp>.tar.gz.
• --provider codex|claude|all Package or merge a single provider or both. Default is all.
• --codex-home PATH Override the Codex home directory. Otherwise codex-mover uses $CODEX_HOME or ~/.codex.
• --claude-config-dir PATH Override the Claude config directory. Otherwise codex-mover uses $CLAUDE_CONFIG_DIR, ~/.claude, or ~/.config/claude.
• --path-map OLD=NEW Rewrite stored project paths during merge. Repeat this flag when multiple roots moved.
• --help, -h Print usage information.

What Gets Moved

By default, codex-mover includes portable history and context:

• Codex history: sessions/, archived_sessions/, history.jsonl, session_index.jsonl
• Codex context: memories/, automations/, AGENTS.md, rules/, policy/, skills/
• Claude Code: projects/, history.jsonl, todos/

What Stays Local

By default, codex-mover excludes machine-local and account-local state:

• Codex: auth.json, config.toml, caches, logs, sqlite state, shell snapshots, temp files, vendor imports, worktrees
• Claude Code: backups, caches, debug logs, plugins, settings.json, shell snapshots, stats caches

Merge Behavior

• JSONL history files are merged by unique line content.
• Session JSONL files prefer the imported copy when both sides identify the same session.
• --path-map rewrites Claude project paths and stored cwd and project references during merge.
• Conflicting non-appendable files are preserved as *.imported-<bundle> siblings instead of overwriting local data.

Development

bun install
bun test
bun run typecheck

Verification

bun run typecheck
bun test
bun run build
npx @propel-code/codex-mover --help
node dist/bin.js pack --provider codex --output /tmp/codex-mover.tar.gz
node dist/bin.js merge --input /tmp/codex-mover.tar.gz