Skip to content

MIGRATION.md

Latest commit

 

History

History
380 lines (264 loc) · 8.75 KB

MIGRATION.md

File metadata and controls

380 lines (264 loc) · 8.75 KB

Migration Guide

Migrating from Claude Code PAI to PAI OpenCode

Overview

This guide helps you migrate an existing PAI 2.x installation from Claude Code to OpenCode.

Two migration paths:

  1. Fresh Install - Start clean with PAI-OpenCode defaults
  2. Migration - Transfer your customizations from Claude Code PAI

Migration Flow

Prerequisites

Required

  • Bun (JavaScript runtime)

    curl -fsSL https://bun.sh/install | bash

  • OpenCode (AI coding assistant)

    Install the standard vanilla release from opencode.ai. No custom build or fork required.

Path 1: Fresh Install (Recommended for New Users)

# 1. Clone repository
git clone https://github.com/Steffen025/pai-opencode.git
cd pai-opencode

# 2. Install dependencies
bun install

# 3. Run the installer
bash PAI-Install/install.sh

# 4. Start OpenCode
opencode

That's it! PAI is now running with defaults.

Path 2: Migration from Claude Code PAI

Step 1: Verify Source PAI

Check your Claude Code PAI installation:

ls -la ~/.claude/

# Expected structure:
# ~/.claude/
# ├── skills/
# ├── agents/
# ├── hooks/
# ├── MEMORY/
# └── settings.json

Step 2: Clone PAI-OpenCode

git clone https://github.com/Steffen025/pai-opencode.git
cd pai-opencode

Step 3: Run CLI Installer (Baseline Config)

This normalizes your opencode.json and ~/.opencode/ before migration.

bash PAI-Install/install.sh

Step 4: Preview Migration (Dry Run)

bun Tools/pai-to-opencode-converter.ts \
  --source ~/.claude \
  --target .opencode \
  --dry-run

Review the output:

  • What will be copied
  • What will be transformed
  • What requires manual work

Step 5: Run Migration

bun Tools/pai-to-opencode-converter.ts \
  --source ~/.claude \
  --target .opencode

Step 6: Verify Migration

# Check structure
ls -la .opencode/

# Verify no .claude references
grep -r "\.claude" .opencode/ --exclude-dir=node_modules

Step 7: Test OpenCode

opencode

Verify:

  1. Skills load: "What skills do I have?"
  2. Agents work: @Intern hello
  3. Security active: Check /tmp/pai-opencode-debug.log

Architecture Changes

PAI-OpenCode required several architectural adaptations to work with OpenCode. These are documented in Architecture Decision Records (ADRs):

Change ADR Impact
Hooks → Plugins ADR-001 Implementation only—logic preserved
.claude/ → .opencode/ ADR-002 Path updates only
File-based logging ADR-004 Debug workflow change
Dual config files ADR-005 settings.json + opencode.json

What stayed the same:

  • Skills System: ADR-003 - 100% identical
  • Security: ADR-006 - Patterns preserved
  • Memory: ADR-007 - Structure unchanged

What Transfers

Component Transfer Status Notes
Skills ✅ Full transfer All skills work identically
Agents ✅ Full transfer Renamed to PascalCase

v1.3 Agent Changes:

  • ClaudeResearcher → DeepResearcher
  • PerplexityProResearcher removed (use PerplexityResearcher)
  • researcher.md renamed to individual researcher files | MEMORY | ✅ Full transfer | Work, Learning, State preserved | | Security Patterns | ✅ Full transfer | patterns.yaml copied | | USER Customizations | ✅ Full transfer | TELOS, ABOUTME, etc. | | settings.json | ⚠️ Partial transfer | Schema mapped | | Hooks | ❌ Manual work | Convert to plugins | | MCP Servers | ❌ Deferred | v1.x feature | | Observability | ❌ Deferred | v1.2 feature |

What Doesn't Transfer (Manual Work Required)

Custom Hooks

If you have custom hooks in ~/.claude/hooks/:

  1. Extract logic from hook file
  2. Create handler in .opencode/plugins/handlers/
  3. Add event to .opencode/plugins/pai-unified.ts

Example:

// Old hook: ~/.claude/hooks/custom-logger.ts
writeFileSync("/tmp/my-log.txt", "Tool executed");
process.exit(0);

// New plugin handler: .opencode/plugins/handlers/custom-logger.ts
import { fileLog } from "../lib/file-logger";
export async function customLog() {
  fileLog("Tool executed");
}

See PLUGIN-SYSTEM.md for full guide.

Troubleshooting

"opencode: command not found"

The installer installs OpenCode to ~/.local/bin/. Make sure it's in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add to your shell config (~/.bashrc or ~/.zshrc) to make it permanent.

Plugin doesn't load

cat /tmp/pai-opencode-debug.log
# Should show: "PAI-OpenCode Plugin Loaded"

Agent invocation fails

Verify agent files are PascalCase:

ls -la .opencode/agents/
# Should be: Intern.md (not intern.md)

CORE skill not loading

grep "Context" /tmp/pai-opencode-debug.log
# Should show: "Context injected successfully"

TUI corruption

reset && opencode

Check plugin code for console.log (should use fileLog).

Converter Tool Reference

Usage

bun Tools/pai-to-opencode-converter.ts [options]

Options

Option Description Default
--source <path> Source PAI directory ~/.claude
--target <path> Target OpenCode directory .opencode
--mode <mode> Migration mode (full or selective) full
--dry-run Preview changes without applying false

Migration Modes Explained

Full Mode (Default)

Copies everything from your Claude Code PAI:

bun Tools/pai-to-opencode-converter.ts --mode full
What Gets Copied Description
Skills All skill definitions
Agents All agent personalities
MEMORY Projects, sessions, learning history
USER TELOS, identity, preferences
Security patterns Custom security rules
Settings Environment variables

Best for: Starting fresh with your complete PAI history.

Selective Mode

Copies only system components, preserving your existing USER customizations:

bun Tools/pai-to-opencode-converter.ts --mode selective
What Gets Copied What's Preserved
Skills (system) USER/TELOS.md
Agents (system) USER/ABOUTME.md
Security patterns USER/Contacts.md
Settings (schema only) Custom USER files

Best for:

  • Updating to a new PAI-OpenCode version
  • Preserving personal customizations while getting new skills
  • Merging multiple PAI installations

Examples

Preview full migration (dry run):

bun Tools/pai-to-opencode-converter.ts --dry-run

Full migration:

bun Tools/pai-to-opencode-converter.ts --mode full

Selective migration (preserve USER customizations):

bun Tools/pai-to-opencode-converter.ts --mode selective

Custom source and target:

bun Tools/pai-to-opencode-converter.ts \
  --source ~/backup/.claude \
  --target .opencode \
  --mode selective

Post-Migration Checklist

After migration, verify:

  • OpenCode starts without errors
  • CORE skill loads (check first response)
  • Agents work (@Intern hello)
  • Security blocks dangerous commands
  • MEMORY preserved (check .opencode/MEMORY/)
  • USER customizations intact (check .opencode/skills/PAI/USER/)
  • Debug log shows plugin loaded

Rollback

If migration fails:

# Delete failed migration
rm -rf .opencode/

# Re-clone fresh
git clone https://github.com/Steffen025/pai-opencode.git

Your original PAI (Claude Code) is never modified during migration.

Getting Help

Next Steps

After successful migration:

  1. Customize - Edit .opencode/settings.json
  2. Explore - Try all skills and agents
  3. Secure - Review .opencode/PAISECURITYSYSTEM/patterns.yaml
  4. Learn - Read skill documentation in .opencode/skills/*/SKILL.md

PAI OpenCode - Your PAI, your way