portable-resume 0.3.0

Offline, local-only portable resume skills across coding agents

portable-resume-skills

Offline, local-only context migration · 8 sources × 8 hosts · inert handoff, not live restore

English · 繁體中文 · 简体中文 · 日本語 · 한국어 · Español · Português · Français · Deutsch · Русский · العربية · हिन्दी · All languages

Clean-room-oriented Agent Skills for migrating bounded local coding-agent context into a fresh session. Readers never invoke the source agent CLI and never add a network path; recovered text is marked untrusted and stale.

Current tree: 0.3.0 local release candidate · 64/64 packaging cells · 64/64 installed-runner cells · six native local plugin/extension installs verified · host UI activation still not-run. The archived v0.2.3 dual-OS claim remains historical until a v0.3.0 tag completes the release workflow.

Sources and destinations

Resume skill	Source store family
resume-claude	Claude Code projects JSONL
resume-codex	Codex SQLite / rollout JSONL
resume-cursor	Cursor CLI chats / Desktop vscdb
resume-opencode	OpenCode SQLite / file store
resume-antigravity	Antigravity transcript JSONL
resume-grok	Grok Build session updates JSONL
resume-qwen	Qwen Code chat JSONL, including archived chats
resume-kimi	Current Kimi Code wire JSONL + legacy Kimi CLI context JSONL

Destination profiles: Claude Code, Codex, Cursor, OpenCode, Antigravity, Grok Build, Qwen Code, and current Kimi Code CLI.

Requirements

• Python 3.11+; CI covers 3.11–3.14 on Ubuntu and macOS.
• Product runtime is stdlib-only.
• Optional trusted zstd binary for compressed Codex rollouts.

Quick start

Install from the current checkout, then install every destination profile into its user-global Skill root:

pipx install .
install-resume-skills quick-install all

After a PyPI release, replace pipx install . with pipx install portable-resume. To install only one host or one project:

install-resume-skills quick-install qwen
install-resume-skills quick-install qwen --project "$PWD"

The lower-level transactional command remains available for previews, custom roots, verification, and uninstall:

# Inspect capabilities and the 8×8 matrix
PYTHONPATH=src python3 scripts/portable-resume self-check --json
PYTHONPATH=src python3 scripts/install-resume-skills matrix --json
PYTHONPATH=src python3 scripts/install-resume-skills hosts

# Read a synthetic Claude fixture
PYTHONPATH=src python3 scripts/portable-resume claude show latest \
  --cwd /workspace/project \
  --source-root tests/fixtures/claude/s-cla-01-ordered-parent-chain/root \
  --format handoff

# Preview, install, verify, and uninstall one destination
PYTHONPATH=src python3 scripts/install-resume-skills install \
  --host qwen --scope project --project "$PWD" --dry-run --json
PYTHONPATH=src python3 scripts/install-resume-skills install \
  --host qwen --scope project --project "$PWD" --json
PYTHONPATH=src python3 scripts/install-resume-skills verify \
  --host qwen --scope project --project "$PWD" --json

Full roots, activation grammar, direct archives, and marketplace/plugin routes are in docs/install-hosts.md. Release assets are generated with:

python3 scripts/build_host_packages.py --output-dir host-packages

This produces eight direct-skill ZIPs plus supported Claude, Codex, Cursor, Antigravity, Grok, Qwen, and Kimi plugin/marketplace bundles. OpenCode remains a direct Skill install because its plugin surface is executable JavaScript/TypeScript rather than a Skill bundle.

Skill contract

python3 <skill>/scripts/run_reader.py show latest --cwd "$PWD" --json
python3 <skill>/scripts/run_reader.py show <session-id|path|text> --cwd "$PWD" --json
python3 <skill>/scripts/run_reader.py list --cwd "$PWD" --json

Activate resume-<source> using the host's documented grammar, run only the installed reader, and summarize its inert output after re-checking the repository. portable-resume/request-v1 files remain an optional advanced interface.

Optional web search and Context7

The reader itself stays offline. After reviewing and minimizing recovered text, the destination host may use its own web tools or Context7 MCP for current documentation. Qwen and Kimi setup, data-flow boundaries, and safe examples are in docs/network-integrations.md.

Safety invariants

• Source stores are immutable; stable no-follow reads fail closed on races.
• Source CLIs are never invoked.
• Recovered text is inert/untrusted and only best-effort redacted.
• Installer paths are contained under the selected skill root.
• Non-owned collisions require --force-with-backup; multi-root installs compensate on failure.
• Shared physical roots with divergent host renders fail before mutation.

Tests and CI/CD

Run all required local gates:

python3 scripts/self_verify.py
python3 scripts/check_secrets.py
PYTHONPATH=src python3 -m unittest discover -s tests -q
PYTHONPATH=src python3 scripts/smoke_installed_matrix.py

.github/workflows/ci.yml runs those gates across Ubuntu/macOS and Python 3.11–3.14, then builds and smoke-installs the exact wheel and sdist. .github/workflows/release.yml accepts only annotated vMAJOR.MINOR.PATCH tags reachable from main, re-runs dual-OS gates, builds release bytes once, tests those exact bytes, creates SHA-256 checksums and GitHub attestations, stages a GitHub Release, and publishes through PyPI Trusted Publishing when the protected pypi environment is configured.

A configured workflow is not release proof: v0.3.0 remains unclaimed until its Actions URL and SHA are archived in docs/evidence-summary.md.

Key documentation

• docs/i18n/README.md — 12 localized quick-start guides
• docs/STATUS.md — done/not-done truth
• docs/install-hosts.md — per-host installation
• docs/source-formats.md — format and provenance registry
• docs/host-ui-smoke.md — live activation evidence protocol
• docs/release-claim.md — release gates and external setup
• SECURITY.md — threat model
• CONTRIBUTING.md — contributor workflow

License and limitations

Apache-2.0. This project is not affiliated with the host vendors. Do not copy ~/.grok/bundled/skills/** into this tree.

Host UI/picker activation is still not-run; Cursor's full bubble graph is not claimed; redaction is not complete DLP; Qwen/Kimi web or MCP calls are optional host-side actions and never implicit reader behavior.