session-convert

MCP server that converts coding agent sessions between Claude Code, Codex CLI, and OpenCode.

The only tool that supports OpenCode SQLite session conversion — agent-convert and ctxmv handle Claude↔Codex but nothing touches OpenCode's .opencode/opencode.db.

What problem does this solve?

You're using multiple AI coding agents (Claude Code, Codex CLI, OpenCode) and want to migrate a session from one to another — maybe you started in Claude Code but want to continue in OpenCode, or you found a great Codex session that would be useful in Claude.

Each agent stores sessions differently:

• Claude Code — JSONL files in ~/.claude/projects/<hash>/<session-id>.jsonl (legacy nested sessions/ is also supported)

• Codex CLI — Rollout JSONL in ~/.codex/sessions/YYYY/MM/DD/

• OpenCode — current SQLite database in ~/.local/share/opencode/opencode.db; legacy project-local databases in <project>/.opencode/opencode.db are also supported

This MCP server reads from any of these, normalizes into a unified format, and writes to any other. All 6 conversion directions work (Claude→Codex, Claude→OpenCode, Codex→Claude, Codex→OpenCode, OpenCode→Claude, OpenCode→Codex).

Related MCP server: codex-mcp-server

Quick Start

git clone https://github.com/megamen32/session-convert.git
cd session-convert
npm install
npm run build

MCP Configuration

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "session-convert": {
      "command": "node",
      "args": ["/absolute/path/to/session-convert/dist/index.js"]
    }
  }
}

Cursor / Windsurf (.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "session-convert": {
      "command": "node",
      "args": ["/absolute/path/to/session-convert/dist/index.js"]
    }
  }
}

MCP Tools

list_sessions

List available sessions from a harness. Filter by working directory prefix.

list_sessions({ harness: "claude", cwdPrefix: "~/apps" })
list_sessions({ harness: "codex" })
list_sessions({ harness: "opencode", searchPaths: ["~/projects"] })

convert_session

Convert a session from one harness to another by session ID.

convert_session({ from: "claude", to: "opencode", sessionId: "abc-123" })
convert_session({ from: "codex", to: "claude", sessionId: "xyz-789" })
convert_session({ from: "opencode", to: "codex", sessionId: "oc-session-1", projectPath: "/path/to/project" })

preview_conversion

Dry-run a conversion — shows message breakdown, tool call stats, and compatibility warnings without writing anything.

preview_conversion({ from: "claude", to: "opencode", sessionId: "abc-123" })

convert_by_path

Convert a session file by its direct path. Auto-detects the format (Claude JSONL, Codex rollout JSONL, or OpenCode .db).

convert_by_path({ sourcePath: "/home/user/.claude/projects/.../sessions/abc.jsonl", to: "codex" })
convert_by_path({ sourcePath: "/home/user/myproject/.opencode/opencode.db", to: "claude" })

Conversion Matrix

What Gets Preserved

How It Works

Source format  →  Unified Conversation  →  Target format
(JSONL/SQLite)     (typed Messages)         (JSONL/SQLite)

1. Read — Parse the source session (Claude JSONL, Codex rollout JSONL, or OpenCode SQLite) into a unified Conversation object with typed Message parts (text, tool_call, tool_result, thinking, image)

2. Transform — Map content types between format-specific representations (e.g., Claude's tool_use ↔ Codex's function_call ↔ OpenCode's double-wrapped tool_call part)

3. Write — Serialize to the target harness's native format and store it in the correct location

Format-Specific Details

• Claude Code stores sessions as one JSON object per line in .jsonl files. Tool calls are tool_use blocks, results are tool_result blocks in the next user message. Thinking blocks are stored as thinking content type.

• Codex CLI uses a session_meta header line followed by response_item entries. Tool calls are separate function_call items with matching function_call_output items. Reasoning is a separate reasoning item type.

• OpenCode currently uses a global SQLite database with session, message, and part tables. Older project-local databases use sessions and messages, with parts stored as JSON in a double-wrapped format: [{ "type": "text", "data": { "text": "..." } }]. Both schemas are supported.

Testing

# Create the OpenCode SQLite test fixture
npm run test:fixtures

# Run all conversion tests (covers all 6 conversion directions + current OpenCode resume shape)
npm test

# Release gate for offline conversion/build checks
npm run test:release

# Live release smoke against a running OpenCode backend (uses a cheap model and writes a log)
OPENCODE_SMOKE_PASSWORD='...' npm run test:release:live

# Watch mode
npm run test:watch

Tests use 3 hand-crafted mini-sessions (one per harness) that include text, thinking, tool_call, and tool_result content parts. Each test reads from a fixture, writes to a target format, then reads back to verify roundtrip integrity.

The live smoke requires OPENCODE_SMOKE_PASSWORD and uses these optional defaults: http://127.0.0.1:4095, project /home/roomhacker/PycharmProjects/TelegramAuto, model opencode/big-pickle, and log path trash/logs/. Override them with OPENCODE_SMOKE_URL, OPENCODE_SMOKE_PROJECT, OPENCODE_SMOKE_MODEL, and OPENCODE_SMOKE_LOG.

Known Limitations

• Encrypted Codex reasoning (encrypted_content) cannot be decrypted — only summary text is preserved

• Claude sub-agent sessions (Task tool spawning child sessions) are not followed — only the parent conversation converts

• Token usage is approximate when cross-converting (different tokenizers per provider)

• OpenCode must be restarted to discover newly imported sessions

• System messages are dropped for Claude (not stored in JSONL) or converted to user messages for Codex

Comparison with Alternatives

Keywords

mcp server, claude code session export, codex cli session migration, opencode session convert, ai coding agent session transfer, claude to codex, claude to opencode, codex to claude, opencode to claude, session migration tool, coding agent context switch, mcp tool, model context protocol, session converter, ai agent session backup, claude jsonl, codex rollout jsonl, opencode sqlite, coding session portability

License

MIT