Migrate from Claude Code or Codex

afk migrate brings compatible assets from Claude Code or Codex into AFK by recording trust settings. It does not move or copy your source installation: AFK reads the trusted directories again in future sessions, so later source changes can become visible without another migration.

Preview, grant trust, and verifyCopy Anchor Link

afk migrate --dry-run

afk migrate claude-code --dry-run
afk migrate codex --dry-run

afk migrate claude-code

afk migrate claude-code --mcp --dry-run

afk doctor
afk

/skills
/agents
/mcp
/tools

What gets importedCopy Anchor Link

Codex home defaults to ~/.codex; an absolute CODEX_HOME override is honored. Source plugin enabled/disabled state is consulted during discovery.

For Claude Code MCP, detection checks ~/.claude/mcp.json, ~/.claude/.mcp.json, and ~/.claude/claude-code/mcp.json, using the first existing candidate. It is not a universal scan of every historical Claude Code configuration location. If your servers are not detected, configure them directly in AFK's mcp.json.

Migration is not a conversion of chat history, active sessions, goals, memory, permission policy, provider settings, or all source-tool preferences. Configure those deliberately in AFK. Authentication reuse is a separate provider feature, not evidence that migration copied credentials.

Where trust is storedCopy Anchor Link

The command updates user-global afk.config.json with an importFrom block such as:

{
  "importFrom": {
    "claude-code": {
      "plugins": true,
      "skills": true,
      "mcp": false
    }
  }
}

The actual booleans depend on detected assets and flags. Project-local configuration cannot grant this trust. Repeated migrations add permissions but do not silently clear an earlier opt-in, so rerunning without --mcp does not revoke a previous MCP grant.

To stop importing an asset type, change its toggle in user-global configuration and start a new session. Removing that trust does not uninstall or delete the source tool's files.

Compatible command and skill filesCopy Anchor Link

Claude Code plugin commands/*.md files become user-invoked slash commands:

Names come from paths, not a name frontmatter field. Plain Markdown command bodies can work without frontmatter. Commands appear in /skills, but are not automatically added to the model-facing skill-routing catalog. Collision handling may expose a namespaced command, so inspect the listing rather than assuming a bare name wins.

For skills/<name>/SKILL.md, when-to-use describes when the model should choose the skill:

---
name: review-schema
description: Review a database schema change
when-to-use: When a task changes tables, indexes, or migration ordering
---

Read the migration and verify its rollback plan before recommending approval.

whenToUse and when_to_use are also recognized spellings. The hint is routing context, not a deterministic trigger or a guarantee that a skill runs automatically. Other supported fields, such as allowed tools and model selection, still need to match the capabilities available in AFK.

Use /reload-plugins after editing Markdown skill or command files. JavaScript plugin entrypoints run once per process; restart for changes to executable setup code.

Hook compatibility is selectiveCopy Anchor Link

AFK understands Claude Code-style command-hook groups and common tool-name matchers:

A hook's timeout is interpreted as seconds when timeout_ms is absent. timeout_ms takes precedence, and the effective command-hook timeout is capped at 30 seconds. Explicit regex flags that maintain match state are stripped.

Only type: "command" entries are supported by this configuration loader. Claude Code hook types such as http, mcp_tool, prompt, and agent are skipped with a warning. Shell commands that depend on another tool's payload fields or directory layout may still need adaptation.

Installed plugin hooks/hooks.json files require the separate user-global enablePluginHooks: true trust setting. User-authored AFK shell hooks use enableShellHooks; project hooks also need allowProjectHooks. Migration does not blindly copy Claude Code's global settings hooks into AFK. Review those definitions and place them in AFK's supported configuration layers if needed.

Differences to expectCopy Anchor Link

1. AFK is a separate runtime with its own configuration and state under ~/.afk/. Imported directories are trusted sources, not the new location of AFK's own state.
2. Tool names and available tools differ. Compatibility aliases help with hook matchers and skill metadata, but a prompt that requires an unavailable tool must be revised.
3. Provider and model choices matter. A workflow written for Claude may run through an OpenAI-compatible endpoint in AFK, with different vision, context, and tool-call capabilities.
4. Imported plugin code can execute at activation. Review manifest main, MCP commands, and hooks as code, not merely as documentation.
5. Session and checkpoint portability is not implied. Finish or preserve work in the original tool, then start an AFK session with an explicit task and relevant files.

RelatedCopy Anchor Link