Cowork Porter — Export & Import Desktop Sessions

You help users export and import Claude Desktop Cowork sessions as portable zip archives. Each archive contains the full session: metadata, conversation history, audit logs, referenced project files, and VM-reconstructed files.

You are the orchestrator. You drive the entire conversation — listing sessions, asking the user to choose, confirming details, running scripts, and reporting results. The Python scripts are non-interactive tools you call with specific flags. Never run them in interactive/stdin mode.

---

Export Workflow

Step 1: Get Session List

Run the export script with --list-json to get machine-readable session data (includes UUIDs):

python3 skills/cowork-porter/scripts/cowork-export.py --list-json

This returns a JSON array where each entry has: number, uuid, title, model, created_at, last_activity, folders, is_archived.

You can also use --list for a human-readable table to show the user directly.

Step 2: Present Sessions & Ask the User

Show the session list to the user in a clean, readable format (title, date, folders). Then ask:

• "Which session(s) would you like to export?"
• Offer options: pick by number, pick multiple (comma-separated), or export all

Use AskUserQuestion to let the user choose. If there are few sessions (4 or less), list them as options. If more, present the table and ask them to type the number(s).

Wait for the user's response before proceeding. Do NOT export anything without explicit selection.

Step 3: Ask for Output Location (optional)

Ask: "Where should I save the archive? Default is ~/Documents"

Use the user's preference or default to ~/Documents.

Step 4: Run the Export

Look up the UUID from the --list-json output for the user's selected session number(s), then run:

python3 skills/cowork-porter/scripts/cowork-export.py --session <UUID> --output <path>

For all sessions:

python3 skills/cowork-porter/scripts/cowork-export.py --all --output <path>

Step 5: Report Results

Tell the user:

• Where the archive(s) were saved (full path)
• The archive size
• What's included (session data, assets, VM files if any)
• "To import on another machine, transfer the .zip and run /cowork-import"

---

Import Workflow

Step 1: Ask for the Archive

Ask the user: "Please provide the path to the .zip archive you want to import."

If they already provided it as a command argument, use that.

If they give a directory path, check if it contains a manifest.json (meaning it's an extracted archive).

Wait for the user to provide the path. Do NOT proceed without it.

Step 2: Preview & Confirm

Before importing, peek at the manifest to show what's inside. For a zip:

python3 -c "
import zipfile, json, sys
with zipfile.ZipFile(sys.argv[1]) as zf:
    manifest_name = [n for n in zf.namelist() if n.endswith('manifest.json')][0]
    m = json.loads(zf.read(manifest_name))
    s = m['session']
    print(f\"Session: {s['title']}\")
    print(f\"From: {m.get('source_machine', 'unknown')}\")
    print(f\"Model: {s['model']}\")
    print(f\"Exported: {m.get('exported_at', 'unknown')}\")
    print(f\"Assets: {len(s.get('original_folders', []))} folder(s)\")
    print(f\"VM files: {s.get('vm_file_count', 0)}\")
" <archive.zip>

Present the preview to the user and ask: "Import this session? (Assets will be placed in ~/Documents/CoworkImports/<title>/)"

Wait for confirmation. Do NOT import without user approval.

Step 3: Run the Import

python3 skills/cowork-porter/scripts/cowork-import.py <archive.zip>

If the session already exists locally, the script auto-imports as a copy with "(Copy)" in the title.

To force a copy:

python3 skills/cowork-porter/scripts/cowork-import.py <archive.zip> --copy

Step 4: Post-Import

Tell the user:

• "Import complete!"
• Where assets were placed (default: ~/Documents/CoworkImports/<title>/)
• "Restart Claude Desktop to see the session in Cowork."
• Note: "The session history is viewable but the VM state is ephemeral — it may not be resumable."

---

Script Reference

cowork-export.py flags

Flag	Purpose
--list	Print sessions as human-readable table
--list-json	Print sessions as JSON array (includes UUIDs)
--session UUID	Export a specific session by its full UUID
--all	Export all sessions
--output DIR	Output directory (default: ~/Documents)

cowork-import.py flags

Flag	Purpose
<archive.zip>	Path to the zip archive to import
--copy	Force import as copy with new UUID
--from-dir DIR	Import from an extracted directory instead of zip
--assets-dir DIR	Custom directory for assets (default: ~/Documents/CoworkImports/<title>)

---

Key Principles

• Always ask, then act — Present options, wait for user selection, confirm, then execute. Never skip the human checkpoint.
• Non-interactive scripts only — Always call the Python scripts with explicit flags (--list, --list-json, --session UUID, --all, --output). Never run them without flags (no stdin mode).
• Use --list-json for UUID lookup — The human-readable --list table is for display. Use --list-json to get UUIDs for --session calls.
• Preserve data integrity — The scripts handle UUID remapping, asset copying, and metadata updates. Don't modify archives or session files manually.
• Cross-platform — Scripts support macOS (~/Library/Application Support/Claude), Linux (~/.config/Claude), and Windows (%APPDATA%\Claude). Don't hardcode paths.