session-share

Share Claude Code sessions between developers through portable file export/import.

Version: 1.0 | Privacy: Files are never uploaded to cloud unless you choose to share them

Script Path Resolution (IMPORTANT)

This skill includes helper scripts in its scripts/ subdirectory. When Claude Code loads this skill, it shows a line like:

Base directory for this skill: /path/to/.../skills/session-share

You MUST use that base directory path to resolve all script references. Store it as SKILL_DIR:

# Set SKILL_DIR to the base directory shown when this skill was loaded
SKILL_DIR="/path/shown/in/base-directory-line"

# Then run scripts as:
$SKILL_DIR/scripts/export.sh
$SKILL_DIR/scripts/import.sh ~/Downloads/session-file.json

Quick Start

# Export current session
$SKILL_DIR/scripts/export.sh
# Output: ~/session-shares/session-2024-01-20-my-feature.json

# Share the file via Slack, email, AirDrop, etc.

# Other developer imports
$SKILL_DIR/scripts/import.sh ~/Downloads/session-2024-01-20-my-feature.json
# Session appears in agent-deck, ready to continue

Commands

Export Session

Export the current Claude session to a portable file:

$SKILL_DIR/scripts/export.sh [options]

Options: | Option | Description | |--------|-------------| | --session <id> | Export specific session (default: current) | | --output <path> | Custom output path | | --include-thinking | Include Claude's thinking blocks | | --no-sanitize | Don't redact sensitive data |

Examples:

# Export current session
$SKILL_DIR/scripts/export.sh

# Export to specific location
$SKILL_DIR/scripts/export.sh --output /tmp/handoff.json

# Export specific session with thinking blocks
$SKILL_DIR/scripts/export.sh --session abc123 --include-thinking

What gets exported:

• All conversation messages (user and assistant)
• Tool calls and results
• File modifications tracked
• Session metadata

What gets redacted (by default):

• API keys and tokens
• Absolute paths (converted to relative)
• Thinking blocks (Claude's internal reasoning)

Import Session

Import a shared session file and create an agent-deck session:

$SKILL_DIR/scripts/import.sh <file-path> [options]

Options: | Option | Description | |--------|-------------| | --title <name> | Override session title | | --project <path> | Import to specific project | | --no-start | Don't auto-start the session |

Examples:

# Import and start
$SKILL_DIR/scripts/import.sh ~/Downloads/session-feature.json

# Import with custom title
$SKILL_DIR/scripts/import.sh session.json --title "Feature Work from Alice"

# Import without starting
$SKILL_DIR/scripts/import.sh session.json --no-start

Workflow: Sharing a Session

Developer A (Exporter)

1. Working in agent-deck session on a feature
2. Needs to hand off to Developer B
3. Runs: $SKILL_DIR/scripts/export.sh
4. Gets file: ~/session-shares/session-2024-01-20-feature.json
5. Sends file to Developer B via Slack DM, email, or AirDrop

Developer B (Importer)

1. Receives the session file
2. Runs: $SKILL_DIR/scripts/import.sh ~/Downloads/session-2024-01-20-feature.json
3. Session appears in agent-deck as "Imported: feature"
4. Starts session - Claude has full context from Developer A's work
5. Continues where Developer A left off

Export File Format

{
  "version": "1.0",
  "exported_at": "2024-01-20T15:30:00Z",
  "exported_by": "alice",
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Feature Implementation",
    "original_project": "/Users/alice/my-project"
  },
  "context": {
    "summary": "Last few user messages for quick context",
    "modified_files": ["src/auth.ts", "src/middleware.ts"]
  },
  "messages": [ /* JSONL records as JSON array */ ],
  "stats": {
    "total_messages": 150,
    "user_messages": 45,
    "assistant_messages": 105
  }
}

Security & Privacy

What's Redacted by Default

| Data Type | Redaction | |-----------|-----------| | API keys | Replaced with [REDACTED] | | Tokens | Replaced with [REDACTED] | | Home paths | Converted to ~ | | Username in paths | Converted to $USER | | Thinking blocks | Removed entirely |

Best Practices

1. Review before sharing - Open the export file and scan for sensitive data
2. Use direct transfer - Slack DM, email, AirDrop are more private than cloud links
3. Delete after import - Remove the file once imported successfully
4. Use --include-thinking sparingly - Thinking blocks may contain sensitive reasoning

Troubleshooting

| Issue | Solution | |-------|----------| | "Could not detect current Claude session" | Make sure you're in an agent-deck session with active Claude | | "Session file not found" | Session may not have been saved yet; send a message first | | Import shows wrong project | Use --project /correct/path to specify destination | | Large file size | Use default settings (strips thinking blocks) |

Technical Details

Session Storage

Claude stores sessions in: ~/.claude/projects/<encoded-path>/<session-id>.jsonl

Path encoding: /Users/alice/project becomes -Users-alice-project

How Import Works

1. Reads export JSON file
2. Creates directory: ~/.claude/projects/<encoded-current-project>/
3. Writes messages as JSONL: <session-id>.jsonl
4. Creates agent-deck session pointing to this path
5. Sets claude-session-id so restart uses --resume

Dependencies

• jq - JSON processing (install: brew install jq)
• agent-deck - Session management
• claude - Claude Code CLI