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

Quick Start

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

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

# Other developer imports
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:

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
scripts/export.sh

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

# Export specific session with thinking blocks
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:

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
scripts/import.sh ~/Downloads/session-feature.json

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

# Import without starting
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: 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: 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

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

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