anthropics · giruuuuj · May 24, 2026 · May 24, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 ## 2.1.150
 
-- Internal infrastructure improvements (no user-facing changes)
+- **New plugin: `desktop-session-sync`** — bridges CLI session transcripts (`~/.claude/projects/**/*.jsonl`) to the Claude desktop app's conversation list via a local metadata bridge. Includes a `/sync-desktop-sessions` command, a PostToolUse hook for auto-sync, and a standalone Python script. See [`plugins/desktop-session-sync/`](/plugins/desktop-session-sync/). Closes #61967
 
 ## 2.1.149
 

diff --git a/examples/features/cli-desktop-conversation-sync.md b/examples/features/cli-desktop-conversation-sync.md
@@ -0,0 +1,105 @@
+# Feature Proposal: CLI-Desktop Conversation Sync
+
+## Summary
+
+Sync Claude Code CLI conversation history with the Claude desktop app so users can browse, search, and review past sessions from either interface. The two products currently use independent storage backends with no sync path.
+
+## Motivation
+
+- Desktop app offers superior browsing UI (search, sidebar, timestamps)
+- CLI offers superior power-user workflow (automation, scripting, pipelines)
+- Users must choose between them — unnecessary tradeoff
+- Competitor precedent: OpenAI Codex CLI syncs with ChatGPT desktop app
+
+## Existing Infrastructure
+
+Claude Code already stores session data in `~/.claude/projects/**/*.jsonl` with a shared schema. The session system has:
+
+- Session ID (UUID per session)
+- Feedback ID (for error reporting)
+- Resume mechanism (`claude --resume`)
+- Stats cache (`~/.claude/stats-cache.json`)
+
+The desktop app stores conversations in its own database (platform-specific).
+
+## Proposed Architecture
+
+### Option A: Account-Based Sync (Recommended)
+
+Both products push/pull conversation metadata via the Claude API, keyed to the user's account.
+
+**CLI side**:
+- After each session turn, push a lightweight metadata record (session_id, model, message_count, timestamp, last_summary) to the API
+- On startup, pull the session index for account-based history browsing
+
+**Desktop side**:
+- Subscribe to the same API endpoint
+- Display CLI sessions alongside desktop sessions in the conversation list
+- Use the existing session ID for deep-link resume (`claude://session/<id>`)
+
+**Advantages**: Works across devices, no local coordination needed, mirrors Codex/ChatGPT pattern.
+
+### Option B: Local Storage Bridge
+
+The CLI writes session metadata to the desktop app's storage directory.
+
+- **macOS**: `~/Library/Application Support/Claude/`
+- **Windows**: `%APPDATA%\Claude\`
+- **Linux**: `~/.config/Claude/`
+
+A shared `.jsonl` index file in the desktop app's directory that both products read/write. The CLI appends new session records; the desktop app reads the index for its conversation list.
+
+**Advantages**: No API changes needed, works offline.
+**Disadvantages**: Single-machine only, race conditions on concurrent writes.
+
+### Option C: Shared Session Format
+
+Both products adopt the same `.jsonl` schema and storage location. The desktop app reads directly from `~/.claude/projects/` and displays CLI sessions natively.
+
+**Advantages**: Minimal changes, leverages existing CLI storage.
+**Disadvantages**: Desktop app would need to parse CLI-specific session files, schema coupling risk.
+
+## Implementation Notes
+
+### Metadata Record Schema
+
+```json
+{
+  "session_id": "uuid",
+  "model": "claude-opus-4-7",
+  "created_at": "2026-05-24T00:00:00Z",
+  "last_activity": "2026-05-24T06:00:00Z",
+  "message_count": 42,
+  "project_dir": "/home/user/project",
+  "summary": "Fixed API rate limiting, added retry logic",
+  "platform": "cli"
+}
+```
+
+### Sync Trigger
+
+- After each assistant turn (real-time, lightweight)
+- On session exit (batch, for history)
+- On explicit `/sync` command (on-demand)
+
+## Working Implementation
+
+A reference implementation is available as a Claude Code plugin at [`plugins/desktop-session-sync/`](/plugins/desktop-session-sync/).
+
+This plugin implements **Option B (Local Storage Bridge)** as a practical, immediately-usable solution:
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| Python sync script | `hooks/sync_sessions.py` | Walks `~/.claude/projects/`, creates `local_<uuid>.json` metadata files in the desktop app's session directory |
+| PostToolUse hook | `hooks/hooks.json` | Auto-syncs after transcript writes during active sessions |
+| Slash command | `commands/sync-desktop-sessions.md` | On-demand full sync via `/sync-desktop-sessions` |
+| Standalone usage | — | Run `python3 sync_sessions.py` independently of the plugin system |
+
+The script derives a deterministic session ID from each transcript's relative path, extracts metadata (title, model, timestamps, message count) from the JSONL content, and writes a `local_<uuid>.json` payload that the desktop app's session list rendering code consumes natively. No modifications to the desktop app are required.
+
+## Related Issues
+
+- #61967 (this feature request)
+- #61742 (Agent View cwd selection — session metadata tracking precedent)
+- #61546 (Agent View cwd — session context features)
+- #56172 (Community bridge script by BasedGPT — inspiration for the plugin approach)
diff --git a/plugins/README.md b/plugins/README.md
@@ -16,6 +16,7 @@ Learn more in the [official plugins documentation](https://docs.claude.com/en/do
 | [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
 | [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |
 | [commit-commands](./commit-commands/) | Git workflow automation for committing, pushing, and creating pull requests | **Commands:** `/commit`, `/commit-push-pr`, `/clean_gone` - Streamlined git operations |
+| [desktop-session-sync](./desktop-session-sync/) | Bridges CLI session history into the Claude desktop app for browsing and resuming from the desktop UI | **Command:** `/sync-desktop-sessions` - Walk CLI transcripts and create desktop metadata<br>**Hook:** PostToolUse - Auto-sync after transcript writes<br>**Script:** `sync_sessions.py` - Standalone Python syncer |
 | [explanatory-output-style](./explanatory-output-style/) | Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style) | **Hook:** SessionStart - Injects educational context at the start of each session |
 | [feature-dev](./feature-dev/) | Comprehensive feature development workflow with a structured 7-phase approach | **Command:** `/feature-dev` - Guided feature development workflow<br>**Agents:** `code-explorer`, `code-architect`, `code-reviewer` - For codebase analysis, architecture design, and quality review |
 | [frontend-design](./frontend-design/) | Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics | **Skill:** `frontend-design` - Auto-invoked for frontend work, providing guidance on bold design choices, typography, animations, and visual details |

diff --git a/plugins/desktop-session-sync/.claude-plugin/plugin.json b/plugins/desktop-session-sync/.claude-plugin/plugin.json
@@ -0,0 +1,9 @@
+{
+  "name": "desktop-session-sync",
+  "version": "1.0.0",
+  "description": "Bridges CLI session history into the Claude desktop app so conversations started in the CLI appear in the desktop app's conversation list",
+  "author": {
+    "name": "giruuuuj",
+    "url": "https://github.com/giruuuuj"
+  }
+}
diff --git a/plugins/desktop-session-sync/README.md b/plugins/desktop-session-sync/README.md
@@ -0,0 +1,99 @@
+# Desktop Session Sync Plugin
+
+Bridges CLI session history into the Claude desktop app so conversations started in the CLI appear in the desktop app's conversation list for browsing, searching, and resuming.
+
+## Problem
+
+The Claude Code CLI and the Claude desktop app use independent storage backends:
+
+- **CLI** stores sessions as `.jsonl` transcripts in `~/.claude/projects/`
+- **Desktop app** maintains its own session list for the Conversations tab
+
+There is no built-in sync path between them.
+
+## Solution
+
+This plugin provides a **local metadata bridge**: it walks the CLI's session transcripts and creates `local_<uuid>.json` metadata files in the desktop app's session directory. The desktop app's existing session list rendering code picks these files up automatically — no modifications to the desktop app are needed.
+
+### How metadata files work
+
+Each `local_<uuid>.json` file contains:
+
+```json
+{
+  "title": "First user message or filename",
+  "model": "claude-opus-4-7",
+  "date": "2026-05-24T06:00:00+00:00",
+  "cliSessionId": "project-name/session-uuid.jsonl",
+  "platform": "cli",
+  "projectDir": "/home/user/.claude/projects/my-project"
+}
+```
+
+The desktop app renders a row in the session list from this metadata and opens the CLI transcript when clicked.
+
+## Features
+
+- **Manual sync** via `/sync-desktop-sessions` slash command
+- **PostToolUse hook** that auto-syncs after transcript writes (when running as a plugin)
+- **Standalone usage** — the Python script can be run independently without the plugin system
+- **Dry-run mode** — preview what would be synced before writing
+- **Cross-platform** — macOS, Windows, and Linux
+
+## Installation
+
+### As a plugin
+
+1. Install the plugin in your project or globally:
+
+```bash
+# In your project directory
+claude /plugin install desktop-session-sync
+
+# Or symlink from the plugins directory
+ln -s /path/to/plugins/desktop-session-sync .claude/plugins/desktop-session-sync
+```
+
+2. The hook will auto-sync after each transcript write. Run `/sync-desktop-sessions` for a full sync.
+
+### Standalone script
+
+```bash
+python3 plugins/desktop-session-sync/hooks/sync_sessions.py
+```
+
+### Run periodically (cron / launch agent)
+
+```bash
+# macOS — run every 10 minutes via launchd
+# Or add to your shell rc file:
+python3 plugins/desktop-session-sync/hooks/sync_sessions.py &
+
+# Linux — add a cron job:
+# */10 * * * * python3 /path/to/plugins/desktop-session-sync/hooks/sync_sessions.py
+```
+
+## Usage
+
+```bash
+# Full sync — walks all CLI transcripts, creates missing desktop metadata
+python3 sync_sessions.py
+
+# Dry-run — preview without writing anything
+python3 sync_sessions.py --dry-run
+
+# Sync only the most recently active session (used by PostToolUse hook)
+python3 sync_sessions.py --sync-current
+```
+
+## Limitations
+
+- **One-directional**: CLI → Desktop only. Changes in the desktop app are not reflected back to the CLI.
+- **Local only**: Syncs only on the current machine. For multi-device sync, the account-based API approach (Option A in the [feature proposal](/examples/features/cli-desktop-conversation-sync.md)) would be needed.
+- **Metadata only**: The full transcript stays in `~/.claude/projects/`; the desktop metadata file is a lightweight pointer.
+
+## Related
+
+- [Feature Proposal: CLI-Desktop Conversation Sync](/examples/features/cli-desktop-conversation-sync.md)
+- Issue [#61967](https://github.com/anthropics/claude-code/issues/61967)
+- Issue [#56172](https://github.com/anthropics/claude-code/issues/56172)
diff --git a/plugins/desktop-session-sync/commands/sync-desktop-sessions.md b/plugins/desktop-session-sync/commands/sync-desktop-sessions.md
@@ -0,0 +1,31 @@
+---
+description: Manually sync all CLI session transcripts to the Claude desktop app session list
+allowed-tools: ["Read", "Bash", "Write"]
+---
+
+# Sync CLI Sessions to Desktop App
+
+Manually syncs CLI conversation history from `~/.claude/projects/` into the Claude desktop app's session list so you can browse and resume CLI sessions from the desktop UI.
+
+## Usage
+
+```
+/sync-desktop-sessions
+```
+
+Run this command to immediately sync all CLI session transcripts to the desktop app. A summary of how many sessions were synced, skipped, or already present will be displayed.
+
+## What it does
+
+1. Walks `~/.claude/projects/` for all `.jsonl` session transcripts
+2. Identifies transcripts without a matching metadata entry in the desktop app's session directory
+3. Creates `local_<uuid>.json` metadata files in the desktop app's session directory
+4. The metadata files reference the original CLI transcript via `cliSessionId`
+
+## Platform paths
+
+| Platform | Desktop session directory |
+|----------|-------------------------|
+| macOS    | `~/Library/Application Support/Claude/claude-code-sessions/` |
+| Windows  | `%APPDATA%\Claude\claude-code-sessions\` |
+| Linux    | `~/.config/Claude/claude-code-sessions/` |
diff --git a/plugins/desktop-session-sync/hooks/hooks.json b/plugins/desktop-session-sync/hooks/hooks.json
@@ -0,0 +1,17 @@
+{
+  "description": "Syncs CLI session transcripts to the Claude desktop app's session list on session end",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/sync_sessions.py\" --sync-current",
+            "timeout": 15
+          }
+        ],
+        "matcher": "*.jsonl"
+      }
+    ]
+  }
+}