{"id":51771171,"url":"https://github.com/danielgerlag/copilot-sync","last_synced_at":"2026-07-20T01:04:35.660Z","repository":{"id":367189282,"uuid":"1175525013","full_name":"danielgerlag/copilot-sync","owner":"danielgerlag","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-07T21:22:45.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-13T03:26:27.989Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielgerlag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T20:37:47.000Z","updated_at":"2026-03-07T21:22:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danielgerlag/copilot-sync","commit_stats":null,"previous_names":["danielgerlag/copilot-sync"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/danielgerlag/copilot-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgerlag%2Fcopilot-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgerlag%2Fcopilot-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgerlag%2Fcopilot-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgerlag%2Fcopilot-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielgerlag","download_url":"https://codeload.github.com/danielgerlag/copilot-sync/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgerlag%2Fcopilot-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35669290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-20T01:04:34.963Z","updated_at":"2026-07-20T01:04:35.650Z","avatar_url":"https://github.com/danielgerlag.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# copilot-session-sync\n\nAn MCP server that syncs your GitHub Copilot CLI and VS Code extension sessions across machines, Codespaces, and environments via a private GitHub repository.\n\n## Why?\n\nYour Copilot sessions (conversation history, plans, checkpoints, artifacts) are stored locally in `~/.copilot/`. When you switch machines, open a Codespace, or work from a different environment, those sessions are gone. This tool fixes that.\n\n## How It Works\n\n`copilot-session-sync` exposes MCP tools that you can invoke directly from Copilot CLI or VS Code Copilot chat. Behind the scenes, it uses a private GitHub repository (`{your-username}/.copilot`) as cloud storage for your sessions.\n\n- **Bidirectional sync** — pushes new/updated local sessions and pulls new/updated remote sessions\n- **Session-level merge** — uses `updated_at` timestamps to determine which side wins\n- **SQLite DB merge** — row-level merge of the `session-store.db` database with FTS5 index rebuild\n- **Auto-creates** the private `.copilot` repo if it doesn't exist\n- **Cross-platform** — works on macOS, Linux, and Windows (no native compilation required)\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js** \u003e= 20\n- **GitHub CLI** authenticated (`gh auth login`), **or** a `GITHUB_TOKEN` environment variable\n\n### Option 1: Use with `npx` (recommended — no install needed)\n\nJust add the MCP server config and start using it. No clone, no build, no install.\n\n### Option 2: Install globally\n\n```bash\nnpm install -g copilot-session-sync\n```\n\n### Option 3: Clone and build from source\n\n```bash\ngit clone https://github.com/danielgerlag/copilot-sync.git\ncd copilot-sync\nnpm install\nnpm run build\n```\n\n## Configuration\n\n### GitHub Copilot CLI\n\nAdd to your MCP configuration file (typically `~/.config/github-copilot/mcp.json` or as configured):\n\n**Using npx (recommended):**\n```json\n{\n  \"mcpServers\": {\n    \"copilot-session-sync\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"copilot-session-sync\"]\n    }\n  }\n}\n```\n\n**Using global install:**\n```json\n{\n  \"mcpServers\": {\n    \"copilot-session-sync\": {\n      \"command\": \"copilot-session-sync\"\n    }\n  }\n}\n```\n\n**Using local build:**\n```json\n{\n  \"mcpServers\": {\n    \"copilot-session-sync\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/copilot-sync/dist/index.js\"]\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot Chat)\n\nAdd to your VS Code `settings.json` (`Cmd+Shift+P` → \"Preferences: Open User Settings (JSON)\"):\n\n**Using npx (recommended):**\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"copilot-session-sync\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"copilot-session-sync\"]\n      }\n    }\n  }\n}\n```\n\n**Using global install:**\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"copilot-session-sync\": {\n        \"command\": \"copilot-session-sync\"\n      }\n    }\n  }\n}\n```\n\n**Using local build:**\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"copilot-session-sync\": {\n        \"command\": \"node\",\n        \"args\": [\"/path/to/copilot-sync/dist/index.js\"]\n      }\n    }\n  }\n}\n```\n\n### GitHub Codespaces\n\nAdd the same VS Code configuration to your dotfiles or devcontainer settings. The `npx` approach works out of the box since Node.js is available in Codespaces. Make sure `gh` is authenticated or `GITHUB_TOKEN` is set (Codespaces usually have this automatically).\n\n## MCP Tools\n\nOnce configured, these tools are available in Copilot CLI and VS Code Copilot chat:\n\n### `sync_sessions`\n\nBidirectional sync of all sessions. Compares local and remote by session ID and `updated_at` timestamps. Pushes new/updated local sessions, pulls new/updated remote sessions, and merges the session-store database.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `dry_run` | boolean (optional) | Preview what would be synced without making changes |\n\n### `list_remote_sessions`\n\nLists all sessions (local and remote) with their sync status.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filter` | string (optional) | Filter by summary text or repository name |\n\nStatus icons:\n- ✅ Synced — session is identical on both sides\n- 📤 Local only — session exists locally but not in remote\n- 📥 Remote only — session exists in remote but not locally\n- ⬆️ Local newer — local version is more recent\n- ⬇️ Remote newer — remote version is more recent\n\n### `pull_session`\n\nPull a specific session from the remote repo to your local machine.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `session_id` | string (required) | UUID of the session to pull |\n\n### `push_session`\n\nPush a specific local session to the remote repo.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `session_id` | string (required) | UUID of the session to push |\n\n### `sync_status`\n\nShow sync overview — last sync time, which machine last synced, session counts, and what needs syncing.\n\n## Usage Examples\n\nJust talk to Copilot naturally. The MCP tools are invoked automatically based on your request:\n\n```\nYou: Sync my sessions\n→ Calls sync_sessions — pushes 5 new sessions, pulls 2 from remote\n\nYou: Show me what sessions need syncing\n→ Calls sync_status — shows 3 local-only, 1 remote-only, 42 synced\n\nYou: What sessions do I have about drasi?\n→ Calls list_remote_sessions with filter \"drasi\" — shows matching sessions\n\nYou: Pull session 03a59c35-d7f8-4e35-8307-beb207d80fb0\n→ Calls pull_session — downloads that session from remote\n\nYou: Push this session to remote\n→ Calls push_session with the current session ID\n\nYou: Do a dry run sync first\n→ Calls sync_sessions with dry_run=true — previews without changes\n```\n\n## Environment Variables\n\nAll configuration is optional — the tool auto-detects everything it can.\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `GITHUB_TOKEN` | GitHub personal access token | Falls back to `gh auth token` |\n| `GITHUB_USER` | GitHub username | Auto-detected via GitHub API |\n| `COPILOT_HOME` | Path to Copilot config directory | `~/.copilot` |\n| `COPILOT_SYNC_REPO` | Name of the sync repository | `.copilot` |\n\n## Architecture\n\n### What Gets Synced\n\n```\n~/.copilot/\n├── session-state/              ← ✅ SYNCED\n│   ├── {session-uuid}/\n│   │   ├── events.jsonl        ← Full conversation events\n│   │   ├── workspace.yaml      ← Session metadata\n│   │   ├── checkpoints/        ← Checkpoint history\n│   │   ├── files/              ← Session artifacts\n│   │   └── plan.md             ← Implementation plans\n│   └── {session-uuid}.jsonl    ← Legacy event logs\n├── session-store.db            ← ✅ SYNCED (row-level merge)\n├── sync-cache/                 ← 🔧 Local clone cache (not synced)\n├── config.json                 ← ❌ NOT synced (machine-specific)\n├── permissions-config.json     ← ❌ NOT synced\n└── logs/                       ← ❌ NOT synced\n```\n\n### Remote Repository Structure\n\nThe private `{username}/.copilot` repo mirrors the synced data:\n\n```\n.copilot (private GitHub repo)\n├── session-state/              ← Same structure as local\n│   ├── {session-uuid}/\n│   └── {session-uuid}.jsonl\n├── session-store.db            ← Merged database\n└── manifest.json               ← Sync metadata (timestamps, machine IDs)\n```\n\n### Sync Mechanics\n\n1. **Clone/pull** the remote `.copilot` repo to `~/.copilot/sync-cache/`\n2. **Discover** sessions on both sides by reading `workspace.yaml` files\n3. **Compare** by session UUID and `updated_at` timestamp\n4. **Copy** session directories (newer side wins)\n5. **Merge** `session-store.db` at the row level (INSERT OR REPLACE)\n6. **Rebuild** FTS5 search index\n7. **Commit and push** changes back to the remote repo\n\n### Security\n\n- The `.copilot` repo is created as **private** — only you can see it\n- Authentication reuses your existing GitHub credentials (`gh` CLI or `GITHUB_TOKEN`)\n- No data is sent to any third-party service — only to your own GitHub repo\n- The sync cache is stored locally at `~/.copilot/sync-cache/`\n\n## Troubleshooting\n\n### \"No GitHub token found\"\nMake sure you're authenticated with the GitHub CLI (`gh auth login`) or have `GITHUB_TOKEN` set in your environment.\n\n### \"Could not determine GitHub username\"\nSet the `GITHUB_USER` environment variable explicitly, or ensure `gh api user` works.\n\n### npx cache issues on Windows\nIf you get stale cache errors, clear the npx cache:\n```powershell\nnpm cache clean --force\nnpx -y copilot-session-sync@latest\n```\n\n### Large session data\nSession data can grow large (especially `events.jsonl` files). The tool syncs everything via git. For very large histories, consider periodically cleaning old sessions you no longer need.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielgerlag%2Fcopilot-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielgerlag%2Fcopilot-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielgerlag%2Fcopilot-sync/lists"}