ookEvents: Record<string, number>; mcpServers: { cli: string[]; desktop: string[] }; plugins: { name: string; type: 'bundled' | 'local' }[]; customCommands: string[]; permissionRules: { allow: string[]; deny: string[]; prompt: string[] }; sessionCount: number; secretReferences: string[]; // Names only, never values }

function scanAgentEnvironment(rootDir: string): InventoryReport { const report: InventoryReport = { instructions: [], hookEvents: {}, mcpServers: { cli: [], desktop: [] }, plugins: [], customCommands: [], permissionRules: { allow: [], deny: [], prompt: [] }, sessionCount: 0, secretReferences: [] };

// Traverse .claude/ directory structure const claudeDir = join(rootDir, '.claude'); if (statSync(claudeDir, { throwIfNoEntry: false })) { // Parse settings.json for hooks & permissions // Parse commands/ for custom slash workflows // Parse agents/ for subagent definitions // Extract secret variable names from env references }

return report; }

**Architecture Rationale:** Separating secret names from values forces explicit credential rotation in the target environment. It prevents automated migration scripts from accidentally committing sensitive data to Git history. The inventory acts as a contract between source and target, ensuring no component is silently dropped.

### Phase 2: Policy & Hook Translation

Hooks encode the safety model. They intercept tool execution, enforce filesystem boundaries, and trigger post-action validations. Copying hook JSON directly fails because event names, payload structures, and execution contexts differ between CLIs.

Map hooks by intent, not syntax:

| Source Event | Target Event | Translation Strategy |
|--------------|--------------|----------------------|
| `PreToolUse.Bash` | `PreToolUse.Bash` | Direct mapping; validate command allowlists |
| `PreToolUse.Edit` | `FileWrite` | Convert patch logic to target diff format |
| `PermissionRequest` | `ApprovalPolicy` | Map to on-request or sandbox mode |
| `SessionStart` | `Lifecycle.Init` | Trigger environment warmup scripts |
| `Stop` | `Lifecycle.Terminate` | Run cleanup or state serialization |

```json
// codex-hooks.json
{
  "version": "2.1",
  "routing": {
    "PreToolUse": {
      "bash": {
        "handler": "scripts/validate-bash.sh",
        "timeout_ms": 5000,
        "fail_policy": "block"
      },
      "file_write": {
        "handler": "scripts/check-diff-scope.js",
        "allowed_paths": ["src/", "lib/"],
        "blocked_patterns": ["*.env", "node_modules/"]
      }
    },
    "Lifecycle": {
      "init": {
        "handler": "scripts/warm-cache.sh",
        "async": true
      }
    }
  }
}

Architecture Rationale: Hooks should be idempotent and fail-safe. Blocking on validation errors prevents unsafe tool execution. Async lifecycle hooks prevent startup latency from blocking the main agent loop. Explicit path allowlists reduce the blast radius of file operations.

Phase 3: MCP Server Scoping & Environment Forwarding

MCP servers expose external tools to the agent. Claude Code and Codex handle server discovery differently. Crucially, desktop MCP connectors must never be migrated to CLI environments. They operate under different threat models, consume different context windows, and often expose GUI automation tools irrelevant to terminal workflows.

Extract only CLI-scoped servers:

# Source environment extraction
claude mcp list --scope cli > cli-servers.txt
claude mcp get <server-name> --format json > server-def.json

Translate to target configuration with environment forwarding:

# .codex/config.toml
[mcp_servers.documentation]
command = "npx"
args = ["-y", "@acme/docs-mcp@latest"]
env_forward = ["DOCS_API_KEY", "DOCS_BASE_URL"]
timeout_seconds = 30
retry_policy = "exponential"

[mcp_servers.database]
command = "python"
args = ["-m", "acme.db_mcp"]
env_forward = ["DB_CONNECTION_STRING"]
sandbox_mode = "read-only"

Architecture Rationale: Forwarding environment variables instead of hardcoding credentials ensures secrets remain in the host environment or secret manager. Sandbox modes restrict server capabilities by default. Timeout and retry policies prevent runaway tool calls from consuming context windows or rate limits.

Phase 4: Plugin Decomposition & Skill Mapping

Plugins in Claude Code are monolithic bundles. They may contain skills, commands, subagents, hooks, MCP definitions, scripts, output themes, and LSP configurations. Codex expects modular skills and explicit configuration. Decompose plugins before migration.

// plugin-decomposer.ts
interface PluginBundle {
  name: string;
  skills: string[];
  commands: { trigger: string; script: string }[];
  hooks: string[];
  mcpServers: string[];
  assets: { type: 'theme' | 'lsp' | 'monitor'; path: string }[];
}

function decomposePlugin(bundle: PluginBundle) {
  const migrationPlan = {
    skills: bundle.skills.map(s => ({ source: s, target: `skills/${s}.md` })),
    commands: bundle.commands.map(c => ({ trigger: c.trigger, handler: `scripts/${c.script}` })),
    hooks: bundle.hooks.map(h => ({ event: h, status: 'requires_semantic_review' })),
    mcp: bundle.mcpServers.map(m => ({ server: m, scope: 'project' })),
    assets: bundle.assets.filter(a => a.type !== 'theme').map(a => a.path)
  };
  return migrationPlan;
}

Architecture Rationale: Monolithic plugins obscure dependencies and make rollback difficult. Decomposition forces explicit mapping of automation logic to target skills, hooks to policy files, and scripts to executable handlers. Themes and LSP configs are typically UI/IDE concerns and should be handled separately or discarded if irrelevant to CLI execution.

Phase 5: Session State Handoff & Verification

Raw session files contain serialized conversation state, tool outputs, and internal agent metadata. Directly copying them between CLIs causes parsing errors, context corruption, or policy violations. Use structured handoff documents instead.

# Session extraction & serialization
npx session-handoff export --source claude --format json --output session-archive.json
npx session-handoff transform --input session-archive.json --preset standard --write-md handoff-report.md

A production handoff report must contain:

• Primary objective and success criteria
• Repository state (branch, uncommitted changes, build status)
• Executed commands and their outputs
• Decisions made and rationale
• Failed attempts and error logs
• Pending tasks and next action

Architecture Rationale: Handoff documents decouple session state from agent internals. They are human-readable, version-controllable, and immune to parser mismatches. Long-running agent sessions degrade in quality over time; handoff forces context pruning and objective realignment before resuming in the target environment.

Pitfall Guide

1. Silent Permission Escalation

Explanation: Copying allow/deny rules without semantic mapping often results in broader access than intended. Source CLIs may use prefix matching while target CLIs use glob patterns or path hierarchies. Fix: Default to on-request approval and workspace-write sandbox mode. Explicitly add known-safe paths. Never migrate bypassPermissions flags without manual review.

2. Desktop MCP Leakage into CLI

Explanation: Desktop MCP servers often include GUI automation, clipboard managers, or system monitors. Migrating them to a CLI agent introduces unnecessary context consumption and security surface area. Fix: Filter servers by scope during inventory. Only migrate servers explicitly registered for CLI execution. Validate each server's tool list against terminal workflow requirements.

3. Hook Syntax Copying Without Semantic Mapping

Explanation: Hook payloads, event names, and execution contexts differ between CLIs. Direct JSON duplication causes silent failures or misfired policies. Fix: Map events by intent. Rewrite handlers to match target payload structures. Implement explicit fail policies (block vs warn) and test hooks against dry-run tool calls.

4. Raw Session File Duplication

Explanation: Session files contain internal agent state, memory buffers, and parser-specific metadata. Copying them directly causes deserialization errors and context pollution. Fix: Use structured handoff documents. Serialize objective, state, decisions, and pending tasks. Verify handoff readability before resuming in the target environment.

5. Plugin Bundle Monolith Migration

Explanation: Treating plugins as single units obscures dependencies, makes rollback difficult, and carries unnecessary assets (themes, LSP configs) into the target environment. Fix: Decompose plugins into skills, commands, hooks, and scripts. Map each component explicitly. Discard UI/IDE-specific assets unless required for CLI output formatting.

6. Secret Value Extraction During Inventory

Explanation: Migration scripts that read .env files or settings JSON often extract actual token values. These values frequently end up in Git history, migration logs, or temporary files. Fix: Extract only variable names. Require explicit credential rotation in the target environment. Use secret managers or environment injection rather than file-based storage.

7. Hook Idempotency Neglect

Explanation: Hooks that modify state or trigger external services without idempotency checks cause duplicate executions, rate limit exhaustion, or inconsistent filesystem states. Fix: Design hooks to be idempotent. Use checksums, state files, or atomic operations. Implement timeout limits and explicit retry policies. Log execution traces for auditability.

Production Bundle

Action Checklist

• Inventory source environment: map instructions, hooks, MCP servers, plugins, commands, permissions, sessions, and secret references
• Isolate secret names: never extract or log credential values during migration
• Translate hooks by intent: rewrite handlers to match target event payloads and fail policies
• Scope MCP servers: extract CLI-only servers, forward environment variables, apply sandbox modes
• Decompose plugins: map skills, commands, and scripts explicitly; discard UI/IDE assets
• Generate session handoff: serialize objective, state, decisions, and pending tasks into markdown
• Apply conservative permissions: default to on-request approval and workspace-write sandbox
• Verify with dry-run tool calls: test hooks, permissions, and MCP servers before production use

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small team, single project	Direct handoff + manual config	Low overhead, fast validation	Minimal engineering time
Enterprise, multi-repo	Automated inventory + CI validation	Consistent policy enforcement, audit trail	Higher initial setup, lower long-term drift
High-security compliance	Conservative permissions + secret rotation	Zero-trust posture, credential isolation	Requires secret manager integration
Legacy plugin dependency	Decomposition + skill mapping	Removes monolithic coupling, enables rollback	Moderate refactoring effort
Rapid prototyping	Minimal hooks + permissive sandbox	Faster iteration, lower friction	Higher manual oversight required

Configuration Template

# .codex/config.toml
[agent]
model = "codex-latest"
context_window = 128000
max_tool_calls = 50

[permissions]
approval_policy = "on-request"
sandbox_mode = "workspace-write"
protected_paths = [".env", "secrets/", "node_modules/"]
allow_prefixes = ["src/", "lib/", "tests/"]

[hooks]
enabled = true
config_path = ".codex/hooks.json"
timeout_ms = 10000
fail_policy = "block"

[mcp]
auto_discover = false
allowed_scopes = ["cli", "project"]

[session]
handoff_format = "markdown"
auto_prune = true
max_context_age_hours = 48

// .codex/hooks.json
{
  "version": "2.1",
  "routing": {
    "PreToolUse": {
      "bash": {
        "handler": "scripts/validate-bash.sh",
        "timeout_ms": 5000,
        "fail_policy": "block",
        "allowed_commands": ["npm", "git", "make", "docker"]
      },
      "file_write": {
        "handler": "scripts/check-diff-scope.js",
        "allowed_paths": ["src/", "lib/", "docs/"],
        "blocked_patterns": ["*.env", "*.key", "node_modules/"]
      }
    },
    "Lifecycle": {
      "init": {
        "handler": "scripts/warm-cache.sh",
        "async": true,
        "timeout_ms": 15000
      },
      "terminate": {
        "handler": "scripts/cleanup-temp.sh",
        "async": false
      }
    }
  }
}

Quick Start Guide

1. Run inventory scan: Execute the environment scanner against your .claude/ directory. Export the report to migration-inventory.json. Verify that only secret names are captured.
2. Generate handoff document: Use the session handoff tool to extract your current workflow state. Review the markdown report for accuracy and completeness.
3. Apply conservative config: Copy the provided .codex/config.toml and .codex/hooks.json templates. Adjust allowed paths and MCP servers to match your project structure.
4. Validate with dry-run: Execute a test workflow using --dry-run or --simulate flags. Verify that hooks trigger correctly, permissions prompt as expected, and MCP servers respond within timeout limits.
5. Commit and monitor: Version control your new configuration. Monitor the first production session for permission prompts, hook failures, or context drift. Adjust allowlists and timeout policies based on observed behavior.