claude-session-sync-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/CHANGELOG.md

@@ -4,8 +4,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-### Fixed
-- Windows: a running Claude Code CLI (`claude.exe`) was mistaken for the desktop app, blocking `--apply` and `--undo`. Processes are now told apart by install path; unknown ones only trigger a warning.
+## [0.1.1] - 2026-11-11
+
+### Added
+- `--include-recent`: also sync sessions written in the last 2 minutes instead of skipping them. Such sessions are marked in the output, and `--purge-archived` still never touches them.
 
 ## [0.1.0] - 2026-11-11
 
@@ -15,9 +17,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Borrow a template from another account when an account has no sessions yet.
 - `--purge-archived`: permanently delete archived sessions after syncing, moving files to a backup folder first. Respects `--exclude`, `--exclude-file`, and `--project`, and skips sessions whose transcript was written in the last 2 minutes.
 - `--undo`: revert the most recent write or deletion, including restoring backups.
-- Refuse `--apply` and `--undo` while the desktop app is running (macOS, Windows, best effort on Linux) unless `--force` is given.
+- Refuse `--apply` and `--undo` while the desktop app is running unless `--force` is given. On Windows, where the desktop app and the Claude Code CLI are both `claude.exe`, they are told apart by install path and unknown processes only trigger a warning; detection on Linux is best effort.
 - `--version` and `--help` with examples.
 - English and Chinese output, chosen from the locale; override with `CLAUDE_SESSION_SYNC_LANG=en|zh`.
 
-[Unreleased]: https://github.com/xushenjie/claude-session-sync/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/xushenjie/claude-session-sync/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/xushenjie/claude-session-sync/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/xushenjie/claude-session-sync/releases/tag/v0.1.0

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/CONTRIBUTING.md

@@ -40,6 +40,6 @@ The `dev` dependency group in `pyproject.toml` pins the ruff version used by CI.
    git tag vX.Y.Z && git push origin vX.Y.Z
    ```
 
-The `Release` workflow checks that the tag matches `__version__` and that the changelog has an entry, builds the package, publishes it to PyPI, and creates a GitHub Release with the changelog section as notes.
+The `Release` workflow checks that the tag matches `__version__` and that the changelog has an entry, builds the package, publishes it to PyPI, and creates a GitHub Release with the changelog section as notes. It runs without manual approval: pushing the tag is the release decision, so double-check the version before tagging — a version published to PyPI can never be reused.
 
-One-time setup before the first release: on PyPI, add a [Trusted Publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) for the `claude-session-sync-cli` project and this repository with workflow `release.yml` and environment `pypi`, and create an environment named `pypi` under the repository's Settings → Environments.
+One-time setup before the first release: on PyPI, add a [Trusted Publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) for the `claude-session-sync-cli` project and this repository with workflow `release.yml` and environment `pypi`, and create an environment named `pypi` under the repository's Settings → Environments, limited to tags matching `v*` (no required reviewers). If more people get write access later, add required reviewers there or a tag ruleset so only maintainers can create `v*` tags.

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: claude-session-sync-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Sync local Claude Code CLI sessions into the Claude desktop app sidebar (unofficial).
 Project-URL: Homepage, https://github.com/xushenjie/claude-session-sync
 Project-URL: Issues, https://github.com/xushenjie/claude-session-sync/issues
@@ -138,7 +138,7 @@ Output is in English, or in Chinese when your locale (`LC_ALL` / `LC_MESSAGES` /
 | The session is archived in **any** account (`isArchived` field or `archived-sessions.idx`) | Not added to any account. Use `--per-account-archive` to only consider each account's own archive state |
 | The session was deleted in the desktop app in any account (`deleted_<session-id>` marker) | Not added to any account |
 | The session is listed via `--exclude` or `--exclude-file` | Not added |
-| The transcript was written within the last 2 minutes (probably still running) | Skipped |
+| The transcript was written within the last 2 minutes (probably still running) | Skipped; pass `--include-recent` to sync it anyway |
 | Empty sessions (no user message) or transcripts without a working directory | Skipped |
 | `.jsonl` files in subfolders of a project directory (subagents etc.) | Not scanned |
 
@@ -167,7 +167,7 @@ claude-session-sync --purge-archived --apply   # do it
 - Nothing is erased outright: files are moved to `~/.claude-desktop-sync/trash-<timestamp>/`, and `--undo` restores everything;
 - purging always covers **all accounts**, even with `--account`, so no account is left with an index pointing to a removed transcript;
 - `--exclude`, `--exclude-file`, and `--project` apply to purging too — excluded sessions are never deleted;
-- sessions whose `.jsonl` was modified in the last 2 minutes are skipped;
+- sessions whose `.jsonl` was modified in the last 2 minutes are always skipped, even with `--include-recent`;
 - backups are not cleaned up automatically; once you're happy, delete `~/.claude-desktop-sync/trash-*` yourself.
 
 ---
@@ -186,6 +186,7 @@ claude-session-sync --purge-archived --apply   # do it
 | `--project <string>` | Only handle sessions whose working directory contains this string (sync and purge) |
 | `--exclude <session-id>` | Exclude a session from sync and purge; repeatable |
 | `--exclude-file <file>` | Read excluded session IDs from a file, one per line |
+| `--include-recent` | Also sync sessions written in the last 2 minutes (possibly still running). They are marked in the output; purging still skips them |
 | `--per-account-archive` | Only exclude sessions archived in the same account |
 | `--purge-archived` | Permanently delete archived sessions after syncing (see above) |
 | `--projects-dir <path>` | CLI sessions directory; defaults to `~/.claude/projects` and honors `CLAUDE_CONFIG_DIR` |
@@ -219,6 +220,23 @@ Undo only touches files the tool itself changed, never the desktop app's existin
 
 ---
 
+## Upgrade and uninstall
+
+Use the package name `claude-session-sync-cli` (not the command name) with your installer:
+
+| Installed with | Upgrade | Uninstall |
+|---|---|---|
+| uv | `uv tool upgrade claude-session-sync-cli` | `uv tool uninstall claude-session-sync-cli` |
+| pipx | `pipx upgrade claude-session-sync-cli` | `pipx uninstall claude-session-sync-cli` |
+| single file | re-run the `curl` command from [Install](#install) | delete `cli.py` |
+
+Not sure which one you used? `uv tool list` or `pipx list` will show it.
+
+- **Upgrading** replaces the old version in place; the command name stays the same. Running `uv tool install` again does not upgrade — use `upgrade`. Journals and backups in `~/.claude-desktop-sync/` are kept, so `--undo` still works across upgrades. Run `claude-session-sync --version` to confirm.
+- **Uninstalling removes only the program.** Sessions it added to the desktop sidebar and everything in `~/.claude-desktop-sync/` stay. To revert those too, quit the desktop app and run `claude-session-sync --undo` repeatedly *before* uninstalling, until it reports nothing left to undo; then delete `~/.claude-desktop-sync/` if you no longer need the backups.
+
+---
+
 ## Known limitations
 
 - **The index format is inferred from existing files.** Archived state is recognized from `isArchived`, `archived`, `archivedAt`, `status: "archived"`, and `archived-sessions.idx`; deletions from `deleted_<session-id>` markers. If a desktop update changes the format, `is_archived()` or `load_markers()` need updating.

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/README.md

@@ -109,7 +109,7 @@ Output is in English, or in Chinese when your locale (`LC_ALL` / `LC_MESSAGES` /
 | The session is archived in **any** account (`isArchived` field or `archived-sessions.idx`) | Not added to any account. Use `--per-account-archive` to only consider each account's own archive state |
 | The session was deleted in the desktop app in any account (`deleted_<session-id>` marker) | Not added to any account |
 | The session is listed via `--exclude` or `--exclude-file` | Not added |
-| The transcript was written within the last 2 minutes (probably still running) | Skipped |
+| The transcript was written within the last 2 minutes (probably still running) | Skipped; pass `--include-recent` to sync it anyway |
 | Empty sessions (no user message) or transcripts without a working directory | Skipped |
 | `.jsonl` files in subfolders of a project directory (subagents etc.) | Not scanned |
 
@@ -138,7 +138,7 @@ claude-session-sync --purge-archived --apply   # do it
 - Nothing is erased outright: files are moved to `~/.claude-desktop-sync/trash-<timestamp>/`, and `--undo` restores everything;
 - purging always covers **all accounts**, even with `--account`, so no account is left with an index pointing to a removed transcript;
 - `--exclude`, `--exclude-file`, and `--project` apply to purging too — excluded sessions are never deleted;
-- sessions whose `.jsonl` was modified in the last 2 minutes are skipped;
+- sessions whose `.jsonl` was modified in the last 2 minutes are always skipped, even with `--include-recent`;
 - backups are not cleaned up automatically; once you're happy, delete `~/.claude-desktop-sync/trash-*` yourself.
 
 ---
@@ -157,6 +157,7 @@ claude-session-sync --purge-archived --apply   # do it
 | `--project <string>` | Only handle sessions whose working directory contains this string (sync and purge) |
 | `--exclude <session-id>` | Exclude a session from sync and purge; repeatable |
 | `--exclude-file <file>` | Read excluded session IDs from a file, one per line |
+| `--include-recent` | Also sync sessions written in the last 2 minutes (possibly still running). They are marked in the output; purging still skips them |
 | `--per-account-archive` | Only exclude sessions archived in the same account |
 | `--purge-archived` | Permanently delete archived sessions after syncing (see above) |
 | `--projects-dir <path>` | CLI sessions directory; defaults to `~/.claude/projects` and honors `CLAUDE_CONFIG_DIR` |
@@ -190,6 +191,23 @@ Undo only touches files the tool itself changed, never the desktop app's existin
 
 ---
 
+## Upgrade and uninstall
+
+Use the package name `claude-session-sync-cli` (not the command name) with your installer:
+
+| Installed with | Upgrade | Uninstall |
+|---|---|---|
+| uv | `uv tool upgrade claude-session-sync-cli` | `uv tool uninstall claude-session-sync-cli` |
+| pipx | `pipx upgrade claude-session-sync-cli` | `pipx uninstall claude-session-sync-cli` |
+| single file | re-run the `curl` command from [Install](#install) | delete `cli.py` |
+
+Not sure which one you used? `uv tool list` or `pipx list` will show it.
+
+- **Upgrading** replaces the old version in place; the command name stays the same. Running `uv tool install` again does not upgrade — use `upgrade`. Journals and backups in `~/.claude-desktop-sync/` are kept, so `--undo` still works across upgrades. Run `claude-session-sync --version` to confirm.
+- **Uninstalling removes only the program.** Sessions it added to the desktop sidebar and everything in `~/.claude-desktop-sync/` stay. To revert those too, quit the desktop app and run `claude-session-sync --undo` repeatedly *before* uninstalling, until it reports nothing left to undo; then delete `~/.claude-desktop-sync/` if you no longer need the backups.
+
+---
+
 ## Known limitations
 
 - **The index format is inferred from existing files.** Archived state is recognized from `isArchived`, `archived`, `archivedAt`, `status: "archived"`, and `archived-sessions.idx`; deletions from `deleted_<session-id>` markers. If a desktop update changes the format, `is_archived()` or `load_markers()` need updating.

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/README.zh-CN.md

@@ -109,7 +109,7 @@ claude-session-sync --undo
 | 会话在**任意一个账号**里被归档过（`isArchived` 字段或 `archived-sessions.idx`） | 所有账号都不补。加 `--per-account-archive` 改为只看当前账号 |
 | 会话在任意账号里被桌面端删除过（存在 `deleted_<会话ID>` 标记） | 所有账号都不补 |
 | 会话在 `--exclude` 或 `--exclude-file` 里 | 不补 |
-| 最近 2 分钟内还在写入的会话（可能正在运行） | 跳过 |
+| 最近 2 分钟内还在写入的会话（可能正在运行） | 跳过；加 `--include-recent` 可以照样同步 |
 | 空会话（没有用户消息）、找不到工作目录的记录 | 跳过 |
 | 项目目录下子文件夹里的 `.jsonl`（子代理等） | 不扫描 |
 
@@ -138,7 +138,7 @@ claude-session-sync --purge-archived --apply   # 执行
 - 被删的文件不会直接抹掉，而是移到 `~/.claude-desktop-sync/trash-<时间>/`，`--undo` 可以全部还原；
 - 不管有没有加 `--account`，清除都会覆盖**全部账号**，避免别的账号留下指向已删文件的索引；
 - `--exclude`、`--exclude-file` 和 `--project` 对清除同样生效，排除的会话不会被删；
-- 最近 2 分钟内还在写入的会话会跳过（按 `.jsonl` 的修改时间判断）；
+- 最近 2 分钟内还在写入的会话一定会跳过（按 `.jsonl` 的修改时间判断），加了 `--include-recent` 也一样；
 - 备份目录不会自动清理，确认没问题后可以手动删除 `~/.claude-desktop-sync/trash-*`。
 
 ---
@@ -157,6 +157,7 @@ claude-session-sync --purge-archived --apply   # 执行
 | `--project <字符串>` | 只处理工作目录里包含这个字符串的会话（同步和清除都生效） |
 | `--exclude <会话ID>` | 排除某个会话，同步和清除都跳过，可以写多次 |
 | `--exclude-file <文件>` | 从文件读取排除列表，每行一个会话 ID |
+| `--include-recent` | 同步时不跳过最近 2 分钟内仍在写入的会话（可能正在运行），输出里会单独标出；清除时仍然跳过 |
 | `--per-account-archive` | 只按当前账号的归档状态来排除 |
 | `--purge-archived` | 同步后彻底删除已归档会话（见上一节） |
 | `--projects-dir <路径>` | CLI 会话目录，默认 `~/.claude/projects`，也会读取 `CLAUDE_CONFIG_DIR` |
@@ -190,6 +191,23 @@ claude-session-sync --exclude-file ~/no-sync.txt --apply
 
 ---
 
+## 升级与卸载
+
+用安装时的工具，配合**包名** `claude-session-sync-cli`（不是命令名）：
+
+| 安装方式 | 升级 | 卸载 |
+|---|---|---|
+| uv | `uv tool upgrade claude-session-sync-cli` | `uv tool uninstall claude-session-sync-cli` |
+| pipx | `pipx upgrade claude-session-sync-cli` | `pipx uninstall claude-session-sync-cli` |
+| 单文件 | 重新运行[安装](#安装)一节里的 `curl` 命令 | 删除 `cli.py` |
+
+不记得用哪种方式装的，运行 `uv tool list` 或 `pipx list` 看一下。
+
+- **升级**会直接替换旧版本，命令名不变。再运行一次 `uv tool install` 不会升级，要用 `upgrade`。`~/.claude-desktop-sync/` 里的日志和备份会保留，升级后 `--undo` 依然可以撤销以前的操作。升级完可以用 `claude-session-sync --version` 确认版本。
+- **卸载只删除程序本身。** 已经同步到桌面端侧边栏的会话和 `~/.claude-desktop-sync/` 都会保留。想一并撤销，请在**卸载前**退出桌面端，反复运行 `claude-session-sync --undo`，直到提示没有可撤销的记录；不再需要备份的话，再手动删除 `~/.claude-desktop-sync/`。
+
+---
+
 ## 已知限制
 
 - **索引格式是根据现有文件推测的**：归档会识别 `isArchived`、`archived`、`archivedAt`、`status: "archived"` 和 `archived-sessions.idx`；删除会识别 `deleted_<会话ID>` 标记。桌面端更新后如果格式变了，需要修改 `is_archived()` 或 `load_markers()`。

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/src/claude_session_sync/cli.py

@@ -40,7 +40,7 @@ import time
 import uuid
 from pathlib import Path, PurePosixPath, PureWindowsPath
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 HOME = Path.home()
 JOURNAL_DIR = HOME / ".claude-desktop-sync"
@@ -668,6 +668,15 @@ Notes:
         "--exclude-file",
         help=t("file with session IDs to exclude, one per line", "排除列表文件，每行一个会话ID"),
     )
+    ap.add_argument(
+        "--include-recent",
+        action="store_true",
+        help=t(
+            "also sync sessions written in the last 2 minutes (possibly still running); "
+            "--purge-archived still skips them",
+            "同步时不跳过最近 2 分钟内仍在写入的会话（可能正在运行）；--purge-archived 仍然会跳过",
+        ),
+    )
     ap.add_argument(
         "--per-account-archive",
         action="store_true",
@@ -792,7 +801,9 @@ Notes:
     if args.project:
         sessions = [s for s in sessions if args.project in s["cwd"]]
     now = time.time()
-    running = {s["id"] for s in sessions if now - s["mtime"] < RUNNING_GRACE_SEC}
+    recent = {s["id"] for s in sessions if now - s["mtime"] < RUNNING_GRACE_SEC}
+    skip_recent = set() if args.include_recent else recent
+    included_recent = set()
 
     print(
         t(
@@ -819,7 +830,7 @@ Notes:
         todo = [
             s
             for s in sessions
-            if s["id"] not in known and s["id"] not in arch and s["id"] not in excluded and s["id"] not in running
+            if s["id"] not in known and s["id"] not in arch and s["id"] not in excluded and s["id"] not in skip_recent
         ]
         print(
             t(
@@ -847,7 +858,11 @@ Notes:
             continue
         for s in sorted(todo, key=lambda x: -x["lastActivityAt"]):
             when = time.strftime("%Y-%m-%d %H:%M", time.localtime(s["lastActivityAt"] / 1000))
-            print(f"  + {when}  {s['title']}  ({s['cwd']})")
+            mark = ""
+            if s["id"] in recent:
+                included_recent.add(s["id"])
+                mark = t("  [still being written]", "  （最近仍在写入）")
+            print(f"  + {when}  {s['title']}  ({s['cwd']}){mark}")
             if args.apply:
                 new_id, entry = build_entry(template, s)
                 out = d / f"{new_id}.json"
@@ -855,11 +870,23 @@ Notes:
                     json.dump(entry, fh, ensure_ascii=False, indent=2)
                 created.append(out)
 
-    if running:
+    if skip_recent:
+        print(
+            t(
+                f"\nSkipped {len(skip_recent)} session(s) written in the last 2 minutes (probably still running). "
+                "Pass --include-recent to sync them anyway.",
+                f"\n跳过 {len(skip_recent)} 个最近 2 分钟内仍在写入的会话（可能正在运行）。"
+                "如需一并同步，加 --include-recent。",
+            )
+        )
+    if included_recent:
         print(
             t(
-                f"\nSkipped {len(running)} session(s) written in the last 2 minutes (probably still running).",
-                f"\n跳过 {len(running)} 个最近 2 分钟内仍在写入的会话（可能正在运行）。",
+                f"\n! Included {len(included_recent)} session(s) still being written. Their title and last-activity "
+                "time may be out of date, and don't type into the same session from the CLI and the desktop app "
+                "at the same time.",
+                f"\n! 包含了 {len(included_recent)} 个最近仍在写入的会话。它们的标题和最后活动时间可能不是最新的，"
+                "也不要在 CLI 和桌面端同时向同一个会话输入。",
             )
         )
 

{claude_session_sync_cli-0.1.0 → claude_session_sync_cli-0.1.1}/tests/test_sync.py

@@ -375,3 +375,39 @@ def test_windows_desktop_detection(paths, expected):
 def test_windows_unknown_process_warns_but_does_not_block(capsys):
     assert cli.windows_desktop_running(["", r"D:\tools\claude.exe"]) is False
     assert "may or may not be the desktop app" in capsys.readouterr().err
+
+
+# ---------------------------------------------------------------- --include-recent
+
+
+def test_recent_session_skipped_with_hint(env, capsys):
+    import time
+
+    env.add_index("existing")
+    env.add_cli_session("busy", mtime=time.time())
+    env.run("--apply")
+    assert cli_ids(env.index_entries()) == ["existing"]
+    assert "--include-recent" in capsys.readouterr().out
+
+
+def test_include_recent_syncs_and_warns(env, capsys):
+    import time
+
+    env.add_index("existing")
+    env.add_cli_session("busy", mtime=time.time())
+    env.add_cli_session("old")
+    env.run("--apply", "--include-recent")
+    assert cli_ids(env.index_entries()) == ["busy", "existing", "old"]
+    out = capsys.readouterr().out
+    assert out.count("[still being written]") == 1  # 只标注最近写入的那个
+    assert "Included 1 session(s) still being written" in out
+    assert "Skipped" not in out
+
+
+def test_include_recent_does_not_affect_purge(env):
+    import time
+
+    arch = env.add_index("busy", archived=True)
+    jsonl = env.add_cli_session("busy", mtime=time.time())
+    env.run("--purge-archived", "--apply", "--include-recent")
+    assert arch.exists() and jsonl.exists()