agentmove

Move your AI agent between clients — the pandoc of agent ecosystems, so switching tools never means losing your agent's brain.

For anyone switching or mixing agent clients: migrate config + MCP servers + skills + memory + persona/instructions between forty-seven clients — OpenClaw, Hermes Agent, Claude Code, Codex CLI, Cursor, Gemini CLI, VS Code, Cline, Continue, and more (see the full table below) — in any direction, with dry-run previews, diffs, and honest loss reporting.

Existing migration tools (like hermes claw migrate) are one-way doors into a single vendor. agentmove is neutral, local-only, and open source: your agent's brain belongs to you.

Quick start

The npm package is agentmove-cli (the bare agentmove name collides with an existing package under npm's hyphen-insensitive naming rules), but the installed command is still agentmove:

npm install -g agentmove-cli   # installs the `agentmove` command
agentmove doctor

Or one-off with npx:

# See which agent clients live on this machine and what can be migrated
npx agentmove-cli doctor

# Preview a migration (nothing is written without --apply)
npx agentmove-cli convert openclaw hermes

# Actually migrate (existing files are backed up to ~/.agentmove/backups first)
npx agentmove-cli convert openclaw hermes --apply

# Or go through a portable bundle you can commit / carry to another machine
npx agentmove-cli export claude-code -o my-agent
npx agentmove-cli import codex -i my-agent --apply

# Compare two clients (or a bundle vs a client) layer by layer
npx agentmove-cli diff claude-code codex

# Partial migration: only the layers you ask for
npx agentmove-cli convert claude-code codex --only mcp --apply

# Project-scoped migration: .mcp.json / CLAUDE.md / .cursor/rules / GEMINI.md / AGENTS.md
npx agentmove-cli convert claude-code cursor --project . --apply

What gets migrated

Every lossy or approximated step is reported as a warning — nothing is silently dropped. Likely secrets (env/header values named *KEY*, *TOKEN*, *AUTHORIZATION*, …) are replaced with ${VAR} placeholders — in the portable MCP list and recursively throughout the raw config snapshot kept in the bundle — unless you pass --include-secrets.

What does NOT migrate (honest edition)

• Cursor memories live in the app's internal database — cannot be exported or imported.
• Claude Code / Codex client-managed memories are not exported; imported memory is appended to the instructions file (CLAUDE.md / AGENTS.md) as an approximation, not written into the client's own memory store.
• Persona is native only in OpenClaw/Hermes (SOUL.md); everywhere else it's appended to instructions and flagged approximated.
• MCP tool filters (OpenClaw toolFilter, Hermes include/exclude) have no portable equivalent — dropped with a warning.
• OpenClaw / Hermes have no project-scoped files — --project covers claude-code, codex, cursor, gemini, windsurf, cline (.clinerules/ + .cline/skills/ + .clinerules/workflows/), zed (.zed/settings.json + .rules + .agents/skills/), openhands, copilot (.mcp.json + .github/instructions/ + .github/skills/ + .github/agents/ + .claude/commands/), opencode, qwen, amp (.amp/settings.json workspace servers), vscode (.vscode/mcp.json + .github/copilot-instructions.md + .github/skills/ + .github/prompts/), kiro (.kiro/settings/mcp.json + .kiro/steering/ + .kiro/skills/ + .kiro/prompts/), roo (.roo/mcp.json + .roo/rules/ + .roo/skills/ + .roo/commands/), continue (.continue/mcpServers/ blocks + .continue/rules/ + .continue/skills/ + .continue/prompts/), crush (crush.json/.crush.json + CRUSH.md + .crush/skills/ + .crush/commands/), antigravity (.agents/mcp_config.json + .agents/rules/ + .agents/skills/), droid (.factory/mcp.json + AGENTS.md + .factory/skills/ + .factory/commands/), amazonq (.amazonq/mcp.json + AmazonQ.md + .amazonq/prompts/), warp (.warp/.mcp.json + AGENTS.md + .warp/skills/), junie (.junie/mcp/mcp.json + .junie/AGENTS.md + .junie/skills/), trae (.trae/mcp.json + .trae/rules/ + .trae/skills/ + .trae/commands/), jetbrains (.ai/mcp/mcp.json + .aiassistant/rules/), comate (.comate/mcp.json + .comate/rules/ + .comate/skills/), codebuddy (.mcp.json + CODEBUDDY.md + .codebuddy/skills/ + .codebuddy/agents/ + .codebuddy/commands/), qoder (.mcp.json + AGENTS.md + .qoder/skills/ + .qoder/agents/ + .qoder/commands/), auggie (.augment/settings.json + .augment/rules/ + .augment/skills/ + .augment/commands/ + .augment/agents/), kilo (kilo.json/.kilo/kilo.json + AGENTS.md + .kilo/skills/ + .kilo/commands/), kimi (.kimi-code/mcp.json + AGENTS.md + .kimi-code/skills/ + .kimi-code/agents/ + .agents/agents/), cortex (.cortex/mcp.json + AGENTS.md + .cortex/skills/), librechat (librechat.yaml in the deployment directory), muse (root AGENTS.md + .agents/skills/ + .agents/memory/), warp-cli (root AGENTS.md/WARP.md + .agents/skills/), and goose (.goosehints/.goose/memory/.agents/skills/.goose/recipes; goose extensions are user-scoped only).
• Cline VS Code extension keeps its own MCP settings copy in VS Code globalStorage — only the CLI settings file (~/.cline) and global rules are migrated. Skills migrate natively (~/.cline/skills/, project .cline/skills/).
• Windsurf Cascade memories are app-managed — cannot be exported or imported; durable rules live in global_rules.md (migrated as instructions). Skills migrate natively (~/.codeium/windsurf/skills/, project .windsurf/skills/).
• Zed Rules Library entries are app-managed — not migrated; personal instructions live in ~/.config/zed/AGENTS.md. Skills migrate natively (~/.agents/skills/, project .agents/skills/). JSONC comments in Zed's settings.json are not preserved on rewrite (warned).
• OpenHands remote MCP servers only support api_key auth — non-Bearer headers are dropped with a warning; per-server timeout has no portable equivalent. Skills migrate natively from ~/.agents/skills/ plus the legacy ~/.openhands/skills/ (.agents/skills wins duplicate names; project .agents/skills/ + .openhands/skills/ with --project); imports write .agents/skills/. The managed ~/.openhands/skills/installed/ store is not exported (warned).

Full details: Limitations.

Supported clients

Commands

• agentmove export <client> [-o dir] — client → portable bundle
• agentmove import <client> [-i dir] [--apply] — bundle → client (dry-run by default)
• agentmove convert <from> <to> [--apply] — direct client → client
• agentmove pack <bundle> [-o file] / agentmove unpack <file> — encrypt a bundle into a single portable .agentpack file (AES-256-GCM, passphrase from AGENTMOVE_PASSPHRASE) for carrying an agent across machines; import -i accepts .agentpack files directly
• --only mcp,skills,… (on export/import/convert) — partial migration of just the listed layers (mcp, skills, memory, instructions, persona)
• --project <dir> (on export/import/convert) — migrate the client's project-scoped files in a repo (.mcp.json/CLAUDE.md, AGENTS.md, .gemini/settings.json/GEMINI.md, .cursor/mcp.json/.cursor/rules, .windsurf/rules, .clinerules, .zed/settings.json/.rules, .openhands/microagents+.openhands/skills, .mcp.json+.github/copilot-instructions.md for copilot, opencode.json+AGENTS.md+.opencode/skills+.opencode/agents for opencode, .qwen/settings.json+QWEN.md+.qwen/skills+.qwen/agents for qwen) instead of user-scoped config; openclaw/hermes have no project scope
• --mif <file> (on export) / import <client> --mif <file> — exchange the memory layer as a vendor-neutral MIF v2 document with any MIF-speaking memory system
• export <client> --plugin — write an Agent Plugin (plugin.json + skills/ + mcp.json with explicit transport types) instead of an agentmove bundle; import -i auto-detects Agent Plugin directories, so any plugin from the ecosystem can be imported into all supported clients (instructions/persona/memory have no plugin slot and are warned about)
• export <client> --mcp-json <file> — also write the MCP layer as a standalone standard mcp.json (explicit type on every entry, secrets redacted by default) — a shareable canonical server list for a team or any mcpServers-speaking tool
• import <client> -i mcp.json — import a standalone MCP config file (any mcpServers map: an Agent Plugins mcp.json, a Claude-style .mcp.json, a canonical team server list, …) directly into any client; transports are taken from type/transport or inferred from command/url with a warning
• import <client> -i <url> — import straight from an http(s) URL: a .json URL is fetched as a standalone MCP config, any other URL is git cloned and auto-detected as an Agent Plugin, agentmove bundle, or skills repository; a GitHub-style /tree/<branch>/<dir> (or GitLab /-/tree/) URL imports just that directory, a blob link to a .json file fetches the raw file, and a .zip/.tgz/.tar.gz URL (release asset, "Download ZIP" link) is downloaded and extracted — local archive files work too
• export <client> --plugin -o my-plugin.zip — package the plugin as a ready-to-publish archive (.zip/.tgz/.tar.gz), e.g. a release asset
• import <client> -i <repo> — import a skills repository (the skills.sh / npx skills add owner/repo ecosystem): SKILL.md directories under skills/, namespaced under skills/<scope>/ (the gh skill convention), at the top level, or a single skill at the repository root, installed into any client's skills location
• export <client> --skills-repo <dir> — also write the skills layer as a skills repository (skills/<name>/SKILL.md), ready to commit and publish with gh skill publish or install with npx skills add; a path ending in .zip/.tgz/.tar.gz writes it as an archive; gh skill install source-tracking metadata (metadata.github-*) is stripped with a warning so the result passes gh skill publish validation
• agentmove diff <from> <to> — layer-by-layer comparison
• agentmove doctor — detect installed clients and inventory migratable data
• agentmove clients — list supported clients and default config locations
• agentmove completion <bash|zsh|fish> — shell completion script

All data commands accept --json for machine-readable output (plans, warnings, per-layer summary) — handy in scripts and CI. A global install also links a man page (man agentmove-cli), and --debug (or AGENTMOVE_DEBUG=1) prints a stack trace on unexpected errors.

Safety model

1. Dry-run by default — import/convert print a plan; --apply is explicit.
2. Automatic backups — every file that would be overwritten is copied to ~/.agentmove/backups/<timestamp>/ first.
3. Merge, don't clobber — imported MCP servers merge into the target's existing list (like the official mcp add commands); nothing the target already has is removed unless you pass --replace-mcp.
4. Secrets stay put — redacted to ${VAR} placeholders unless --include-secrets is passed.

Exit codes: 0 success · 1 unexpected error · 2 usage error · 3 bad input data (messages include the offending file path).

Development

pnpm install
pnpm build && pnpm lint && pnpm typecheck && pnpm test

Adapters are plugins: implement the ClientAdapter interface in packages/agentmove/src/adapters/ and register it in adapters/index.ts. Research behind the format mappings lives in docs/research/ (proposal, competitive comparison, and the per-client format matrix).

License

Apache-2.0