Content
# UniSessions
UniSessions is an SDK-first AI CLI session converter for moving sessions between Codex, Claude Code, Pi, and OpenCode, with an MCP chat recall server built on top.
<div align="center">
```
▄▄▄ ▄▄ ▄▄▄▄▄
█▀██ ██ ██▀▀▀▀█▄
██ ██ ▄ ▀▀ ▀██▄ ▄▀ ▀▀ ▄
██ ██ ████▄ ██ ▀██▄▄ ▄█▀█▄ ▄██▀█ ▄██▀█ ██ ▄███▄ ████▄ ▄██▀█
██ ██ ██ ██ ██ ▄ ▀██▄ ██▄█▀ ▀███▄ ▀███▄ ██ ██ ██ ██ ██ ▀███▄
▀█████▄▄██ ▀█▄██ ▀██████▀▄▀█▄▄▄█▄▄██▀█▄▄██▀▄██▄▀███▀▄██ ▀██▄▄██▀
```
**Convert one AI CLI session format into another across Codex, Pi, OpenCode, and Claude Code.**
I use a lot of AI coding CLIs Codex Claude Code Pi OpenCode and wanted to move a session from one tool into another without losing the useful conversation history
[](https://www.python.org/)
[]()
[-purple)]()
[]()
[]()
[]()
[](https://github.com/vibheksoni/session-export/stargazers)
</div>
---
## Table of Contents
- [Why I built this](#why-i-built-this)
- [Quick Start](#quick-start)
- [Supported AI coding agents](#supported-ai-coding-agents)
- [All 12 conversion directions](#all-12-conversion-directions)
- [How to list sessions](#how-to-list-sessions)
- [How to convert sessions](#how-to-convert-sessions)
- [How to handle conflicts](#how-to-handle-conflicts)
- [How to bulk export](#how-to-bulk-export)
- [How to use custom paths](#how-to-use-custom-paths)
- [MCP server for agent chat recall](#mcp-server-for-agent-chat-recall)
- [SDK usage](#sdk-usage)
- [Architecture](#architecture)
- [Default session paths](#default-session-paths)
- [Data fidelity](#data-fidelity)
- [Performance](#performance)
- [FAQ](#faq)
- [Contributing](#contributing)
- [Development](#development)
- [License](#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 and Claude Code in any direction all 12 combinations
- 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
Clone the repo and run from it directly
```powershell
git clone https://github.com/vibheksoni/session-export.git
cd session-export
python -m unisessions list codex
python -m unisessions list pi
python -m unisessions list opencode
python -m unisessions list claude
```
Convert a single session (dry-run first, then write):
```powershell
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
```
Bulk export all Codex sessions to Pi:
```powershell
python -m unisessions codex-to-pi-all --write --workers 8
```
Search across all sessions via MCP:
```powershell
python -m unisessions.mcp_server
```
## Supported AI coding agents
| Agent | Store | Session Format | Session IDs |
|---|---|---|---|
| [OpenAI Codex](https://github.com/openai/codex) | `codex` | JSONL rollout files under date tree | UUID v7 |
| [Pi](https://github.com/earendil-works/pi-coding-agent) | `pi` | JSONL append-only tree entries in cwd-encoded dirs | UUID v7 |
| [OpenCode](https://github.com/sst/opencode) | `opencode` | Official export/import JSON | `ses_` prefixed |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | JSONL transcript files in cwd-sanitized dirs | UUID v4 |
## All 12 conversion directions
| From \ To | Pi | Codex | OpenCode | Claude |
|---|---|---|---|---|
| **Codex** | `codex-to-pi` | -- | `codex-to-opencode` | `codex-to-claude` |
| **Pi** | -- | `pi-to-codex` | `pi-to-opencode` | `pi-to-claude` |
| **OpenCode** | `opencode-to-pi` | `opencode-to-codex` | -- | `opencode-to-claude` |
| **Claude** | `claude-to-pi` | `claude-to-codex` | `claude-to-opencode` | -- |
## How to list sessions
```powershell
python -m unisessions list codex
python -m unisessions list pi
python -m unisessions list opencode
python -m unisessions list claude
```
## How to convert sessions
All commands default to dry-run. Add `--write` to produce output.
```powershell
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
```
## How to handle conflicts
When a destination file already exists use `--on-conflict` to control behavior:
| Mode | Behavior |
|---|---|
| `skip` (default) | Skip if destination exists |
| `overwrite` | Replace existing destination with new content |
| `fork` | Generate a new UUID session ID, preserve old file untouched |
| `update` | Skip if unchanged, overwrite if source changed (fast head-meta + line count check) |
```powershell
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:
```powershell
python -m unisessions codex-to-pi-all --write --workers 8
python -m unisessions export-all --write --targets pi opencode claude --workers 8
```
## How to use custom paths
Use system defaults by omitting path flags. For backups or staging:
```powershell
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
```
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](https://github.com/jlowin/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
```powershell
python -m unisessions.mcp_server
```
### MCP client configuration
```json
{
"mcpServers": {
"unisessions": {
"command": "unisessions-mcp",
"args": [],
"env": {
"UNISESSIONS_SEARCH_INDEX": "C:\\Users\\you\\AppData\\Local\\unisessions\\search.sqlite"
}
}
}
}
```
### HTTP transports for app-managed servers
```powershell
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
| Tool | Description |
|---|---|
| `list_chats` | List sessions globally or filtered by provider and project path |
| `index_status` | Report indexed, missing, stale, deleted, and refresh-size counts |
| `refresh_chats_index` | Parse sessions into SQLite FTS5 index for fast recall |
| `search_chats` | Full-text search with literal, regex, all-keywords, and any-keywords modes |
| `search_sessions` | Find which sessions match a topic, with match counts and top snippets |
`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`), 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:
```python
from session_sdk import (
CodexStore, PiStore, PiDcpStore,
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)
```
### Search API
```python
from session_sdk import (
CodexStore, PiStore, OpenCodeStore, ClaudeStore,
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),
)
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
converters.py # Extractors, builders, 12 converters
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
mcp_server.py # FastMCP tools for chat recall/search
tests/
test_conversion.py # 22 tests
docs/ # full API documentation
examples/ # 7 tested Python example scripts
requirements.txt # tiktoken (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
| Agent | Default Location |
|---|---|
| Codex sessions | `~/.codex/sessions` |
| Codex archived | `~/.codex/archived_sessions` |
| Pi sessions | `~/.pi/agent/sessions` |
| Pi DCP sidecars | `~/.pi-dcp/sessions` |
| OpenCode data | `%APPDATA%\opencode` or `OPENCODE_GLOBAL_DATA_DIR` |
| Claude Code | `~/.claude` or `CLAUDE_CONFIG_DIR` |
## 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 four 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`
### 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`)
- 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 12
conversion directions are supported between Codex, Pi, OpenCode, and Claude
Code.
**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`.
**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, and Claude Code JSONL transcript files. All four formats
are supported in all 12 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
```powershell
python -m compileall session_sdk unisessions tests
python -m unittest discover -s tests -v
```
22 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, search behavior,
search index persistence, regex full-index search, keyword contraction
handling, and dedup edge cases.
## Links
- X/Twitter: [@ImVibhek](https://x.com/ImVibhek)
- Website: [vibheksoni.com](https://vibheksoni.com/)
- Security Blog: [opendoors.wtf](https://opendoors.wtf/)
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available