Import from another agent

If you are coming from another agent, you do not have to start empty. atomic-agent import reads the other agent’s state directory and copies what it can map into Atomic Agent’s own stores. Six sources are supported, and each one brings across a different set of things:

Source	Command	Imported by default	Opt-in with --migrate-secrets
Claude Code	atomic-agent import claude-code	Skills, memory, MCP servers, sessions	ANTHROPIC_API_KEY
Codex	atomic-agent import codex	Skills, instructions (AGENTS.md), sessions	OPENAI_API_KEY
Hermes	atomic-agent import hermes	Sessions, cron jobs	OPENROUTER_API_KEY, AIMLAPI_API_KEY
OpenClaw	atomic-agent import openclaw	Sessions, cron jobs	none
Pi	atomic-agent import pi	Skills, sessions	none
Oh-My-Pi	atomic-agent import oh-my-pi	Skills, MCP servers, sessions	none

Anything not in this table stays where it is. For example, skills, memory and MCP servers are not imported from Hermes or OpenClaw, and no source’s general config file is copied.

It is a one-shot migration, not a sync. Run it once when you switch, or again later to pick up what you left behind.

Developer Preview

Atomic Agent is a Developer Preview. Import options and report shapes can move between releases. Pin a release if you script this.

Start with a dry run

Always. --dry-run runs the full reconciliation — reading the source, matching against your existing sessions, detecting conflicts — and then writes nothing. You get the exact report the real run would produce, with none of the consequences.

atomic-agent import hermes --dry-run

1. Preview. Run with --dry-run and read the report: how many items of each kind would be imported, and how many conflicts.

2. Resolve conflicts. If items are flagged as conflicting, decide whether you want --overwrite or would rather leave your existing data alone.

3. Import. Re-run without --dry-run. You get an interactive confirmation unless you pass --yes.

Hermes

atomic-agent import hermes [--source DIR] [--preset default|full]
                           [--include a,b] [--exclude a,b]
                           [--migrate-secrets] [--limit N]
                           [--overwrite] [--dry-run] [--yes]

Flag	Default	Description
--source DIR	~/.hermes, or HERMES_STATE_DIR	Hermes state directory to read.
--preset default|full	default	What to import. default is sessions + cron.
--include a,b	—	Add options on top of the preset (sessions, cron).
--exclude a,b	—	Remove options from the preset.
--migrate-secrets	off	Also copy allowlisted provider keys into <stateDir>/.env. See below.
--limit N	no limit	Cap the number of sessions imported. Must be a non-negative integer.
--overwrite	off	Overwrite destinations that differ instead of flagging them as conflicts.
--dry-run	off	Preview only; never write.
--yes	off	Skip the interactive confirmation.

atomic-agent import hermes --dry-run
atomic-agent import hermes --yes
atomic-agent import hermes --migrate-secrets --overwrite

If your include/exclude combination leaves nothing selected, the command exits 1 with nothing selected to import rather than doing a silent no-op.

OpenClaw

atomic-agent import openclaw [--source DIR] [--agent NAME]
                             [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

Flag	Default	Description
--source DIR	~/.openclaw, or OPENCLAW_STATE_DIR	OpenClaw state directory to read.
--agent NAME	main	Which OpenClaw agent’s sessions to import.
--include a,b	—	Add options (sessions, cron).
--exclude a,b	—	Remove options.
--limit N	no limit	Cap the number of sessions imported.
--overwrite	off	Overwrite differing destinations.
--dry-run	off	Preview only.
--yes	off	Skip confirmation.

atomic-agent import openclaw --dry-run
atomic-agent import openclaw --agent main --yes

OpenClaw has no --preset

OpenClaw takes --include and --exclude but no --preset, and no --migrate-secrets: there are no OpenClaw keys to migrate.

Claude Code

atomic-agent import claude-code [--source DIR] [--include a,b] [--exclude a,b]
                                [--migrate-secrets] [--limit N]
                                [--overwrite] [--dry-run] [--yes]

Flag	Default	Description
--source DIR	~/.claude, or CLAUDE_CODE_STATE_DIR	Claude Code state directory to read.
--include a,b	all four	Add options (skills, memory, mcp, sessions).
--exclude a,b	none	Remove options.
--migrate-secrets	off	Also copy ANTHROPIC_API_KEY from the env block of settings.json into <stateDir>/.env.
--limit N	no limit	Cap the number of sessions imported, newest first.
--overwrite	off	Overwrite differing destinations.
--dry-run	off	Preview only.
--yes	off	Skip confirmation.

What each option maps to:

• skills: skill directories (skills/*/SKILL.md) are installed into Atomic Agent’s global skills directory.
• memory: auto-memory notes and CLAUDE.md become notes in memory.sqlite.
• mcp: the mcpServers entries from ~/.claude.json are added to mcp.servers in your config.
• sessions: transcripts (projects/*/*.jsonl) are copied into sessions.sqlite.

atomic-agent import claude-code --dry-run
atomic-agent import claude-code --exclude sessions --yes

Codex

atomic-agent import codex [--source DIR] [--include a,b] [--exclude a,b]
                          [--migrate-secrets] [--limit N]
                          [--overwrite] [--dry-run] [--yes]

Flag	Default	Description
--source DIR	~/.codex, or CODEX_STATE_DIR	Codex state directory to read.
--include a,b	all three	Add options (skills, memory, sessions).
--exclude a,b	none	Remove options.
--migrate-secrets	off	Also copy OPENAI_API_KEY from auth.json into <stateDir>/.env.
--limit N	no limit	Cap the number of sessions imported, newest first.
--overwrite	off	Overwrite differing destinations.
--dry-run	off	Preview only.
--yes	off	Skip confirmation.

Here memory means your AGENTS.md instructions, which become notes in memory.sqlite. Skills (skills/*/SKILL.md) go to the global skills directory, and rollouts (sessions/**/*.jsonl) go to sessions.sqlite. Codex has no MCP option.

atomic-agent import codex --dry-run
atomic-agent import codex --limit 50 --yes

Pi and Oh-My-Pi

atomic-agent import pi       [--source DIR] [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]
atomic-agent import oh-my-pi [--source DIR] [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

	Pi	Oh-My-Pi
Default --source	~/.pi/agent, or PI_STATE_DIR	~/.omp/agent, or OMP_STATE_DIR
Options	skills, sessions	skills, mcp, sessions
Skills	skills/**/SKILL.md	skills/*/SKILL.md
MCP servers	not imported	mcpServers from mcp.json
Sessions	sessions/*/*.jsonl	sessions/*/*.jsonl

Every option is selected by default; use --exclude to leave one out. Neither source has --migrate-secrets. The remaining flags work as they do for the other sources.

atomic-agent import pi --dry-run
atomic-agent import oh-my-pi --exclude mcp --yes

The subcommand is required

import on its own is not a command. Running it with no source prints the help text and exits 1:

atomic-agent import          # prints help, exits 1
atomic-agent import --help   # prints help, exits 0

An unrecognised source (atomic-agent import claude) also exits 1.

Imported sessions never collide

Sessions arrive with a namespace prefix (claude-code:, codex:, hermes:, openclaw:, pi: or oh-my-pi:), so an imported conversation can never overwrite a native Atomic Agent session that happens to share an id.

Conflicts are detected structurally, on the full transcript rather than just the identifier. Two consequences worth knowing:

• Re-running the same import is safe. Identical items are skipped and reported as duplicates, not written twice.
• An item flagged as a conflict genuinely differs in content. --overwrite replaces your side with the source’s; without it, your existing data wins and the difference is reported.
• Skills follow the same rule: a byte-identical skill is skipped, and a skill that differs from one you already have is flagged as a conflict.

Tip

Because import is idempotent on the source, --limit is a reasonable way to try it out. Import ten sessions, look at them in the TUI, then re-run without the limit to bring the rest across.

Migrating secrets

Three sources can bring a provider key with them. --migrate-secrets copies it into <stateDir>/.env, and only the keys in this list:

Source	Read from	Key
Claude Code	env block of settings.json	ANTHROPIC_API_KEY
Codex	auth.json	OPENAI_API_KEY
Hermes	Hermes .env	OPENROUTER_API_KEY, AIMLAPI_API_KEY

The allowlist is hard-coded. Any other variable in the source is ignored, as are allowlisted keys with empty values. OpenClaw, Pi and Oh-My-Pi have no key migration.

Secrets are never part of a preset

--migrate-secrets is the only way to move keys. No preset or default includes them, and --include secrets is rejected rather than quietly honoured. That is deliberate: copying credentials should be a thing you typed, not a thing a preset did for you.

The import report prints key names only, never values.

From the TUI

You do not have to use the command line. The TUI has an Import tab with the same six sources, reachable with the /import slash command:

atomic-agent tui
# → /import

The panel offers a preview (the same reconciliation as --dry-run) and an execute action that writes what you selected, including keys only when you ask for them. On first run, the onboarding screen also offers an import step when it finds one of these agents on your machine.

Related

CLI Reference Every command and flag, with import alongside the rest.

Why local-first Where imported sessions, tasks, and secrets land in the state directory.

Scheduling What imported cron jobs become once they are in the task queue.

Configuration config.json, .env, and the state directory layout.

Atomic Agent vs Hermes vs OpenClaw From the blog: how the three local agents compare, feature by feature.