GitHub - theoriclabs/agent-convert

NOTE Please use the lean-version of the repo https://github.com/theoriclabs/agent-convert-lean That is a more up to date maintained version of this.

Convert coding-agent sessions from one format to another. Claude Code to Codex CLI. Codex to Claude Code. Google AI Studio or Hermes exports into the same portable session format, then onward into the harness you want to use next. One local CLI turns agent transcripts into files you can resume, inspect, or move between tools.

npm i -g agent-convert

# Claude Code session -> Codex, installed so `codex resume` sees it
agent-convert ~/.claude/projects/<project>/<session-id>.jsonl --to codex

# Codex rollout -> Claude Code session file
agent-convert ~/.codex/sessions/2026/07/02/rollout-<ts>-<id>.jsonl --to claude out.jsonl

# Google AI Studio export -> Cursor standalone sqlite database
agent-convert chat.json --from google-ai-studio --to cursor out.vscdb

# Any supported file export -> the pi JSONL pivot format
agent-convert chat.json --from google-ai-studio --to pi

Source format is auto-detected (--from auto is the default). With no output path, the codex target installs (opt out with --no-install); every other target writes a sibling file like session.pi.jsonl. Everything runs locally — no network calls, no telemetry, your transcripts never leave your machine. (Install note: npm may print deprecation warnings from the optional native sqlite3 chain — they're upstream noise, and only Cursor support needs sqlite3 at all.)

Support matrix

Direct file conversions through agent-convert:

Every conversion pivots through the pi JSONL session format; any direct file source can become any target in one command.

Cursor IDE sessions live in a sqlite store, not files. Use the plumbing command to discover/extract one, then convert onward:

agent-convert-to-pi cursor --list
agent-convert-to-pi cursor --chat-id <composerId> cursor.pi.jsonl
agent-convert cursor.pi.jsonl --from pi --to codex out.codex.jsonl

Conversion examples

# Claude Code -> Codex CLI
agent-convert claude-session.jsonl --to codex

# Codex CLI -> Claude Code
agent-convert rollout.jsonl --to claude claude-session.jsonl

# Hermes -> Google-independent pivot archive
agent-convert hermes-session.json --to pi archive.pi.jsonl

# Google AI Studio -> Codex CLI
agent-convert gais-export.json --from google-ai-studio --to codex out.codex.jsonl

# Claude Code -> Cursor standalone database
agent-convert claude-session.jsonl --to cursor out.vscdb

# Machine-readable summary for agents and scripts
agent-convert claude-session.jsonl --to codex --json

Commands

• agent-convert — one-shot <input> [output] --from auto --to <fmt> (this is the one you want).
• agent-convert-to-pi — plumbing: per-source import into pi JSONL, with every knob (--drop-thinking, --keep-pre-compaction-history, cursor chat discovery, --install into ~/.pi/agent/sessions/…).
• agent-convert-from-pi — plumbing: pi JSONL → target format, with per-target knobs (session ids, models, --keep-thinking, install behavior…).

The plumbing commands are namespaced so global npm installs do not collide with other tools that already own generic names like convert-to-pi.

Harness-specific install semantics worth knowing:

• codex is the only target with registration bookkeeping: --install (the default when no output path is given) writes ~/.codex/sessions/YYYY/MM/DD/rollout-….jsonl and appends ~/.codex/session_index.jsonl — without the index entry, codex resume won't list the session.
• claude discovers sessions by directory scan: --install just drops the file into ~/.claude/projects/<encoded-cwd>/.
• cursor --install merges into the live state.vscdb (quit Cursor first; a timestamped backup of the db is made).

Agent-native by construction

These CLIs are built to be driven by agents, not just people:

• <bin> agent-context emits a versioned JSON schema of the full command surface — flags, args, subcommands — so an agent can discover capabilities without parsing --help.
• <bin> feedback "<note>" records friction reports to ~/.<bin>/feedback.jsonl (and POSTs upstream if <BIN>_FEEDBACK_ENDPOINT is set), so agent users have a channel back to the maintainers.
• --json on conversions emits machine-readable results.

Library

The format layer is importable — parse/serialize any supported session format:

import { parseSession, getActivePath } from "agent-convert/session-core";
import { importCodexToPi } from "agent-convert/codex";
import { exportPiToClaudeJsonl } from "agent-convert/claude-code";
import { detectSource } from "agent-convert/detect";

Fidelity notes

Conversion is structure-preserving but not always lossless — formats disagree about what a session even is. The honest details (thinking blocks, tool-id sanitization rules, codex compaction history, cursor tool-bubble mapping) live in docs/formats.md, field notes on each harness's session format.

Platform: macOS and Linux (CI-tested). Windows: untested — reports welcome. Reading Cursor sessions needs the native sqlite3 module (an optional dependency; everything else works without it).

Release checks

Before tagging or publishing:

npm test
npm run leakscan
npm pack --dry-run

The tag release workflow repeats the test and leak-scan gates before publishing to npm with provenance. See RELEASE_CHECKLIST.md for the full checklist.

Known issues

• No --dry-run yet; to inspect before installing, pass an explicit output path (or --no-install for codex) and look at the file.
• A wrong manual --from surfaces the underlying parser error rather than "this looks like a claude session" — prefer --from auto (the default), whose detection is reliable.
• Rare known edge cases inherited from the source toolkit: a Cursor double-wrap on one exotic bubble shape, and two latent id-handling corners (codex compaction orphans, hermes ids) that we've never hit in practice. Tracked in issues.
• npm i -g prints deprecation warnings from the optional native sqlite3 dependency chain (upstream; harmless; only Cursor support uses sqlite3).

Status

Pre-1.0: extracted from the internal toolkit we use daily at Theoric (an applied AI lab focused on the intersection of formal methods and agentic AI) to run a multi-harness agent org. v1.0 lands shortly, with the launch write-up.

MIT © Theoric Labs