casr

Cross Agent Session Resumer for coding agents: resume a session created in one provider (Claude Code, Codex, Gemini, and more) using a different provider by converting through a canonical session model.

Quick Install (Recommended)

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/cross_agent_session_resumer/main/install.sh?$(date +%s)" | bash

That installer is the primary distribution path. It handles platform detection, secure artifact verification, fallback source builds, shell completions, and agent-oriented local setup in one step.

TL;DR

The Problem: AI coding sessions are siloed by provider. A useful Codex session cannot be resumed directly in Claude Code, and vice versa.

The Solution: casr discovers a session across installed providers, reads it into a canonical IR, writes a native session file for your target provider, verifies read-back fidelity, and prints the exact resume command.

Why Use casr?

Quick Example

# 1) See what providers are available
casr providers

# 2) Find a session from any provider
casr list --limit 20 --sort date

# 3) Inspect a single session
casr info 019c3eae-94c3-7d73-9b2a-9edb18f1563b

# 4) Convert that session to Claude Code format
casr cc resume 019c3eae-94c3-7d73-9b2a-9edb18f1563b

# ergonomic shorthand (auto-detects source provider from the session ID)
casr -cc 019c3eae-94c3-7d73-9b2a-9edb18f1563b   # open in Claude Code
casr -cod 019c3eae-94c3-7d73-9b2a-9edb18f1563b  # open in Codex
casr -gmi 019c3eae-94c3-7d73-9b2a-9edb18f1563b  # open in Gemini CLI

# 5) Resume in Claude Code using the generated ID
claude --resume <new-session-id>

Design Philosophy

1. Provider fungibility over lock-in: sessions are portable assets.
2. Native fidelity over lossy export: writers target real provider session formats.
3. Safety over convenience: atomic writes, conflict checks, read-back verification.
4. Permissive conversion over brittle strictness: warnings for imperfect input when conversion is still useful.
5. Observability by default: rich logs and actionable errors for every pipeline stage.

How casr Compares

Supported Providers

Notes: - Initial core focus is Claude Code, Codex, and Gemini CLI. - Additional providers are implemented through the same Provider trait model.

Installation

Primary Path: Hardened curl | bash Installer

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/cross_agent_session_resumer/main/install.sh?$(date +%s)" | bash

What this installer does for you:

High-value installer flags:

# Examples
bash install.sh --verify
bash install.sh --system --easy-mode --yes
bash install.sh --offline ./casr-x86_64-unknown-linux-musl.tar.xz
bash install.sh --no-configure --no-skill

Run bash install.sh --help for the full option set.

Alternative: From Source

git clone https://github.com/Dicklesworthstone/cross_agent_session_resumer
cd cross_agent_session_resumer
cargo build --release
./target/release/casr --help

Alternative: Cargo Local Install

cargo install --path .
casr --help

Alternative: Development Mode

cargo run -- --help

Quick Start

1. Confirm provider detection.

casr providers

1. List discoverable sessions.

casr list --sort date --limit 50

1. Inspect the source session.

casr info <session-id>

1. Convert to your target provider.

casr <target-alias> resume <session-id>

1. Resume in target provider.

# Examples
claude --resume <new-session-id>
codex resume <new-session-id>
gemini --resume <new-session-id>

Commands

Global flags:

--dry-run                 # Show what would happen without writing
--force                   # Overwrite existing target session (creates .bak backup)
--json                    # Structured JSON output
--verbose                 # Debug-level logging (casr=debug)
--trace                   # Trace-level logging (casr=trace)
--source <alias_or_path>  # Explicit source provider alias or direct session path
--enrich                  # Add optional synthetic context/orientation messages

casr <target> resume <session-id>

Convert a source session into target provider format and print the target resume command.

casr cc resume 019c3eae-94c3-7d73-9b2a-9edb18f1563b
casr claude resume 019c3eae-94c3-7d73-9b2a-9edb18f1563b   # standard name fallback
casr cod resume 40f2cb68-fed7-4cee-83de-2b63ba9b7813 --dry-run
casr codex resume 40f2cb68-fed7-4cee-83de-2b63ba9b7813 --dry-run
casr gmi resume 40f2cb68-fed7-4cee-83de-2b63ba9b7813 --source cc
casr gemini resume 40f2cb68-fed7-4cee-83de-2b63ba9b7813 --source claude
casr cc resume <session-id> --force
casr cc resume <session-id> --json

casr list

List sessions across installed providers.

casr list
casr list --provider codex
casr list --workspace /data/projects/myapp
casr list --limit 100 --sort messages

# default behavior (no args): current workspace only, top 10, styled table output
casr list

casr info <session-id>

Show non-converting session details.

casr info 019c3eae-94c3-7d73-9b2a-9edb18f1563b
casr info 019c3eae-94c3-7d73-9b2a-9edb18f1563b --json

casr providers

Show provider detection and installation evidence.

casr providers

casr completions <shell>

Generate shell completions.

casr completions bash > /tmp/casr.bash
casr completions zsh > "${fpath[1]}/_casr"
casr completions fish > ~/.config/fish/completions/casr.fish

Configuration

casr is primarily configured by environment variables.

# Optional provider home overrides for non-standard locations
export CLAUDE_HOME="$HOME/.claude"
export CODEX_HOME="$HOME/.codex"
export GEMINI_HOME="$HOME/.gemini"
export CURSOR_HOME="$HOME/.config/Cursor"
export CLINE_HOME="$HOME/.config/Code/User/globalStorage/saoudrizwan.claude-dev"
export AIDER_HOME="$HOME/.aider"
export AMP_HOME="$HOME/.local/share/amp"
export OPENCODE_HOME="$HOME/.opencode"

# Logging verbosity (alternative to --verbose / --trace)
export RUST_LOG="casr=debug"
# or:
export RUST_LOG="casr=trace"

Canonical Session Model

Core model (conceptual):

CanonicalSession
  - session_id: String
  - provider_slug: String
  - workspace: Option<PathBuf>
  - title: Option<String>
  - started_at: Option<epoch_millis>
  - ended_at: Option<epoch_millis>
  - messages: Vec<CanonicalMessage>
  - metadata: serde_json::Value
  - source_path: PathBuf
  - model_name: Option<String>

CanonicalMessage
  - idx: usize
  - role: User | Assistant | Tool | System | Other(String)
  - content: String
  - timestamp: Option<epoch_millis>
  - author: Option<String>
  - tool_calls: Vec<ToolCall>
  - tool_results: Vec<ToolResult>
  - extra: serde_json::Value

Important helpers: - flatten_content: normalizes mixed string/block content representations. - parse_timestamp: normalizes ISO strings, epoch seconds, and epoch millis. - normalize_role: maps provider-specific roles to canonical roles. - reindex_messages: keeps message indices contiguous after filtering.

Architecture

Input CLI
  casr <target> resume <session-id>
          |
          v
Provider Registry + Detection
  - discover installed providers
  - optional --source narrowing
          |
          v
Session Discovery
  - find owning provider + source path
          |
          v
Reader (Provider-specific native format -> CanonicalSession)
  Claude/Codex/Gemini/etc.
          |
          v
Validation
  - hard errors: empty / one-sided sessions
  - warnings/info: missing workspace, timestamp gaps, metadata loss
          |
          v
Writer (CanonicalSession -> target native format)
  - generate target session id
  - preserve provider-specific extras when possible
          |
          v
Atomic Write + Conflict Handling
  - temp file -> fsync -> rename
  - optional --force backup (.bak)
          |
          v
Read-Back Verification
  - re-read written session via target reader
  - compare structural fidelity
          |
          v
Output
  - human output with actionable steps
  - optional JSON output for automation

Why This Is Useful in Day-to-Day Work

casr is built for practical agent handoff problems, not only format conversion demos.

• You can switch models mid-task without rebuilding context from scratch.
• You can recover from provider outages or rate limits by moving the same session to another CLI.
• You can keep one durable transcript while changing agent personas and tool stacks.
• You can move a session into the provider that has the strongest tooling for the next step, then move back.

Common examples: - Start in Codex for rapid code edits, then resume in Claude Code for architecture review. - Start in Gemini for long context analysis, then resume in Codex for implementation. - Recover old sessions from one provider and continue them in another after a tooling migration.

CLI Ergonomics and Alias Normalization

casr supports two equivalent resume styles:

• Canonical subcommand form: casr <target> resume <session-id>
• Shorthand form: casr -cc <session-id>, casr -cod <session-id>, casr -gmi <session-id>

Shorthand flags are rewritten internally before clap parsing, so logging, JSON output, and error handling stay identical across both forms.

Alias normalization also accepts common provider tokens:

• claude maps to claude-code
• codex-cli maps to codex
• gemini-cli maps to gemini

Deterministic Resolution Algorithm

The resolver is intentionally strict and deterministic.

1. If --source parses as a path, casr bypasses provider scanning and resolves from that path.
2. If --source parses as an alias, casr searches only that provider.
3. If no source hint is provided, casr scans installed providers and collects all matches.
4. Zero matches returns SessionNotFound.
5. One match proceeds.
6. Multiple matches returns AmbiguousSessionId and includes candidates.

Path mode has additional fallback logic when a file is outside known provider roots:

1. Try extension and file-signature heuristics.
2. If heuristics fail, ask each provider parser to read the file.
3. Rank successful par