Hermes Import Agent is the hermes import-agent command, which copies your existing Claude Code or Codex CLI setup into Hermes Agent with one command, and this page walks you through it step by step.
The Hermes CLI help calls it a "one-command import of another coding agent's setup into Hermes."
It moves your instructions, permission rules, MCP servers, skills and memories into their Hermes equivalents.
It always shows you a preview before it writes anything, and it never imports your API keys or credentials.
Nous Research has since packaged the command as an official plugin called agent-importers, and the v0.22.4 release notes say it now handles Cursor as well.
I'll also clear up the most common mix-up, which is that hermes import-agent and hermes import are two completely different commands.
When I covered Hermes v0.20 on agentos.guide, I put hermes import-agent claude-code in my setup steps as the one-line way to bring a Claude Code setup across.
The video below is about running Claude and Hermes side by side in my Agent OS, so treat it as context rather than a demo of this command.
Hermes Import Agent At A Glance: The Commands You Need
This table is the whole workflow on one screen, with every command copied from the official docs.
| Step | What you do | Command |
|---|---|---|
| 1 | You preview what would be imported without writing anything. | hermes import-agent claude-code --dry-run |
| 2 | You run the real import from Claude Code. | hermes import-agent claude-code |
| 3 | You import from Codex CLI instead. | hermes import-agent codex |
| 4 | You let Hermes auto-detect ~/.claude or ~/.codex. |
hermes import-agent |
| 5 | You point at a config folder in a custom location. | hermes import-agent codex --source /path/to/.codex |
| 6 | You replace conflicts and skip the prompts. | hermes import-agent claude-code --overwrite --yes |
| 7 | You pull in later changes from the other agent. | hermes import-agent --sync |
The full mapping lives on the official Import from Other Agents page in the Hermes docs.
What Hermes Import Agent Is
Hermes Import Agent is a migration command built into Hermes Agent, the free, open-source agent from Nous Research.
It reads the config folder of another coding agent and writes the matching pieces into your Hermes profile.
The docs say it "follows the same preview-first pattern" as hermes claw migrate, the older command for moving across from OpenClaw.
Here's the local CLI help, which you can check yourself with hermes import-agent --help.
usage: hermes import-agent [-h] [--source SOURCE] [--dry-run] [--overwrite]
[--yes] [--sync]
[{claude-code,codex}]
That's the output on my own machine, which runs Hermes v0.22.1, so the built-in command there lists Claude Code and Codex.
🔥 Want my exact Hermes Import Agent setup, step by step? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
The Problem It Solves
If you've spent months in Claude Code or Codex, your setup is worth a lot.
You've written global instructions, approved safe shell commands, wired up MCP servers and built skills.
Rebuilding all of that by hand in a new agent is slow, and you'll forget half of it.
Hermes Import Agent copies the parts that have a clean Hermes equivalent, so you start with your own rules instead of a blank profile.
It also lets you keep both agents, because the sync mode pulls in changes you make on the other side later.
Before You Start: Update Hermes And Take A Backup
Update Hermes first, because the import and sync features have improved across recent releases.
On a command-line install, the release notes say you run hermes update.
Then take a backup, so you have a restore point if you don't like the result.
hermes backup
That writes a full backup zip of your Hermes home, and my Hermes Agent backup guide covers the quick-snapshot options too.
Step 1: Preview The Import With A Dry Run
Always start with a dry run, because it shows you the full plan and writes nothing to disk.
hermes import-agent claude-code --dry-run
The docs say the command "prints the full plan before applying," and --dry-run "never touches disk."
Read the plan line by line, and look especially at the items it reports as conflicts or as not mapped.
Step 2: Run The Import From Claude Code
When the plan looks right, run the import for real.
hermes import-agent claude-code
Here's exactly what moves from Claude Code into Hermes, according to the official docs.
| Claude Code | Where it lands in Hermes |
|---|---|
CLAUDE.md global instructions |
Memory entries in ~/.hermes/memories/MEMORY.md |
permissions.allow Bash(...) rules in settings.json |
command_allowlist in config.yaml |
permissions.deny Bash(...) rules in settings.json |
approvals.deny in config.yaml |
mcpServers from ~/.claude.json and settings.json |
mcp_servers in config.yaml |
skills/<name>/ folders with a SKILL.md |
~/.hermes/skills/claude-code-imports/<name>/ |
commands/*.md slash commands |
They are skipped with a note telling you to convert them into skills. |
A Claude rule such as Bash(npm run test:*) becomes the Hermes glob npm run test*.
Rules that aren't Bash rules, such as Read(...) or WebFetch, gate Claude-only tools, so they're reported as unmapped rather than imported.
Step 3: Or Import From Codex CLI
The Codex import works the same way.
hermes import-agent codex
| Codex CLI | Where it lands in Hermes |
|---|---|
AGENTS.md global instructions |
Memory entries in ~/.hermes/memories/MEMORY.md |
[mcp_servers.*] in config.toml |
mcp_servers in config.yaml |
memories/*.md |
Memory entries in ~/.hermes/memories/MEMORY.md |
skills/<name>/ folders with a SKILL.md |
~/.hermes/skills/codex-imports/<name>/ |
If your Codex folder lives somewhere unusual, point at it with --source.
hermes import-agent codex --source /path/to/.codex
If you also want Codex to call Hermes, my Hermes MCP server setup for Codex covers the other direction.
Step 4: Handle Conflicts The Right Way
By default, the import skips anything that already exists in Hermes.
The docs say an MCP server or skill with the same name "is reported as a conflict," and you pass --overwrite to replace it.
hermes import-agent claude-code --overwrite --yes
I'd only use that line after a dry run, because --overwrite replaces your existing items and --yes skips the confirmation prompts.
Memory entries are merged and deduplicated against your existing MEMORY.md, and allowlist patterns merge with what's already in config.yaml.
A broken settings.json or config.toml becomes a per-item error in the report, and everything else still imports.
Step 5: Add Your Keys Back Deliberately
This is the step people miss, because Hermes Import Agent never brings your secrets across.
The docs say credential files such as ~/.claude/.credentials.json and ~/.codex/auth.json are never read.
MCP environment variables or headers with secret-looking names, such as anything ending in _TOKEN or _API_KEY, are stripped and listed in the report.
So after the import, you run hermes setup to configure your model providers, or you add secrets to ~/.hermes/.env.
Then you re-add the stripped MCP secrets one by one, which is safer than copying them blindly.
🔥 Want my Claude Code and Hermes setup, side by side? Inside the AI Profit Boardroom, I've got a full Hermes Agent course plus the Agent OS, which runs Claude and Hermes together with shared memory. You'll be learning alongside 3,400+ members with four coaching calls every week. → Get access here
Step 6: Keep Both Agents In Sync
You don't have to pick one agent and abandon the other.
Every successful import registers its source in ~/.hermes/import-sync.json, along with a digest of everything it read.
When you change your Claude Code or Codex setup later, you pull the changes in with one command.
hermes import-agent --sync # re-import every changed source
hermes import-agent --sync --dry-run # preview what a sync would do
The docs say sync is prompt-free and cheap, because unchanged sources are skipped by digest comparison.
That makes it safe to run on a schedule, such as a daily Hermes cron job.
The docs also set four rules for sync.
- Memory and config merges stay deduplicated, so a sync never duplicates entries you already have.
- Skills that
import-agentimported earlier are refreshed in place when the source copy changes. - Skills you created or edited yourself under the import category are never overwritten by a sync.
- Token refreshes in credential files never trigger a sync, and secrets are still stripped.
Sync into a second profile
The sync manifest is per profile, and the docs show how to carry it into a clone.
hermes profile create work --clone --sync-imports # also carry over the import-agent sync manifest
After that, hermes -p work import-agent --sync keeps that profile pulling from the same Claude Code or Codex folders.
Step 7: Importing From Cursor With The agent-importers Plugin
The Hermes Agent v0.22.4 release notes list "agent-importers (hermes import-agent, now with Cursor)" as new in the plugin catalog.
agent-importers is an official Nous Research plugin, and its README says the command was "formerly built into Hermes Agent core."
The README gives this install line.
hermes plugins install agent-importers
It then lists hermes import-agent cursor, which reads ~/.cursor.
From Cursor, it maps AGENTS.md and your User Rules into memory, mcp.json servers into config.yaml, and skill folders into skills/cursor-imports/.
Cursor's credential file, ~/.cursor/cli-config.json, is never read.
There's one compatibility note in the README you should know about.
It says that on a Hermes version that still has import-agent built in, the plugin's command stays inert and the built-in one runs.
So check hermes import-agent --help after installing, and if cursor isn't listed, your install is still using the built-in command.
Coming From OpenClaw Instead?
The docs point OpenClaw users to hermes claw migrate rather than hermes import-agent.
The newest agent-importers README also lists hermes import-agent openclaw as the new spelling of that same migration.
My Hermes Agent alternatives comparison covers how OpenClaw and Hermes differ if you're still deciding.
Hermes Import Agent vs Hermes Import: Don't Mix Them Up
The names are close, but the jobs are completely different.
| Command | What it does | What it reads | What it writes |
|---|---|---|---|
hermes import-agent |
It moves another agent's setup into Hermes. | It reads ~/.claude, ~/.codex or, with the plugin, ~/.cursor. |
It merges into memory, config.yaml and skills. |
hermes import |
It restores a Hermes backup zip. | It reads a zip made with hermes backup. |
It overwrites the matching files in your Hermes home. |
hermes profile import |
It imports an exported profile archive. | It reads a profile archive made with hermes profile export. |
It creates a profile from that archive. |
The docs describe hermes import as restoring "a previously created Hermes backup into your Hermes home directory."
Here's the docs example.
hermes import ~/hermes-backup-20260423.zip # Prompts before overwriting existing config
The docs warn you to stop the gateway before running it, and --force only skips the confirmation prompt.
Since v0.22.0, hermes import refuses damaged archives and leaves your Hermes home untouched.
So if you want to bring Claude Code across, use hermes import-agent, and if you want your old Hermes back, use hermes import.
Common Hermes Import Agent Problems And Fixes
| Problem | Why it happens | Fix |
|---|---|---|
| Nothing was written | Non-interactive sessions stop at the preview. | Pass --yes once you've checked the plan. |
| An MCP server or skill was skipped | It already existed in Hermes, so it was a conflict. | Re-run with --overwrite after a dry run. |
| An MCP server fails after import | Its secret environment variables were stripped. | Re-add the keys listed in the report. |
| Slash commands are missing | commands/*.md files have no direct Hermes equivalent. |
Convert them into skills by hand. |
Read(...) rules didn't import |
Non-Bash rules gate Claude-only tools. |
Set equivalent Hermes approvals yourself. |
If you want a second pair of eyes on a migration for your agency, you can book a free SEO strategy session with my team.
🔥 Want help moving your whole agent stack into Hermes? The AI Profit Boardroom has Hermes Agent training, the Agent OS and four weekly coaching calls where you can ask me how to migrate without breaking anything. → Join the AI Profit Boardroom
Related Reading
- How to set up Hermes Agent in one click
- Hermes Labs, Nous Research's experimental plugins
- Hermes Agent as an MCP server, and adding MCP servers to Hermes
Also On Our Network
- 🌐 How a team would use Hermes Import Agent to move its setup
- 🌐 Hermes Import Agent reviewed, with what moves and what doesn't
- 🌐 The Hermes Import Agent quick start for your Agent OS
- 🌐 Which model to run after you import, measured on GoldieBench
FAQ: Hermes Import Agent
What is Hermes Import Agent?
Hermes Import Agent is the hermes import-agent command, which imports a Claude Code or Codex CLI setup into Hermes in one command.
What is the difference between hermes import-agent and hermes import?
hermes import-agent brings another agent's setup into Hermes, while hermes import restores a Hermes backup zip.
Does hermes import-agent copy my API keys?
No, it doesn't, because credential files are never read and secret-looking MCP variables are stripped and listed.
How do I keep an imported setup in sync?
You run hermes import-agent --sync, which re-imports only the sources whose files changed.
Can hermes import-agent import from Cursor?
Yes, through the official agent-importers plugin, which lists hermes import-agent cursor in its README.
If you're planning a bigger move to agents across your business, book a free SEO strategy session and my team will help you plan it.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link-building agency, Goldie Agency, with 70+ people in Bangkok.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote the book "Link Building Mastery", which covers nine link building strategies.
- I run GoldieBench, where I score AI models on real one-shot builds.
→ Get my best AI training inside the AI Profit Boardroom
Back up, dry-run, import, add your keys back and switch on sync, and you'll have moved your whole setup with Hermes Import Agent.
