Agent Skills: Session Sync

Session Sync

Export Claude Code sessions to project-organized markdown. Integrates with QMD for semantic search.

Quick Start

# First time setup (cross-platform)
python ~/.claude/skills/session-sync/scripts/session-sync.py setup

# Export all sessions
python ~/.claude/skills/session-sync/scripts/session-sync.py export --all

# Search sessions
python ~/.claude/skills/session-sync/scripts/session-sync.py search "authentication"

Note: Use python on Windows, python3 on macOS/Linux. The setup command auto-detects your platform.

Commands

| Command | Description | |---------|-------------| | setup | Interactive onboarding (auto-detects platform) | | status | Show config, QMD status, export stats | | export | Export sessions. Filters: --all, --days N, --project NAME, --since DATE | | index | Re-index exported sessions in QMD | | search QUERY | BM25 keyword search via QMD | | vsearch QUERY | Semantic vector search via QMD | | config | Set --target-folder, --collection-name | | list-projects | List available Claude Code projects | | sync | Sync current session (used by Stop hook or manually) |

Cross-Platform Paths

| Platform | Claude Data | Default Output | |----------|-------------|----------------| | macOS | ~/.claude | ~/Documents/Claude-Sessions | | Linux | ~/.claude | ~/Documents/Claude-Sessions | | Windows | C:\Users\<user>\.claude | C:\Users\<user>\Documents\Claude-Sessions |

Procedures

Setup (First Time)

1. Run setup (auto-detects platform):

   # macOS/Linux
   python3 ~/.claude/skills/session-sync/scripts/session-sync.py setup
   
   # Windows (PowerShell)
   python $env:USERPROFILE\.claude\skills\session-sync\scripts\session-sync.py setup
   

2. Follow prompts to set target folder and install QMD if needed

3. Export sessions:

   python ~/.claude/skills/session-sync/scripts/session-sync.py export --all
   

Export Sessions

1. Determine filter from user request:

   • "all sessions" → --all
   • "last N days" → --days N
   • "project X" → --project X
   • "since DATE" → --since YYYY-MM-DD

2. Run export:

   python ~/.claude/skills/session-sync/scripts/session-sync.py export [FLAGS]
   

3. Re-index QMD:

   python ~/.claude/skills/session-sync/scripts/session-sync.py index
   

Search Sessions

1. Keyword search:

   python ~/.claude/skills/session-sync/scripts/session-sync.py search "QUERY" -n 10
   

2. Semantic search:

   python ~/.claude/skills/session-sync/scripts/session-sync.py vsearch "QUERY" -n 10
   

Sync Current Session

For manual sync (without hook):

export CK_SESSION_ID=<session-id>
python ~/.claude/skills/session-sync/scripts/session-sync.py sync

Troubleshooting

QMD Not Found

macOS/Linux:

npm install -g qmd
# or
bun install -g qmd

Windows:

npm install -g qmd

If using nvm, ensure QMD is installed in active Node version.

QMD Vector Search Crash (Bun)

If you see NAPI finalizer errors with vsearch:

# Add to shell profile (~/.zshrc, ~/.bashrc, or PowerShell $PROFILE)
alias qmd="QMD_RUNTIME=node qmd"

No Sessions Found

Check Claude Code data exists:

• macOS/Linux: ls ~/.claude/projects/
• Windows: dir $env:USERPROFILE\.claude\projects\

Output Format

Sessions exported to {target_folder}/Claude-Sessions/{project-name}/:

---
type: claude-session
project: vibelabs-agentic-platform
date: 2026-03-03
session_id: abc12345-...
title: "Implement auth module"
messages: 42
created: 2026-03-03T10:00:00Z
last_activity: 2026-03-03T12:30:00Z
cwd: /path/to/project
git_branch: main
---

Configuration

Config file: ~/.claude/skills/session-sync/config.json

| Key | Default | Description | |-----|---------|-------------| | target_folder | ~/Documents | Parent folder for Claude-Sessions | | collection_name | claude-sessions | QMD collection name | | auto_sync | false | Whether hook is configured |

References

• procedures/setup.md - Detailed setup steps
• procedures/install-qmd.md - QMD installation guide
• procedures/setup-hook.md - Auto-sync hook configuration
• references/schema.md - Session markdown schema