UniSessions

UniSessions is an SDK-first AI CLI session converter for moving sessions between Codex, Claude Code, Pi, OpenCode, Devin, Factory, Windsurf Cascade, Grok Build, and Freebuff Desktop, with trace export for HuggingFace and fine-tuning, plus an MCP chat recall server built on top.

                                                                   
 ▄▄▄  ▄▄            ▄▄▄▄▄                                         
█▀██  ██           ██▀▀▀▀█▄                                       
  ██  ██  ▄     ▀▀ ▀██▄  ▄▀                   ▀▀       ▄          
  ██  ██  ████▄ ██   ▀██▄▄  ▄█▀█▄ ▄██▀█ ▄██▀█ ██ ▄███▄ ████▄ ▄██▀█
  ██  ██  ██ ██ ██ ▄   ▀██▄ ██▄█▀ ▀███▄ ▀███▄ ██ ██ ██ ██ ██ ▀███▄
  ▀█████▄▄██ ▀█▄██ ▀██████▀▄▀█▄▄▄█▄▄██▀█▄▄██▀▄██▄▀███▀▄██ ▀██▄▄██▀

Table of Contents

• Why I built this
• Quick Start
• Supported AI coding agents
• All 72 conversion directions
• How to list sessions
• How to convert sessions
• How to export traces
• How to handle conflicts
• How to bulk export
• How to use custom paths
• MCP server for agent chat recall
• SDK usage
• Architecture
• Default session paths
• Data fidelity
• Performance
• FAQ
• Contributing
• Development
• License

Why I built this

I looked for a tool that could convert one AI CLI session into another AI CLI session format and found nothing so I built one

I also wanted my agent to remember things from my other sessions like if I solved a bug in one project I wanted to tell it hey in that other session I fixed this by doing X and it would go check and learn from it instead of me explaining the same thing again

So this does two things

• Moves your sessions between Codex Pi OpenCode Claude Code Devin Factory Windsurf Cascade Grok Build and Freebuff Desktop in any direction all 72 combinations
• Exports sessions as traces in HuggingFace STS OpenAI fine-tuning or ShareGPT format for Hub upload or model training
• Lets your agent search through all your old chat history across all projects and providers so it can recall what you did before and learn from it

Then I wanted the project to not be locked into a CLI or MCP its an SDK first so you can use it for other projects to do cool stuff like build a GUI for it or whatever you want the CLI and MCP server are just built on top of the SDK

Quick Start

Install from PyPI:

pip install unisessions
python -m unisessions list codex
python -m unisessions list pi
python -m unisessions list opencode
python -m unisessions list claude
python -m unisessions list devin
python -m unisessions list factory
python -m unisessions list windsurf
python -m unisessions list grok
python -m unisessions list freebuff

Or clone the repo:

git clone https://github.com/vibheksoni/session-export.git
cd session-export
pip install -e .
python -m unisessions list codex

Convert a single session (dry-run first, then write):

python -m unisessions codex-to-pi <session-id>
python -m unisessions codex-to-pi <session-id> --write
python -m unisessions claude-to-pi <session-id> --write
python -m unisessions devin-to-pi <session-id> --write
python -m unisessions factory-to-pi <session-id> --write
python -m unisessions windsurf-to-pi <session-id> --write
python -m unisessions freebuff-to-pi <session-id> --write

Export a session as a HuggingFace trace:

python -m unisessions to-trace codex <session-id> --format sts --write -o trace.jsonl

Bulk export all Codex sessions to Pi:

python -m unisessions codex-to-pi-all --write --workers 8

Search across all sessions via MCP:

python -m unisessions.mcp_server

Supported AI coding agents

All 72 conversion directions

How to list sessions

python -m unisessions list codex
python -m unisessions list pi
python -m unisessions list opencode
python -m unisessions list claude
python -m unisessions list devin
python -m unisessions list factory
python -m unisessions list windsurf
python -m unisessions list grok
python -m unisessions list freebuff

How to convert sessions

All commands default to dry-run. Add --write to produce output.

python -m unisessions codex-to-pi <session-id> --write
python -m unisessions pi-to-codex <session-id> --write
python -m unisessions codex-to-opencode <session-id> --write
python -m unisessions pi-to-opencode <session-id> --write
python -m unisessions opencode-to-codex <session-id> --write
python -m unisessions opencode-to-pi <session-id> --write
python -m unisessions claude-to-pi <session-id> --write
python -m unisessions pi-to-claude <session-id> --write
python -m unisessions claude-to-codex <session-id> --write
python -m unisessions codex-to-claude <session-id> --write
python -m unisessions claude-to-opencode <session-id> --write
python -m unisessions opencode-to-claude <session-id> --write
python -m unisessions devin-to-pi <session-id> --write
python -m unisessions pi-to-devin <session-id> --write
python -m unisessions devin-to-codex <session-id> --write
python -m unisessions codex-to-devin <session-id> --write
python -m unisessions devin-to-opencode <session-id> --write
python -m unisessions opencode-to-devin <session-id> --write
python -m unisessions devin-to-claude <session-id> --write
python -m unisessions claude-to-devin <session-id> --write
python -m unisessions factory-to-pi <session-id> --write
python -m unisessions pi-to-factory <session-id> --write
python -m unisessions factory-to-codex <session-id> --write
python -m unisessions codex-to-factory <session-id> --write
python -m unisessions factory-to-opencode <session-id> --write
python -m unisessions opencode-to-factory <session-id> --write
python -m unisessions factory-to-claude <session-id> --write
python -m unisessions claude-to-factory <session-id> --write
python -m unisessions factory-to-devin <session-id> --write
python -m unisessions devin-to-factory <session-id> --write
python -m unisessions windsurf-to-pi <session-id> --write
python -m unisessions pi-to-windsurf <session-id> --write
python -m unisessions windsurf-to-codex <session-id> --write
python -m unisessions codex-to-windsurf <session-id> --write
python -m unisessions windsurf-to-opencode <session-id> --write
python -m unisessions opencode-to-windsurf <session-id> --write
python -m unisessions windsurf-to-claude <session-id> --write
python -m unisessions claude-to-windsurf <session-id> --write
python -m unisessions windsurf-to-devin <session-id> --write
python -m unisessions devin-to-windsurf <session-id> --write
python -m unisessions windsurf-to-factory <session-id> --write
python -m unisessions factory-to-windsurf <session-id> --write
python -m unisessions grok-to-pi <session-id> --write
python -m unisessions pi-to-grok <session-id> --write
python -m unisessions grok-to-codex <session-id> --write
python -m unisessions codex-to-grok <session-id> --write
python -m unisessions grok-to-opencode <session-id> --write
python -m unisessions opencode-to-grok <session-id> --write
python -m unisessions grok-to-claude <session-id> --write
python -m unisessions claude-to-grok <session-id> --write
python -m unisessions grok-to-devin <session-id> --write
python -m unisessions devin-to-grok <session-id> --write
python -m unisessions grok-to-factory <session-id> --write
python -m unisessions factory-to-grok <session-id> --write
python -m unisessions grok-to-windsurf <session-id> --write
python -m unisessions windsurf-to-grok <session-id> --write
python -m unisessions freebuff-to-pi <session-id> --write
python -m unisessions pi-to-freebuff <session-id> --write
python -m unisessions freebuff-to-codex <session-id> --write
python -m unisessions codex-to-freebuff <session-id> --write
python -m unisessions freebuff-to-opencode <session-id> --write
python -m unisessions opencode-to-freebuff <session-id> --write
python -m unisessions freebuff-to-claude <session-id> --write
python -m unisessions claude-to-freebuff <session-id> --write
python -m unisessions freebuff-to-devin <session-id> --write
python -m unisessions devin-to-freebuff <session-id> --write
python -m unisessions freebuff-to-factory <session-id> --write
python -m unisessions factory-to-freebuff <session-id> --write
python -m unisessions freebuff-to-windsurf <session-id> --write
python -m unisessions windsurf-to-freebuff <session-id> --write
python -m unisessions freebuff-to-grok <session-id> --write
python -m unisessions grok-to-freebuff <session-id> --write

How to export traces

Export any session as a trace file for HuggingFace Hub upload, model fine-tuning, or training data preparation. Three formats are supported:

# HuggingFace STS format (default) -- print to stdout
python -m unisessions to-trace codex <session-id> --format sts

# OpenAI fine-tuning format -- write to file
python -m unisessions to-trace pi <session-id> --format openai --write -o train.jsonl

# ShareGPT format from Devin session
python -m unisessions to-trace devin <session-id> --format sharegpt --write -o traces.jsonl

Upload to HuggingFace Hub:

pip install huggingface-cli
hf upload your-username/your-dataset trace.jsonl

The Hub auto-detects the trace format and renders it in the trace viewer. See the trace export docs for SDK usage and format details.

How to handle conflicts

When a destination file already exists use --on-conflict to control behavior:

python -m unisessions codex-to-pi <id> --write --on-conflict fork
python -m unisessions codex-to-pi <id> --write --on-conflict update

How to bulk export

Export all Codex sessions to one or more targets in parallel:

python -m unisessions codex-to-pi-all --write --workers 8
python -m unisessions export-all --write --targets pi opencode claude devin factory windsurf grok freebuff --workers 8

How to use custom paths

Use system defaults by omitting path flags. For backups or staging:

python -m unisessions --codex-session-dir C:\path\to\sessions list codex
python -m unisessions --pi-session-dir C:\path\to\pi\sessions list pi
python -m unisessions --opencode-session-dir C:\path\to\opencode\exports list opencode
python -m unisessions --claude-session-dir C:\path\to\claude\projects list claude
python -m unisessions --devin-session-dir C:\path\to\devin\transcripts list devin
python -m unisessions --factory-session-dir C:\path\to\factory\sessions list factory
python -m unisessions --windsurf-session-dir C:\path\to\windsurf\cascade list windsurf
python -m unisessions --grok-home C:\path\to\grok --grok-session-dir C:\path\to\grok\sessions list grok
python -m unisessions --freebuff-home C:\path\to\freebuff --freebuff-session-dir C:\path\to\freebuff\projects list freebuff

OpenCode output files use the official import/export JSON shape. Load them with opencode import <path-to-json>.

MCP server for agent chat recall

UniSessions ships a FastMCP server that exposes a SQLite FTS5 full-text search index over parsed session chat history. AI agents can use it to recall past conversations, find what was discussed, and search across all providers.

Setup

python -m unisessions.mcp_server

MCP client configuration

{
  "mcpServers": {
    "unisessions": {
      "command": "unisessions-mcp",
      "args": [],
      "env": {
        "UNISESSIONS_SEARCH_INDEX": "%LOCALAPPDATA%\\unisessions\\search.sqlite"
      }
    }
  }
}

HTTP transports for app-managed servers

unisessions-mcp --transport streamable-http --host 127.0.0.1 --port 8765 --path /mcp
unisessions-mcp --transport http --host 127.0.0.1 --port 8765
unisessions-mcp --transport sse --host 127.0.0.1 --port 8765

Environment knobs: UNISESSIONS_MCP_TRANSPORT, UNISESSIONS_MCP_HOST, UNISESSIONS_MCP_PORT, UNISESSIONS_MCP_PATH, UNISESSIONS_MCP_LOG_LEVEL, UNISESSIONS_MCP_SHOW_BANNER, UNISESSIONS_SEARCH_INDEX.

MCP tools

search_chats returns a structured response with search_metadata (total_matches, deduplicated, sessions_searched, messages_searched, truncated) and a results array ranked by relevance score. Duplicate messages across compaction cycles are collapsed to a single hit with a duplicate_count field.

search_chats supports provider (codex, pi, opencode, claude, devin, factory, windsurf, grok, freebuff), cwd, session_id, role (user, assistant), message type (message, compaction, contextual), exclude_keywords to filter out false positives, max_per_session (default 5) to prevent one session from flooding results, date range (after, before), and stale-index policy (refresh, skip, error).

Search runs over parsed TextMessage rows, not raw JSON files, so semantic filters like roles=["user"] stay correct. Tool calls and tool outputs are excluded to keep recall focused on chat text. An internal raw-match cap of 200 prevents timeouts on massive sessions.

Performance: warm indexed search ~35-40ms on a 20-session corpus. Cold index refresh ~39-49s (I/O-bound). Call index_status first, then refresh_chats_index, then use search_chats with stale_policy="skip" for fast interactive recall.

SDK usage

Build your own application on top of session_sdk without the CLI:

from session_sdk import (
    CodexStore, PiStore, PiDcpStore, FactoryStore, WindsurfStore,
    CodexToPiConverter, SessionIdFactory, WindowsDefaults,
)

defaults = WindowsDefaults()
codex = CodexStore(defaults.codex_home)
pi = PiStore(defaults.pi_agent_home)
dcp = PiDcpStore(defaults.pi_dcp_home)

converter = CodexToPiConverter(codex, pi, dcp, SessionIdFactory())
plan = converter.plan("your-session-id-here")

print(f"Source:      {plan.source.path}")
print(f"Destination: {plan.destination}")
print(f"Records:     {len(plan.records)}")

converter.write(plan, overwrite=False)

Trace export API

from session_sdk import (
    CodexStore, WindowsDefaults,
    MessageExtractor, build_trace,
)
from session_sdk.jsonl import _dumps

defaults = WindowsDefaults()
store = CodexStore(defaults.codex_home)
session = store.load("session-id")
messages = MessageExtractor().from_codex(session)

# Build HuggingFace STS-format trace
records = build_trace("sts", session, messages)

# Write to JSONL
with open("trace.jsonl", "wb") as f:
    for record in records:
        f.write(_dumps(record))
        f.write(b"\n")

Search API

from session_sdk import (
    CodexStore, PiStore, OpenCodeStore, ClaudeStore, DevinStore, FactoryStore, WindsurfStore, GrokStore, FreebuffStore,
    SessionSearchEngine, WindowsDefaults,
)

defaults = WindowsDefaults()
engine = SessionSearchEngine(
    CodexStore(defaults.codex_home),
    PiStore(defaults.pi_agent_home),
    OpenCodeStore(defaults.opencode_data_home),
    claude=ClaudeStore(defaults.claude_home),
    devin=DevinStore(defaults.devin_home),
    factory=FactoryStore(defaults.factory_home),
    windsurf=WindsurfStore(defaults.windsurf_home),
    grok=GrokStore(defaults.grok_home),
    freebuff=FreebuffStore(defaults.freebuff_home),
)

engine.refresh_index(provider="claude")

response = engine.search(
    query="authentication",
    provider="claude",
    roles=["assistant"],
    stale_policy="skip",
)
for hit in response["results"]:
    print(f"{hit['session_id']} [{hit['role']}] {hit['snippet'][:80]}")

# SDK escape hatch for apps that want custom ranking or filtering.
raw_rows = engine.raw_search_rows(query="authentication", provider="claude")

engine.close()

Architecture

session-export/
  pyproject.toml              # both packages + optional [mcp] extra
  session_sdk/                # the SDK core (no CLI dependencies)
    __init__.py               # public API surface
    json_types.py             # JSON type guards and coercion
    jsonl.py                  # JSONL read/write helpers (orjson when available)
    models.py                 # SessionSummary, TextMessage, NativeSession, ConversionPlan
    paths.py                  # WindowsDefaults, path encoding, SessionIdFactory, timestamps
    stores.py                 # CodexStore, PiStore, PiDcpStore, OpenCodeStore, ClaudeStore, DevinStore, FactoryStore, WindsurfStore, GrokStore, FreebuffStore
    converters.py             # Extractors, builders, 72 converters
    traces.py                 # STS, OpenAI, ShareGPT trace format builders
    search.py                 # parsed SQLite FTS5 chat recall index/search
  unisessions/                # CLI and MCP app (depends on session_sdk)
    __init__.py
    __main__.py               # python -m unisessions
    cli.py                    # argparse, command routing, dry-run/write, conflict resolution, trace export
    mcp_server.py             # FastMCP tools for chat recall/search
  tests/
    test_conversion.py        # 40 tests
  docs/                       # full API documentation
  examples/                   # 7 tested Python example scripts
  requirements.txt            # tiktoken + cryptography (required), orjson + google-re2 (optional)
  requirements-mcp.txt        # fastmcp for MCP server

Dependency chain (no cycles)

json_types  (leaf)
jsonl       -> json_types
models      -> json_types
paths       (leaf)
stores      -> models, jsonl, json_types, paths
converters  -> stores, models, paths, json_types
search      -> stores, converters, models

The SDK never imports from the CLI. unisessions depends on session_sdk, never the reverse.

Default session paths

Data fidelity

UniSessions performs text-history conversions, not full behavioral state replay. It preserves user/assistant/system text and enough metadata for the target tool to open the session. It does not fully preserve every tool call, provider-specific event, approval state, sandbox state, MCP runtime, or UI-only event.

How compaction is handled

Compaction markers are preserved across all nine formats so the target tool can reconstruct context correctly:

• Pi: type="compaction" entry with summary, firstKeptEntryId, tokensBefore, details, and fromHook=True
• Codex: type="compacted" record with payload.message summary text
• OpenCode: user message with CompactionPart + assistant summary=True
• Claude Code: system entry with subtype="compact_boundary" + logicalParentUuid, followed by user message with isCompactSummary=true
• Devin: compaction summaries become system steps in ATIF transcript JSON
• Windsurf Cascade: compaction checkpoints (field 30) become compaction summary messages
• Grok Build: compaction summaries import as user_message_chunk envelopes so the conversation stays readable in Grok's TUI

How contextual messages are handled

Codex injects contextual messages (permissions, AGENTS.md instructions, environment context, skills, plugins) as developer or user role messages. These are marked is_contextual=True by the SDK extractor and skipped by all builders during export to prevent payload overflow in target tools. SDK consumers can still inspect these messages.

Performance

• orjson for JSON parsing when available (2x faster than stdlib)
• google-re2 for regex search when available (4x faster than stdlib re)
• Trace export to HuggingFace STS, OpenAI fine-tuning, and ShareGPT formats
• O(1) session lookup via cached path index and ID index
• has_changes() reads head meta + line count (no full JSON parse)
• Bulk export reuses converter instances across sessions
• Default bulk workers: 8 (higher is opt-in; 32 workers measured ~2x slower)
• Warm indexed search: ~35-40ms on a 20-session corpus
• Cold index refresh: ~39-49s (I/O-bound, threading helps modestly)

FAQ

Can I convert Claude Code sessions to Pi?

Yes. Use python -m unisessions claude-to-pi <session-id> --write. All 72 conversion directions are supported between Codex, Pi, OpenCode, Claude Code, Devin, Factory, Windsurf Cascade, Grok Build, and Freebuff Desktop.

Can I export all my Codex sessions at once?

Yes. Use python -m unisessions codex-to-pi-all --write --workers 8 to bulk export all Codex sessions to Pi in parallel. You can also export to multiple targets at once with export-all --write --targets pi opencode claude devin factory windsurf grok freebuff.

Can my AI agent search my old chat history?

Yes. The MCP server exposes search_chats and search_sessions tools that do full-text search over parsed chat messages from all providers. Your agent can recall what you discussed in any session across any project. Search runs on a SQLite FTS5 index so warm queries are ~35ms. Results are ranked by relevance, deduplicated across compaction cycles, and capped per session to prevent timeouts.

What happens if the destination session already exists?

Use --on-conflict to control behavior: skip (default), overwrite, fork (new UUID, preserves old file), or update (skip if unchanged, overwrite if source changed).

Does this preserve tool calls and tool outputs?

No. This tool performs text-history conversions preserving user and assistant chat messages, compaction summaries, and session metadata. Tool calls and tool outputs are not preserved in the current version.

Can I use the SDK without the CLI?

Yes. The SDK (session_sdk) is a standalone library with no CLI dependencies. Import stores, converters, and the search engine directly in your own Python projects. The CLI and MCP server are thin wrappers built on top.

What session formats are supported?

Codex JSONL rollout files, Pi JSONL append-only tree entries, OpenCode export/import JSON, Claude Code JSONL transcript files, Devin ATIF transcript JSON with SQLite metadata, Factory JSONL transcript files, Windsurf Cascade AES-256-GCM encrypted protobuf trajectory files, Grok Build ACP updates.jsonl + summary.json session directories, and Freebuff Desktop per-project SQLite desktop-v2.db (threads + messages) databases. All nine formats are supported in all 72 conversion directions.

How fast is bulk export?

A full export of 276 Codex sessions to Pi completes in about 65 seconds with 8 workers. The largest sessions (700MB+) take a few seconds each. Default workers is 8 because higher counts measured slower on I/O-bound workloads.

Contributing

1. Fork the repo
2. Create a branch: git checkout -b feature/your-feature
3. Run tests: python -m unittest discover -s tests -v
4. Submit a PR with a description of your change

Development

python -m compileall session_sdk unisessions tests
python -m unittest discover -s tests -v

40 tests covering conversion shape, compaction extraction/emission, dry-run safety, assistant usage estimation, OpenCode JSON shape, custom session directories, path encoding, Claude extraction and conversion, Devin extraction and conversion, Windsurf Cascade extraction and conversion, Grok Build extraction, conversion, and store round-trips, Freebuff Desktop extraction, conversion, and store round-trips, trace format building (STS, OpenAI, ShareGPT), search behavior, search index persistence, regex full-index search, keyword contraction handling, and dedup edge cases.

Links

• X/Twitter: @ImVibhek
• Website: vibheksoni.com
• Security Blog: opendoors.wtf

License

MIT