sessionport

Carry your AI agent sessions between CLIs.
Export any session to one portable, human-readable brief. Resume it in any other agent.

Why

You work in Claude Code today and OpenCode tomorrow. Codex for the weekend, Gemini for the big refactor. Every agent has its own session store, its own format, and zero memory of the others. Switch agents and your context dies: the decisions, the constraints, the files you already read, the next steps you agreed on.

sessionport is the missing layer. It reads any agent's local session store, distills the durable parts into one markdown brief, and hands that brief to any other agent as a resume prompt.

• Offline by default. Export never calls the network. Your sessions stay on your machine.
• Open format. A brief is markdown with plain frontmatter: read it, diff it, commit it.
• One command. sessionport export out of one agent, sessionport import into the next.

Supported agents

	Agent	Store
	Claude Code	JSONL transcripts (~/.claude/projects)
	Codex	JSONL sessions (~/.codex/sessions)
	OpenCode	JSON session files
	Gemini CLI	Markdown transcripts
	Hermes	SQLite session databases

Every store location can be overridden with a SESSIONPORT_* environment variable for CI and unusual setups (SESSIONPORT_CLAUDE_HOME, SESSIONPORT_CODEX_HOME, SESSIONPORT_GEMINI_HOME, SESSIONPORT_OPENCODE_HOME, SESSIONPORT_HERMES_DB).

Install

pip install sessionport
# or
uv tool install sessionport

Requires Python >= 3.11. macOS and Linux.

Quickstart

# see every session, from every agent, in one place
sessionport list

# turn a session into a portable brief
sessionport export claude-code:9f9f9f9f

# hand the brief to another agent as a resume prompt
sessionport import brief-claude-code-9f9f9f9f.md --into codex --copy

# did the brief lose anything? (optional, needs an LLM key)
sessionport score brief-claude-code-9f9f9f9f.md --source claude-code:9f9f9f9f

That's the whole loop: export, carry, import, resume.

How it works

1. Discover. sessionport list walks each agent's local session store.
2. Extract. sessionport export reads the transcript and pulls out the durable parts: goal, decisions, files touched, URLs, code blocks, next actions, constraints, key facts. Deterministic heuristics, no LLM, no network.
3. Carry. The result is one sessionport-brief/v1 markdown file.
4. Resume. sessionport import wraps the brief in a resume prompt for any target agent. Paste it, or --copy it, and the new agent continues the work without re-litigating settled decisions.

The brief format

sessionport-brief/v1 is markdown with flat YAML-flavored frontmatter. Example:

---
format: sessionport-brief/v1
source-agent: claude-code
session: 9f9f9f9f-1111-2222-3333-444444444444
exported: 2026-08-06T00:41:29Z
messages: 4
estimated_tokens: 121
---

# Session brief (claude-code)

## Goal

Fix the auth bug in login.py: the session cookie is not being set on refresh

## Decisions

- Decision: switch to httpOnly secure cookies. We'll go with SameSite=Lax...

## State: files

- login.py
- tests/test_session.py

## Constraints

- Constraint: never store tokens in localStorage.

Human-readable, git-diffable, machine-parseable. The format is versioned in the frontmatter so future revisions migrate explicitly.

Fidelity scoring

A brief is only useful if it kept what mattered. sessionport score compares a brief against its source transcript with an LLM judge and reports:

• fidelity: 0.0-1.0, how much of the session's durable knowledge survived
• missed: the specific facts the brief lost
• notes: one-sentence verdict

Opt-in and env-gated, against any OpenAI-compatible endpoint:

export SESSIONPORT_JUDGE_API_KEY=sk-...
export SESSIONPORT_JUDGE_ENDPOINT=https://api.openai.com/v1/chat/completions  # default
export SESSIONPORT_JUDGE_MODEL=gpt-4o-mini                                     # default
sessionport score brief.md --source claude-code:9f9f9f9f

The judge never runs on the export path, and transcripts are truncated to 120k characters.

CLI reference

sessionport list [--agent NAME] [--json]
sessionport export SESSION [--out FILE] [--json]
sessionport import FILE [--into AGENT] [--copy] [--out FILE]
sessionport score FILE --source AGENT:SESSION [--json]
sessionport version

SESSION is agent:id (e.g. claude-code:9f9f9f9f), or a bare id that is searched across all stores.

Development

uv sync --extra dev
make all          # lint + typecheck + test (the full gate)
make images       # regenerate docs/images

30 tests, zero-warning lint, strict mypy. See AGENTS.md for the operational reference and CONTRIBUTING.md for the contribution contract.

Roadmap

• MCP server (v0.2): the same library behind an agent-native surface
• More adapters: Cursor, Aider, Warp, Windsurf
• Local judge via Ollama for fully offline scoring
• Windows parity

License

MIT. See LICENSE. Third-party attributions in THIRD_PARTY_NOTICES.md.