Languages: English | 简体中文
Parse and export local Claude Code, Codex CLI, Cursor, OpenCode, Kimi Code, Pi, and Antigravity agent session files from disk into one JSON schema.
This is a Python library and JSON CLI — not a TUI, not a session manager. Other tools integrate by shelling out to sesskit or by validating against the published JSON Schema.
- Feed local conversations into your own search index or knowledge base.
- Inspect native usage and historical outcomes without parsing runtime files.
- Follow incremental events in your own session client.
Start with the integration guide and three runnable examples. No model account or API key is needed to read existing local history.
Third-party programs can use open_message_stream(session) or sesskit stream
to display message updates. Host-provided native feeds deliver partial text;
unavailable feeds automatically fall back to persisted history. See the
message streaming guide for the Python bridge,
JSONL protocol and observation budgets. Available in v0.2.25 and later.
SessKit is not on PyPI yet. Install the fixed-release wheel in your project's virtual environment.
Requires Python 3.10+. Supported platforms: macOS and Linux (agents store history under ~). Not claimed on Windows.
python -m pip install --no-index --find-links "https://github.com/x0c/sesskit/releases/expanded_assets/v0.3.11" sesskit
python -m sesskit describeFor an existing pip-managed installation, sesskit upgrade --dry-run checks the
latest release without changing anything, and sesskit upgrade performs a
forward-only upgrade and verifies the installed version. No gh call, manual tag
discovery, pip show, or v-prefix conversion is needed. Package-manager-owned
installations (for example Homebrew) keep their owner's upgrade route.
The same command works on macOS and Linux; no Git or local build tools are needed.
Need a virtual environment first? Run python3 -m venv .venv && . .venv/bin/activate.
The installer selects a prebuilt Rust-accelerated wheel for macOS/Linux on
Apple Silicon, Intel/AMD or ARM64 where available, or a pure-Python compatibility
wheel. Existing Python APIs and JSON output are unchanged. Set SESSKIT_NATIVE=0
to use the Python path. Source builds require Rust 1.88+; wheel installs do not.
For source contributions, clone the repository and run python -m pip install -e ..
sesskit list --top 5 --compact
sesskit search refactor --top 3
sesskit show <session-id-or-prefix> --full
sesskit share <session-id> --out /tmp/share.json
sesskit export --since 7d --out /tmp/week.json
sesskit skills --limit 20
sesskit describe
sesskit verify --sample 30After changing parsers or load wiring, sesskit verify is the required
real-history consistency gate. It checks conversation, v1 events, typed
activity, and supported incremental readers against one another, and reports
per-runtime counts, outcomes, violations, and timings — never content or
paths. Scan/load/reader/probe failures prevent a pass; a runtime with no
samples is marked unverified, not passed. Kimi's documented lack of typed
activity and incremental readers is expected, while its legacy checks still
run. Reads overlapping a live source change are inconclusive, not passes.
This verifies internal consistency, not semantic correctness against an
independent oracle. The command exits non-zero when verification fails or is
unverified.
Snapshot commands print one JSON envelope:
{"ok": true, "data": {...}, "error": null, "meta": {"version": 1, "tool_version": "0.3.11"}}from sesskit import load_session_conversation, load_skills, refresh_session
from sesskit.registry import default_registry
from sesskit.transcript import load_events, SCHEMA_ID
registry = default_registry()
sessions = registry.scan_all(limit=20)
for runtime_id, items in sessions.items():
for session in items[:3]:
messages = load_session_conversation(session)
events = load_events(session) # SCHEMA_ID == "sesskit.transcript/v1"
skills = load_skills(session) # SCHEMA_ID == "sesskit.skills/v1" (explicit vs auto)
# Refresh this session between scans; None if its history is gone.
fresh = refresh_session(session)The release includes reconciled token/cost data and historical timing/rates.
sesskit usage pi:SESSION_ID
sesskit usage pi:SESSION_ID --message-id MESSAGE_ID
sesskit performance pi:SESSION_ID
sesskit performance pi:SESSION_ID --detail records --limit 100Python: load_usage, summarize_usage, UsageSelection, and load_performance.
For one token number, use data.summary.metrics.total_tokens.total_to_report
and keep its adjacent coverage; partial data is not a complete total. Keep
per-call/message/turn/session scope and native timing meanings; missing values
are not zero and client timing is not provider decode speed.
SessKit supplies data, not evaluation scores. See the integration guide
for runtime support, selectors, examples and schemas.
| Runtime | Role |
|---|---|
| Claude Code | Parse / export local session files |
| Codex CLI | Parse / export local session files |
| Cursor Agent | Parse / export local session files |
| OpenCode | Parse / export local session files |
| Kimi Code | Parse / export local session files |
| Pi | Parse / export local session files |
| Antigravity | Parse / export local session files |
See the capability matrix for typed
activity, incremental reading, questions, native turn markers, usage, and compaction.
Capabilities are also returned by sesskit describe; unavailable data is not zero
or proof of success.
Session history is read-only. SessKit does not launch agents, resume chats, or
write history. The explicit upgrade command changes only its own pip-managed
package installation.
Automation that launches real agent sessions (tests, evals, probes) can keep them out of listings by placing an empty .sesskit-ignore file in its workspace root; see docs/CONTRACT.md.
See schemas/ and docs/CONTRACT.md.
| Need | Interface |
|---|---|
| Plain conversation | Python load_session_conversation, or CLI show / export |
| Compatible JSON events from another language | CLI share + transcript v1 schema |
| Rich evidence, usage, outcomes, or incremental readers | Python API; see the integration guide |
Transcript v1 is a compatibility projection, not every field in the richer Python
model. sesskit search matches titles and excerpts, not full conversation text.
Exported content may contain secrets; review it before sharing or uploading.
If you run multiple AI coding agents daily, check out the rest of the local-first toolkit:
| Repository | Description |
|---|---|
| corral | Run Claude Code, Codex, OpenCode, Cursor & Pi side-by-side in a terminal session manager, then continue from iPhone or Mac. |
| subswap | Check remaining quota and switch Claude Code, Codex, Cursor, Kimi Code & OpenCode accounts without logging out. |
| agentsync | Sync AGENTS.md, CLAUDE.md, skills, and MCP configs across coding agents from one local source of truth. |
| agent-doc-skills | Navigable project knowledge base skills (doc-init, doc-update, doc-compact) so coding agents don't rediscover your repo every session. |
| agent-session-control | Launch and track local coding-agent sessions from Python (library + JSON CLI + ACP adapter); history observation is delegated to SessKit. |
Maintainers: see docs/MAINTENANCE.md.
- Launching or controlling agents — use agent-session-control instead
- A terminal UI or session manager
- Writing or deleting session history
- Go/TypeScript bindings (consume the CLI/schema instead)
Share your integration use case: which runtimes you read, what output you need, and what blocked you. Do not post credentials or complete private transcripts; synthetic or redacted examples help.
MIT