Import and Migration

Overview

When you switch to Autohand from another AI coding tool, you do not have to start from scratch. The import system reads configuration files from your previous tool, maps them to Autohand's format, and writes them to the appropriate locations in your Autohand setup.

The import process handles custom agents, configuration preferences, workspace instructions, and saved memory entries. Each source tool stores its data differently, so Autohand includes specific adapters for each one to ensure a clean translation.

Supported sources

Autohand supports importing from seven AI coding tools. Each source provides different types of data:

Agents are custom AI personas with specific instructions and tool permissions. Config includes model preferences, permission rules, and environment settings. Memory refers to saved context and project instructions. Skills are reusable prompt templates and workflows.

How to import

You can import using the interactive wizard or run it headlessly from the command line.

Interactive wizard

The easiest way to import is the built-in wizard. Start an Autohand session and run:

/import

Autohand scans your system for installed AI coding tools and shows you what it found. You then choose which source to import from and which categories to include. The wizard walks you through any conflicts and lets you review everything before writing files.

Headless import

For scripting or quick migration, run the import subcommand directly from the command line:

# Import everything from Claude Code
autohand import claude

# Import from Cursor
autohand import cursor

# Import from Codex
autohand import codex

# Import from all detected sources
autohand import --all

Auto-detection

When you run /import without specifying a source, Autohand checks common installation paths for each supported tool. It looks for configuration directories like ~/.claude/, ~/.cursor/, ~/.continue/, and others. If it finds multiple tools, you can choose which ones to import from.

What gets imported

Here is what Autohand reads from each category and where it places the imported data.

Custom agents

Agent definitions are converted to Autohand's Markdown-with-YAML-frontmatter format and placed in .autohand/agents/ for project agents or ~/.autohand/agents/ for global agents. The import preserves the agent's name, description, system prompt, and any tool permission rules.

# Source: ~/.cursor/agents/reviewer.json
# Imported to: ~/.autohand/agents/reviewer.md

Configuration preferences

Model preferences, permission rules, and environment variables are merged into your settings.json. Autohand maps the source tool's settings to their Autohand equivalents. For example, Cursor's preferred model setting becomes the model field in settings.json.

Workspace instructions

Project-level instructions (like Cursor's .cursorrules, Claude Code's CLAUDE.md, or Continue's .continue/ config) are converted to AGENTS.md files that Autohand loads at startup. If you already have an AGENTS.md, the imported instructions are appended under a clearly marked section.

Memory entries

Saved context and persistent memories are imported into Autohand's memory system. Each entry is tagged with its source tool so you can identify where it came from.

Dry-run mode

Before committing any changes, you can preview exactly what would be imported. The dry-run flag shows every file that would be created or modified without actually writing anything:

# Preview what Claude Code import would do
autohand import claude --dry-run

Example output:

Dry run: Import from Claude Code

Would create:
  ~/.autohand/agents/code-reviewer.md      (from ~/.claude/agents/code-reviewer.json)
  ~/.autohand/agents/docs-writer.md        (from ~/.claude/agents/docs-writer.json)
  .autohand/agents/project-helper.md       (from .claude/agents/project-helper.json)

Would modify:
  ~/.autohand/settings.json                (merge model preferences, permissions)
  .autohand/AGENTS.md                      (append workspace instructions from CLAUDE.md)

Would import 4 memory entries into the memory system.

No files were changed. Remove --dry-run to apply.

This is especially useful when importing from a tool you have used for a long time and are not sure how much data has accumulated.

Category-based import

If you only want to bring over specific parts of your setup, use the --categories flag to pick what to import:

# Import only agents
autohand import cursor --categories agents

# Import agents and config, skip memory and skills
autohand import claude --categories agents,config

# Import only memory entries
autohand import codex --categories memory

# Import skills from Claude Code
autohand import claude --categories skills

Available categories:

• agents - Custom agent definitions
• config - Settings, model preferences, permissions
• memory - Saved context and persistent memories
• skills - Reusable prompt templates and workflows

After importing

Once the import finishes, take a few minutes to verify and adjust your setup.

Verify imported agents

List your agents to confirm they were imported correctly:

# List all available agents
/agents

# Test a specific agent
/agents code-reviewer
"Review the latest commit for any issues"

Check configuration

Open the settings UI to review merged preferences:

/config

Look for any settings that may conflict with your existing Autohand configuration. The import tries to merge intelligently, but some values like the default model or permission rules may need manual adjustment.

Review workspace instructions

If you had project-level instructions in your previous tool, check your AGENTS.md to see how they were mapped:

cat .autohand/AGENTS.md

Imported instructions are placed under a heading that identifies the source, so you can easily edit or remove them.

Test your setup

Run a few typical tasks to make sure everything works as expected. If an imported agent or setting does not behave the way it did in your previous tool, you can edit the imported files directly since they are all standard Autohand configuration files.

Migration guides

Below are step-by-step instructions for the three most common migration paths.

From Claude Code

Claude Code stores its configuration in ~/.claude/ and project-level settings in .claude/ directories. The import maps these directly to Autohand's format:

# 1. Preview the import
autohand import claude --dry-run

# 2. Run the full import
autohand import claude

# 3. Verify your agents
/agents

# 4. Check that CLAUDE.md content moved to AGENTS.md
cat .autohand/AGENTS.md

Claude Code's CLAUDE.md files are converted to AGENTS.md entries. Custom slash commands become Autohand slash commands stored in .autohand/commands/. MCP server configurations are merged into your Autohand MCP settings.

From Cursor

Cursor keeps its configuration in ~/.cursor/ and uses .cursorrules for project-level instructions:

# 1. Preview the import
autohand import cursor --dry-run

# 2. Run the full import
autohand import cursor

# 3. Check that .cursorrules content moved to AGENTS.md
cat .autohand/AGENTS.md

# 4. Review model and permission settings
/config

Cursor's .cursorrules file becomes an AGENTS.md entry. Custom agent definitions in Cursor's settings are converted to Autohand's agent format. Model preferences and keyboard shortcuts are mapped to their Autohand equivalents where possible.

From Codex

Codex stores its configuration in ~/.codex/ and uses project-level AGENTS.md or codex.md files:

# 1. Preview the import
autohand import codex --dry-run

# 2. Run the full import
autohand import codex

# 3. Verify agents and memory
/agents
/memory

Codex agent files are already in a Markdown format similar to Autohand's, so the conversion is straightforward. Configuration preferences and sandbox settings are mapped to their Autohand equivalents.

Troubleshooting

• Source not detected - Make sure the source tool's configuration directory exists. For example, Claude Code needs ~/.claude/ to be present. If you used a non-standard install path, pass it with --import-path.
• Agent name conflicts - If an imported agent has the same name as an existing Autohand agent, the import wizard asks you to rename one of them. In headless mode, the imported agent gets a suffix like -imported.
• Settings conflicts - When a setting exists in both your Autohand config and the imported source, Autohand keeps your existing value by default. Use --overwrite to prefer the imported values instead.
• Partial import - If the import fails partway through, no files are left in a broken state. Autohand writes to temporary locations first, then moves everything into place as a single operation.

Frequently asked questions