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 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 supported on Windows.
python -m pip install --no-index --find-links "https://github.com/x0c/sesskit/releases/expanded_assets/v0.3.4" 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 describe
sesskit verify --sample 30After changing parsers or load wiring, run sesskit verify: it cross-checks conversation, v1 events, typed activity, and incremental readers, and reports per-runtime counts, outcomes, violations, and timings — never content or paths. A failing check exits non-zero.
Snapshot commands print one JSON envelope:
{"ok": true, "data": {...}, "error": null, "meta": {"version": 1, "tool_version": "0.3.4"}}from sesskit import load_session_conversation, 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"
# 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; if a runtime exposes no data, SessKit reports it as unavailable — never as zero, and never as 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.
If your automation launches real agent sessions (tests, evals, probes), 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-oriented subset, 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.
- Launching or controlling agents
- 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.
Install users can stop at Install: SessKit is not on PyPI yet.
Maintainers verify an existing release without trusting the working tree:
python scripts/publish.py verify --version 0.2.23 --check-onlyExpected v0.2.23 asset hashes (also recorded by the GitHub release API):
- wheel
sesskit-0.2.23-py3-none-any.whl:sha256:30fcf7e063c29d594262a8223b368af2d0e6bd8958e3b65792ada2d9a8964d81 - sdist
sesskit-0.2.23.tar.gz:sha256:acc70a9033f0f9c945ad4f0df53600f61ff5ea5417580df5c930410c2d76f084
Local publish is not CI-only. Validate first, then upload with credentials from the environment only — the helper has no password/token options, so secrets never appear on argv or in shell history. Store the PyPI token once in your system secret store (prompts for the value; nothing secret is typed into the command line), then reference it at upload time:
python scripts/publish.py check-dist --version 0.2.23 --dist dist
security add-generic-password -s pypi-sesskit -a __token__ -w
TWINE_USERNAME=__token__ TWINE_PASSWORD="$(security find-generic-password -s pypi-sesskit -w)" \
python scripts/publish.py upload --version 0.2.23 --dist dist --confirm-upload(On Linux use your secret store instead, e.g. secret-tool lookup server pypi.org, keeping the same pattern: no literal secret in the command.)
CI publish runs .github/workflows/publish-pypi.yml
on a v* tag push (or manual dispatch of an existing tag) via PyPI Trusted
Publishing — no stored API token (GitHub mints a short-lived OIDC credential
per run).
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. |
MIT