Historical Session Sync

Sync sessions that were created before you started using GuideMode Desktop.

Overview

When you first enable a provider in GuideMode, it only monitors new sessions going forward. Historical Session Sync lets you upload sessions that already exist on your machine.

When to Use Historical Sync

Good Use Cases:

• Just installed GuideMode and want to include past work
• Want to analyze historical trends
• Need complete project history for team
• Migrating to GuideMode from another tool

Skip if:

• Only care about future sessions
• Past sessions contain sensitive data
• Want to start fresh

How It Works

1. Scan

GuideMode searches provider directories for existing session files:

What’s Scanned:

• All projects in provider directory
• Only selected projects (if using “Selected only”)
• Sessions from any time period
• Already-synced sessions are detected and skipped

Scan Time:

• Small projects: seconds
• Large projects: 1-2 minutes
• Very large: 5+ minutes

2. Review

After scanning, review what was found:

Information Shown:

• Total sessions found
• Projects included
• Date range of sessions
• Estimated sync time

3. Sync

Upload the found sessions to GuideMode server:

Process:

• Sessions queued for upload
• Batch processing in background
• Real-time progress indicator
• Error handling for failed uploads

4. Complete

When finished, all historical sessions are available on the server:

Step-by-Step Guide

Prerequisites

1. Provider enabled - Enable the provider first
2. Sync mode set - Choose Metrics Only or Full
3. Signed in - Must be logged into GuideMode server
4. Projects selected - Choose which projects to include

Step 1: Navigate to Historical Sync

1. Open GuideMode Desktop
2. Go to Configuration page
3. Scroll down on any enabled provider card
4. Find “Historical Session Sync” section

Step 2: Start Scan

1. Click “Scan for Sessions”
2. Wait while GuideMode searches directories
3. Watch the progress indicator

Behind the scenes:

• Reading provider session files
• Checking if already synced
• Filtering by selected projects
• Building session list

Step 3: Review Results

After scanning completes:

Check:

• Session count: How many were found
• Projects: Which projects are included
• Date range: Oldest to newest session
• Details: Click “Show Details” to see session list

Session Details View:

• Project name / File name
• Session start time
• Provider type

Step 4: Sync Sessions

If you’re happy with the results:

1. Click “Sync X Sessions”
2. Confirm if prompted
3. Monitor the progress:
   • Current session being synced
   • Progress percentage
   • Errors (if any)

Sync Speed:

• Metrics Only: ~10 sessions/second
• Full transcripts: ~2-5 sessions/second
• Depends on session size and network speed

Step 5: Handle Errors (If Any)

If some sessions fail:

Common Errors:

• Network timeout
• File format changes
• Corrupted session files
• Permission issues

Resolution:

• Retry: Click “Retry Failed”
• Skip: Ignore failed sessions
• Check logs: View detailed error in Logs page

Sync Modes and Historical Data

Metrics Only

When using Metrics Only mode for historical sync:

What’s Synced:

• Session metadata and timestamps
• Performance metrics
• Usage statistics
• AI-generated summaries (if you have AI keys configured)

What Stays Local:

• Full transcripts
• Code snippets
• Specific file names
• Exact commands

Transcript & Metrics

When using Full mode:

What’s Synced:

• Everything from Metrics Only, plus:
• Complete conversation transcripts
• All code generated
• File paths and names
• Commands executed

Privacy Considerations

Before Syncing

Review Sessions: Click “Show Details” to see what will be synced

Check for:

• Proprietary code or trade secrets
• API keys or credentials in conversations
• Customer data or PII
• Sensitive file paths

During Sync

Pause Anytime: Close GuideMode to pause (resumes later)

Cancel: Click “Cancel” to stop sync

After Sync

Delete if Needed: Go to web interface to delete specific sessions

Change Mode: Future sessions can use different mode

Managing Historical Sync

Reset Progress

To start over:

1. Click “Reset”
2. Confirm reset
3. Scan again from scratch

Use when:

• Want to re-scan after adding projects
• Previous scan had errors
• Provider directory changed

Incremental Sync

After initial historical sync, you can sync new historical sessions:

1. Create more sessions with your AI provider
2. Scan again - only new sessions are found
3. Sync just the new ones

Note: Already-synced sessions are automatically skipped.

Per-Provider Sync

Each provider has independent historical sync:

• Claude Code: Sync Claude Code history
• GitHub Copilot: Sync Copilot history separately
• OpenCode: Independent sync
• Codex: Independent sync

Tip: Start with one provider, verify it works, then sync others.

Troubleshooting

No Sessions Found

Problem: “0 sessions found” after scan

Solutions:

1. Verify provider is installed and has been used
2. Check home directory path is correct
3. Look for session files manually:
   • Claude Code: ~/.claude/projects/*/sessions/*.jsonl
   • Copilot: ~/.copilot/sessions/*.json
   • OpenCode: ~/.local/share/opencode/storage/
4. Ensure at least one project is selected

Scan Takes Forever

Problem: Scan doesn’t complete

Solutions:

1. Check for extremely large projects
2. Verify disk isn’t full
3. Check file permissions
4. Restart GuideMode and try again

Sync Fails

Problem: All sessions fail to sync

Solutions:

1. Network: Check internet connection
2. Server: Verify GuideMode server is accessible
3. Auth: Ensure you’re logged in
4. Quota: Check if you’ve exceeded storage quota
5. Retry: Click “Retry Failed Uploads”

Partial Sync

Problem: Some sessions sync, others fail

Solutions:

1. Review errors: Check error messages
2. File format: Some old sessions may use incompatible format
3. Corrupted files: Some files may be incomplete
4. Skip: It’s okay to skip failed sessions

Duplicate Sessions

Problem: Same session appears multiple times

This shouldn’t happen: GuideMode detects duplicates automatically.

If it does:

1. Delete duplicates from web interface
2. Report the issue (helps us improve)

Best Practices

Before Historical Sync

1. Review sync mode - Ensure correct privacy level
2. Select projects - Only include what you need
3. Test with small project - Verify sync works
4. Check disk space - Ensure enough space for scan

During Sync

1. Stay connected - Keep internet connection stable
2. Don’t close app - Let sync complete
3. Monitor errors - Watch for failures
4. Be patient - Large syncs take time

After Sync

1. Verify on web - Check sessions appear correctly
2. Delete sensitive sessions - If any slipped through
3. Review insights - Start analyzing historical trends
4. Set expectations - Historical metrics establish baseline

FAQ

Q: Will historical sync interfere with current work? A: No. Sync runs in background and doesn’t affect file watching.

Q: Can I stop and resume historical sync? A: Yes. Quit GuideMode anytime. Next time it will resume where it left off.

Q: How much will historical sync cost? A: Currently free. Future pricing (if any) will be announced in advance.

Q: Can I re-sync historical sessions? A: Sessions already synced are skipped. To re-sync, delete from web first.

Q: What if I don’t want all historical sessions? A: Use “Selected projects” to exclude certain projects before scanning.

Q: Can I see which sessions will be synced before syncing? A: Yes. Click “Show Details” after scanning to see the list.

Next Steps

• Sync Modes - Understanding sync options
• Server Features - What to do with synced data
• Privacy Guide - Privacy implications