Codex Session Librarian

A local tool for finding, forking and transferring coding-agent sessions.

A useful conversation contains more than its last answer. It records decisions, discarded approaches, tool results and the reasons a project ended up where it did. CSL helps you find that conversation and continue working from its native history.

You can reopen a Codex session, make an independent working copy, or hand a snapshot to another person. Native transfers support Codex and Claude Code. An explicit, experimental conversion path also moves supported history between the two CLIs.

CSL works with local JSONL records. It does not host your conversations or ask you to create another account. The receiving CLI uses its own authentication, configuration and tools.

Install CSL · Read an executed example · User guide

The 0.1.0 candidate adds secret review and a conversion fix under Apache-2.0. It is in upstream review; installation from the main branch does not yet include those changes.

Getting started

You need Linux, Git and Python 3.11 or later. The core uses the Python standard library; there is no pip install or virtual environment to set up. Run the following in the directory where you keep your tools:

git clone https://github.com/warevista/codex-session-librarian.git
cd codex-session-librarian
./install.sh

# If ~/.local/bin is not already on PATH:
export PATH="$HOME/.local/bin:$PATH"
csl --help

The installed launcher points to the checkout. Updating that checkout with git pull --ff-only updates the tool. Reopening a session requires the corresponding CLI and your own login. GitHub CLI is only needed for the optional team exchange; ZIP transfers work without it.

For command-by-command options, see the command reference. Team installation covers shared use.

Finding a session

The Codex library indexes local history so you can search by words and inspect the evidence behind a match. Use it when you remember what a discussion was about, but not which session contains it.

csl index --prune
csl recall "workspace publishing"
csl show SESSION_UUID

Search is lexical, not embedding-based semantic search. Read the matching snippets before assuming you have found the right conversation. Claude currently has basic session discovery through csl sessions --provider claude, rather than the complete Codex library command set.

Passing work on

The simplest handoff is a ZIP. Export a session, send the package through a channel you trust, and let the recipient inspect it before importing:

# Sender
csl export SESSION_UUID --to ~/Downloads

# Recipient, using the actual received filename
csl import handoff.csl.zip --list
csl import handoff.csl.zip --cwd ~/work/project --open

Import creates a new session identity. The source stays intact and each person continues independently. This is a snapshot handoff, not live synchronization or an automatic merge of subsequent work.

For regular team use, CSL can exchange snapshots through releases in a private GitHub repository. That exchange is separate from the CSL source-code repository. Each person connects using their own GitHub account:

csl team connect OWNER/PRIVATE-EXCHANGE
csl share SESSION_UUID --title "Workspace publishing"
csl inbox
csl receive SHARE_ID --cwd ~/work/project --open

A package contains supported conversation records and already embedded assets. It does not bring the project repository, installed tools, credential files or external attachments with it. The recipient needs a suitable local working directory.

See transfers and team sharing for package validation, repeat imports and other details.

Working forks

A native Codex clone is useful when you want an agent to investigate a separate direction without modifying the original conversation. The agent visibility option keeps that copy outside the usual interactive session picker:

csl native-clone SESSION_UUID --visibility agent
# Continue using the codex exec resume command CSL prints.

Clones receive a fresh UUID. You can also create an archived snapshot or an ordinary interactive copy. Visibility is a presentation choice, not access control or filesystem isolation. CSL does not automatically delete an agent fork when its task ends.

Moving between CLIs

Native handoffs keep the same CLI format. Cross-CLI conversion is a separate, explicit operation through the versioned csl-conversation format:

csl convert SESSION_UUID --to claude --cwd ~/work/project
csl receive SHARE_ID --target codex --cwd ~/work/project --open

Conversion supports a bounded profile of text, completed tools, references, embedded images and PDFs. Media conversion needs an optional isolated decoder. Unsupported or inconsistent state can be rejected; CSL does not silently promise to recover an entire opaque checkpoint.

In CSL, --provider selects or asserts the source CLI; it does not request conversion. Use --target or --to for that. The maintained provider matrix and conversion contract describe the full boundaries.

A worked example

This example was run with a synthetic conversation. An early draft used cobalt and Postgres; a later instruction changed that to amber42 and SQLite. A historical tool result contained a third fact, DEMO-617. The continuation question asked for the latest decisions and that tool-only fact without supplying the answers.

The example exports and inspects a ZIP, imports a new identity, and converts a Claude fixture to Codex. Two real Codex continuations then recovered all three facts. You can read the recorded steps below. These are results from an executed fixture, not a terminal running in this page.

Loading the example…

Recorded evidence (JSON) · Reproduction script

Limits and privacy

Review conversation contents before sharing them. Tool output and ordinary messages can contain credentials or other private information, even when no credential files are collected. Private GitHub access and checksums do not remove that information.

The 0.1.0 candidate adds local secret detection before export or share. For each finding, the user can keep it, scrub it from the output copy, or cancel. Non-interactive use requires an explicit policy when findings exist. These changes are in the release PR, pending upstream integration.

Detection is partial. Binary attachments, opaque state and values outside the recognized patterns need separate review. A successful scan does not certify that a conversation is safe to share. Scrubbing changes the exported copy, not the source history.

CSL does not copy authentication or translate permissions between tools. Imported instructions are historical context, not new authority to execute a task. Account access, model availability and the behavior of future CLI versions remain outside the transfer’s guarantees.

The project

CSL is a project by Vitral. It grew out of the practical need to locate and hand over useful agent conversations. The tool can be used independently of Vitral’s workspace product.

Apache-2.0 has been selected for the 0.1.0 candidate, including attribution to Vitral. Release PR #1 contains the license, secret-review changes, conversion correction and reproducible demo. The candidate is awaiting upstream integration; a prepared version is not a published release.

Contributions should start with a reproducible problem, synthetic history and a focused change. Reports about a real workflow are useful; please do not post private conversation exports or credentials in public issues. The issue tracker is the place for public bug reports and proposals.

Codex and Claude Code are products of their respective owners. Their software, services and marks are not licensed by the CSL project.