open-index/open-npm huggingface dataset:
npm package: @propel-code/codex-mover
Description: Package and merge portable Codex and Claude Code history/context between machines.
Latest version: 0.1.2

# 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:

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

Install globally:

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

Run with Bun:

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

## Usage

```bash
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

```bash
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

```bash
bun install
bun test
bun run typecheck
```

## Verification

```bash
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
```