Agent Config Migrate

agent-migrate 0.6.1 inventories, sanitizes, converts, imports, transfers, and synchronizes configuration among Codex, Pi, and Claude Code. It supports local homes, explicit project workspaces, and SSH config Host aliases. Credentials, sessions, history, telemetry, caches, and control state are never exported.

中文完整使用说明：docs/usage.zh-CN.md

Install

Install the published crate from crates.io:

cargo install ethan-acm
agent-migrate --version

The crates.io package is named ethan-acm; it installs the agent-migrate executable. Rust 1.88 and pnpm 11 are required to build the complete repository from source.

pnpm --dir resources/pi-mcp-bridge install --frozen-lockfile
pnpm --dir resources/pi-mcp-bridge run check
cargo build --release
install -m 0755 target/release/agent-migrate ~/.local/bin/agent-migrate

Endpoints And Scope

Endpoints use <agent>@<host>, where agent is codex, pi, or claude and host is local or a validated SSH config Host alias. Examples are codex@local and pi@lab-linux. Project operations require --scope project and an explicit --workspace; discovery never walks above that directory.

Global options include --format human|json, --root, --workspace, --state-root, and --dry-run. JSON results use schema 1.0. Dry runs do not lock, snapshot, write, transfer, start a bridge, or invoke a conversation.

Commands

agent-migrate scan <endpoint> [--scope global|project]
agent-migrate export <endpoint> --output bundle [--scope ...]
agent-migrate convert --input bundle --target <agent> --output converted-bundle
agent-migrate diff --input bundle --target <agent>
agent-migrate import <endpoint> --input bundle [--map /source=/target]
agent-migrate transfer --input bundle.age --host <ssh-alias>
agent-migrate sync <source> <target> [--source-root ... --target-root ...]
agent-migrate doctor <endpoint> [--scope global|project] [--conversation]
agent-migrate rollback <snapshot-id>
agent-migrate watch <source> <target>
agent-migrate repo init|snapshot|status ...
agent-migrate recommend [--host <ssh-alias>]
agent-migrate completions bash|zsh|fish

--map is repeatable. It rewrites declared absolute path fields in structured settings and MCP resources using component-boundary matching. Both sides must be normalized absolute paths. An absolute path field that is in mapping mode but has no matching declaration blocks import.

Use --accept-lossy for resources reported as lossy or preserved_unavailable. Pi MCP conversion additionally requires --bridge-healthy; the generated Pi extension uses the bundled MCP SDK bridge and starts only servers declared in its sanitized configuration.

Bundle And Secrets

Bundle schema 1.0 uses an inspectable directory with manifest.yaml, typed resource directories, and secrets.ref.yaml. It stores SHA-256 for every file, sanitized content, path mappings, and logical secret references. A single-file .yaml wire format remains accepted for compatibility and encrypted transport. Secret values are replaced with ${SECRET_REF:NAME}. There is no include-secrets mode. Encrypted transfers use age X25519 recipients, deterministic tar metadata, SFTP staging named by ciphertext SHA-256, and fixed JSON requests over agent-migrate remote serve.

SSH uses the local OpenSSH configuration, SSH Agent, ProxyJump, and host-key policy. Password flags, shell endpoints, arbitrary remote commands, automatic package installation, and disabled host-key checks are not available. The same major version of agent-migrate must be installed remotely.

Transactions And Recovery

Imports take a target-scoped advisory lock, reject conflicts by default, snapshot every touched path with its hash and mode, atomically replace files, and automatically restore the snapshot after write or doctor failure. --conflict replace permits known targets to be replaced. merge is limited to structured JSON, TOML, or YAML; rename applies to named skills, commands, and agents. Successful imports write JSON and Markdown reports under the state root. The import result returns a snapshot ID:

agent-migrate --root /target --state-root /state rollback <snapshot-id>

Encrypted staging is removed after a successful import. A failed remote operation reports a fixed agent-migrate remote cleanup <sha256> recovery command while retaining only encrypted data.

Exit Codes

Quality Gates

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo nextest run --workspace --all-features
cargo deny check
cargo machete
pnpm --dir resources/pi-mcp-bridge run check
scripts/check-file-size.sh
cargo build --release

tests/integration/ssh_roundtrip.sh drives real OpenSSH/SFTP against the Docker Linux fixture in both directions. tests/integration/real_agents.sh runs the opt-in exact-marker conversation against installed authenticated Agents without migrating their authentication or persisting sessions. tests/integration/release_surface.sh drives every local command through the release binary and includes the isolated secret, symlink, and shell-injection probes in tests/security/release_security.sh.