claude-session-sync 0.1.1__tar.gz

claude_session_sync-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

claude_session_sync-0.1.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

claude_session_sync-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tsubome (Aratech)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_session_sync-0.1.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: claude-session-sync
+Version: 0.1.1
+Summary: Sync Claude Code sessions across Windows, macOS, and Linux
+Project-URL: Homepage, https://github.com/tsubome/claude-session-sync
+Project-URL: Issues, https://github.com/tsubome/claude-session-sync/issues
+Project-URL: Repository, https://github.com/tsubome/claude-session-sync
+Author: tsubome
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+[日本語](docs/README_ja.md) | English
+
+# claude-session-sync
+
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+## What is this?
+
+**claude-session-sync** is a CLI tool that syncs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) session history across Windows, macOS, and Linux.
+
+- Continue any conversation on any machine — pick up exactly where you left off
+- Uses a **private GitHub repository** as the sync backend (no third-party servers)
+- **Automatic path conversion**: OS-specific paths are replaced with portable placeholders (e.g., `/home/user/projects` → `{{PROJECTS}}` → `C:\projects`)
+
+## How it works
+
+```
+Ubuntu                         GitHub                          Mac
+claude-session-sync push  →  Private Repo  →  claude-session-sync pull
+/home/user/projects       →  {{PROJECTS}}  →  /Users/user/projects
+```
+
+Session files (`.jsonl`) are stored under `~/.claude/projects/` by Claude Code. This tool copies them into a private GitHub repository, translating machine-specific paths to shared placeholders on push, and back to local paths on pull.
+
+Memory files stored under `~/.claude/projects/*/memory/` are also synced.
+All machines share a single set of memory files — the last push becomes the source of truth.
+On pull, local memory is completely replaced with the shared version.
+Changes are tracked through git commit history.
+
+## Features
+
+- **Cross-machine session resume** — open any session from any registered machine
+- **Automatic path conversion** with user-defined placeholders
+- **Session locking** — prevents two machines from editing the same session simultaneously
+- **Background daemon** — periodic push backup while Claude Code is running
+- **Selective sync** — only sessions under configured directories are shared
+- **Windows / macOS / Linux** support
+- **Memory & CLAUDE.md sync** — project memory files and global CLAUDE.md are synced across machines automatically during push/pull
+- **Shared memory model** — all machines use the same memory files, git tracks change history
+- **git push retry** — automatic pull-and-retry (up to 3 times) when push is rejected due to concurrent updates
+- **Duplicate daemon prevention** — the resume command checks for existing daemons before starting a new one
+- **Last-editing machine display** — the session list shows which machine last edited each session, not just where it was created
+
+## Quick Start
+
+```bash
+# Install
+pip install claude-session-sync
+```
+
+### Development install
+
+```bash
+# Development install
+git clone https://github.com/tsubome/claude-session-sync.git
+cd claude-session-sync
+pip install -e .
+```
+
+```bash
+# Setup — first machine (creates a new private GitHub repo)
+claude-session-sync init
+
+# Setup — additional machines (connects to the existing repo)
+claude-session-sync init
+
+# Daily usage — `ccsync` is a short alias for `claude-session-sync`
+ccsync resume
+# Pulls the latest sessions, lets you pick one interactively,
+# launches Claude Code, then pushes and releases the lock on exit.
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `resume [SESSION_ID]` | **Main command.** Pull → select session interactively → launch Claude Code → push + release lock on exit. Pass `SESSION_ID` to skip the list. |
+| `resume --latest` | Automatically selects the most recently updated session. |
+| `resume --from MACHINE_ID` | Show only sessions from a specific machine. |
+| `resume --all` | Show all sessions, ignoring `sync_directories` filter. |
+| `init` | Register this machine and create or connect to the shared GitHub repository. |
+| `push [--dry-run]` | Manually push local sessions to the remote repository. |
+| `pull [--dry-run] [--force]` | Manually pull sessions from the remote repository. |
+| `update` | Push sessions and release any locks left behind after an abnormal exit. |
+| `status` | Show the current sync status (last push/pull time, machine ID, etc.). |
+| `list [--remote] [--format table\|json]` | List local (or remote) sessions. |
+| `lock show` | Show all current locks. |
+| `lock release [SESSION_ID]` | Release a lock. Omit `SESSION_ID` to release all locks on this machine. |
+| `lock cleanup` | Delete all expired locks. |
+| `config show` | Show the current configuration. |
+| `config add-placeholder NAME=PATH` | Add a new placeholder mapping for this machine. |
+| `config set-path NAME MACHINE_ID PATH` | Set a path for a specific machine in `shared_placeholders.json`. |
+| `daemon [--interval SECONDS] [--push-only] [--stop]` | Run a background sync daemon (default interval: 300 s / 5 min). |
+
+## Configuration
+
+The local config file is stored at `~/.claude-session-sync/config.json`.
+
+Placeholder mappings shared across all machines are stored in the GitHub repository as `shared_placeholders.json`.
+
+### Example config
+
+```json
+{
+  "machine_id": "ubuntu-work",
+  "github_owner": "your-username",
+  "github_repo": "claude-sessions",
+  "sync_directories": [
+    "/home/your-username/projects"
+  ],
+  "custom_placeholders": {
+    "PROJECTS": "/home/your-username/projects"
+  }
+}
+```
+
+`sync_directories` controls which sessions are visible in `resume`. Only sessions whose working directory falls under one of these paths are shown. Sessions outside them are ignored unless you pass `--all`.
+
+## Custom Placeholders
+
+Placeholders let the same session be opened on machines with different filesystem layouts.
+
+**Adding during init:**
+
+```bash
+claude-session-sync init --add-placeholder PROJECTS=/home/user/projects
+```
+
+**Adding afterwards:**
+
+```bash
+claude-session-sync config add-placeholder PROJECTS=/home/user/projects
+```
+
+**Setting the path for another machine:**
+
+```bash
+claude-session-sync config set-path PROJECTS macbook /Users/user/projects
+claude-session-sync config set-path PROJECTS windows C:\projects
+```
+
+When the same session is pulled on macOS, `{{PROJECTS}}` is automatically expanded to `/Users/user/projects`. On Windows it becomes `C:\projects`.
+
+## Session Locking
+
+When you resume a session, `claude-session-sync` acquires a lock in the shared repository so that no other machine can open the same session at the same time.
+
+| Detail | Value |
+|---|---|
+| Lock TTL | 10 minutes (default) |
+| Heartbeat | Background daemon refreshes the lock while Claude Code is running |
+| Crash recovery | Locks auto-expire after TTL — no manual cleanup needed in most cases |
+| Manual release | `claude-session-sync lock release` |
+
+If a session is locked by another machine, you are shown a warning and asked whether to take over the lock. This is safe if the other machine crashed or was closed without a proper exit.
+
+## Concurrent Operation
+
+Multiple machines can work on **different** sessions simultaneously.
+Each session has its own lock, so editing CrossClip on Linux while editing WhisperApp on Windows is fully supported.
+
+If two machines push at the same time, the tool automatically retries with pull-and-push (up to 3 attempts).
+
+## Troubleshooting
+
+**"Session is locked by another machine"**
+
+The previous Claude Code session likely exited abnormally. You can:
+
+1. Select the locked session → confirm the takeover prompt (`y`)
+2. Or run `claude-session-sync update` on the machine that holds the lock (if still reachable)
+3. Or run `claude-session-sync lock release SESSION_ID` to force-release it
+
+**"No sessions found"**
+
+Run `claude-session-sync pull` first to download sessions from the remote repository, then try `resume` again.
+
+**Windows: daemon does not stop**
+
+The daemon uses a stop-file mechanism on Windows (instead of signals). Run `claude-session-sync daemon --stop` to request a graceful shutdown.
+
+**Sessions from another machine are not visible**
+
+Make sure `sync_directories` on both machines point to the same placeholder (e.g., both mapped to `{{PROJECTS}}`). Run `claude-session-sync config show` to verify, and use `config set-path` to add missing machine entries.
+
+## Requirements
+
+- Python 3.9+
+- Git
+- [GitHub CLI (`gh`)](https://cli.github.com/) — must be authenticated (`gh auth login`)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+## License
+
+MIT

claude_session_sync-0.1.1/README.md

@@ -0,0 +1,196 @@
+[日本語](docs/README_ja.md) | English
+
+# claude-session-sync
+
+![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+## What is this?
+
+**claude-session-sync** is a CLI tool that syncs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) session history across Windows, macOS, and Linux.
+
+- Continue any conversation on any machine — pick up exactly where you left off
+- Uses a **private GitHub repository** as the sync backend (no third-party servers)
+- **Automatic path conversion**: OS-specific paths are replaced with portable placeholders (e.g., `/home/user/projects` → `{{PROJECTS}}` → `C:\projects`)
+
+## How it works
+
+```
+Ubuntu                         GitHub                          Mac
+claude-session-sync push  →  Private Repo  →  claude-session-sync pull
+/home/user/projects       →  {{PROJECTS}}  →  /Users/user/projects
+```
+
+Session files (`.jsonl`) are stored under `~/.claude/projects/` by Claude Code. This tool copies them into a private GitHub repository, translating machine-specific paths to shared placeholders on push, and back to local paths on pull.
+
+Memory files stored under `~/.claude/projects/*/memory/` are also synced.
+All machines share a single set of memory files — the last push becomes the source of truth.
+On pull, local memory is completely replaced with the shared version.
+Changes are tracked through git commit history.
+
+## Features
+
+- **Cross-machine session resume** — open any session from any registered machine
+- **Automatic path conversion** with user-defined placeholders
+- **Session locking** — prevents two machines from editing the same session simultaneously
+- **Background daemon** — periodic push backup while Claude Code is running
+- **Selective sync** — only sessions under configured directories are shared
+- **Windows / macOS / Linux** support
+- **Memory & CLAUDE.md sync** — project memory files and global CLAUDE.md are synced across machines automatically during push/pull
+- **Shared memory model** — all machines use the same memory files, git tracks change history
+- **git push retry** — automatic pull-and-retry (up to 3 times) when push is rejected due to concurrent updates
+- **Duplicate daemon prevention** — the resume command checks for existing daemons before starting a new one
+- **Last-editing machine display** — the session list shows which machine last edited each session, not just where it was created
+
+## Quick Start
+
+```bash
+# Install
+pip install claude-session-sync
+```
+
+### Development install
+
+```bash
+# Development install
+git clone https://github.com/tsubome/claude-session-sync.git
+cd claude-session-sync
+pip install -e .
+```
+
+```bash
+# Setup — first machine (creates a new private GitHub repo)
+claude-session-sync init
+
+# Setup — additional machines (connects to the existing repo)
+claude-session-sync init
+
+# Daily usage — `ccsync` is a short alias for `claude-session-sync`
+ccsync resume
+# Pulls the latest sessions, lets you pick one interactively,
+# launches Claude Code, then pushes and releases the lock on exit.
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `resume [SESSION_ID]` | **Main command.** Pull → select session interactively → launch Claude Code → push + release lock on exit. Pass `SESSION_ID` to skip the list. |
+| `resume --latest` | Automatically selects the most recently updated session. |
+| `resume --from MACHINE_ID` | Show only sessions from a specific machine. |
+| `resume --all` | Show all sessions, ignoring `sync_directories` filter. |
+| `init` | Register this machine and create or connect to the shared GitHub repository. |
+| `push [--dry-run]` | Manually push local sessions to the remote repository. |
+| `pull [--dry-run] [--force]` | Manually pull sessions from the remote repository. |
+| `update` | Push sessions and release any locks left behind after an abnormal exit. |
+| `status` | Show the current sync status (last push/pull time, machine ID, etc.). |
+| `list [--remote] [--format table\|json]` | List local (or remote) sessions. |
+| `lock show` | Show all current locks. |
+| `lock release [SESSION_ID]` | Release a lock. Omit `SESSION_ID` to release all locks on this machine. |
+| `lock cleanup` | Delete all expired locks. |
+| `config show` | Show the current configuration. |
+| `config add-placeholder NAME=PATH` | Add a new placeholder mapping for this machine. |
+| `config set-path NAME MACHINE_ID PATH` | Set a path for a specific machine in `shared_placeholders.json`. |
+| `daemon [--interval SECONDS] [--push-only] [--stop]` | Run a background sync daemon (default interval: 300 s / 5 min). |
+
+## Configuration
+
+The local config file is stored at `~/.claude-session-sync/config.json`.
+
+Placeholder mappings shared across all machines are stored in the GitHub repository as `shared_placeholders.json`.
+
+### Example config
+
+```json
+{
+  "machine_id": "ubuntu-work",
+  "github_owner": "your-username",
+  "github_repo": "claude-sessions",
+  "sync_directories": [
+    "/home/your-username/projects"
+  ],
+  "custom_placeholders": {
+    "PROJECTS": "/home/your-username/projects"
+  }
+}
+```
+
+`sync_directories` controls which sessions are visible in `resume`. Only sessions whose working directory falls under one of these paths are shown. Sessions outside them are ignored unless you pass `--all`.
+
+## Custom Placeholders
+
+Placeholders let the same session be opened on machines with different filesystem layouts.
+
+**Adding during init:**
+
+```bash
+claude-session-sync init --add-placeholder PROJECTS=/home/user/projects
+```
+
+**Adding afterwards:**
+
+```bash
+claude-session-sync config add-placeholder PROJECTS=/home/user/projects
+```
+
+**Setting the path for another machine:**
+
+```bash
+claude-session-sync config set-path PROJECTS macbook /Users/user/projects
+claude-session-sync config set-path PROJECTS windows C:\projects
+```
+
+When the same session is pulled on macOS, `{{PROJECTS}}` is automatically expanded to `/Users/user/projects`. On Windows it becomes `C:\projects`.
+
+## Session Locking
+
+When you resume a session, `claude-session-sync` acquires a lock in the shared repository so that no other machine can open the same session at the same time.
+
+| Detail | Value |
+|---|---|
+| Lock TTL | 10 minutes (default) |
+| Heartbeat | Background daemon refreshes the lock while Claude Code is running |
+| Crash recovery | Locks auto-expire after TTL — no manual cleanup needed in most cases |
+| Manual release | `claude-session-sync lock release` |
+
+If a session is locked by another machine, you are shown a warning and asked whether to take over the lock. This is safe if the other machine crashed or was closed without a proper exit.
+
+## Concurrent Operation
+
+Multiple machines can work on **different** sessions simultaneously.
+Each session has its own lock, so editing CrossClip on Linux while editing WhisperApp on Windows is fully supported.
+
+If two machines push at the same time, the tool automatically retries with pull-and-push (up to 3 attempts).
+
+## Troubleshooting
+
+**"Session is locked by another machine"**
+
+The previous Claude Code session likely exited abnormally. You can:
+
+1. Select the locked session → confirm the takeover prompt (`y`)
+2. Or run `claude-session-sync update` on the machine that holds the lock (if still reachable)
+3. Or run `claude-session-sync lock release SESSION_ID` to force-release it
+
+**"No sessions found"**
+
+Run `claude-session-sync pull` first to download sessions from the remote repository, then try `resume` again.
+
+**Windows: daemon does not stop**
+
+The daemon uses a stop-file mechanism on Windows (instead of signals). Run `claude-session-sync daemon --stop` to request a graceful shutdown.
+
+**Sessions from another machine are not visible**
+
+Make sure `sync_directories` on both machines point to the same placeholder (e.g., both mapped to `{{PROJECTS}}`). Run `claude-session-sync config show` to verify, and use `config set-path` to add missing machine entries.
+
+## Requirements
+
+- Python 3.9+
+- Git
+- [GitHub CLI (`gh`)](https://cli.github.com/) — must be authenticated (`gh auth login`)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+## License
+
+MIT