multicc-sync 1.0.0__py3-none-any.whl

multicc_sync/__init__.py

@@ -0,0 +1,3 @@
+"""Keep the Claude desktop app's session list the same across two accounts on one machine."""
+
+__version__ = "1.0.0"

multicc_sync/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m multicc_sync``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

multicc_sync/adopt.py

@@ -0,0 +1,127 @@
+"""Give transcripts that only the terminal ``claude`` produced an index entry, so the app lists them.
+
+A transcript with no entry in any account is usually one of three things: an earlier
+segment of a session the app already lists (recorded in ``priorCliSessionIds``), a session
+the user deleted (a tombstone exists), or a session started from the command line, which
+the desktop app never sees. Only the last kind is adopted.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .index import ENTRY_PREFIX, Index
+
+TITLE_CHARS = 60
+
+
+@dataclass
+class Orphan:
+    cli_id: str
+    path: Path
+    cwd: str
+    title: str
+    first_ms: int
+    last_ms: int
+    size: int
+
+
+def known_ids(indexes: list[Index]) -> set[str]:
+    """Every transcript id some entry already covers, current or prior."""
+    ids: set[str] = set()
+    for index in indexes:
+        for entry in index.sessions.values():
+            if entry.get("cliSessionId"):
+                ids.add(entry["cliSessionId"])
+            ids.update(entry.get("priorCliSessionIds") or [])
+        ids.update(index.tombstones)
+    return ids
+
+
+def _scan(path: Path) -> tuple[str, str, int, int] | None:
+    """cwd, first user message, first and last timestamp of a transcript."""
+    cwd = ""
+    title = ""
+    first = last = 0
+    with open(path, encoding="utf-8", errors="ignore") as fh:
+        for line in fh:
+            try:
+                record = json.loads(line)
+            except ValueError:
+                continue
+            stamp = _ms(record.get("timestamp"))
+            if stamp:
+                first = first or stamp
+                last = max(last, stamp)
+            if not cwd and record.get("cwd"):
+                cwd = record["cwd"]
+            if not title and record.get("type") == "user":
+                text = _text(record.get("message"))
+                if text and not text.startswith("<"):
+                    title = text.replace("\n", " ")[:TITLE_CHARS].strip()
+    if not cwd:
+        return None
+    return cwd, title, first, last
+
+
+def _text(message) -> str:
+    if not isinstance(message, dict):
+        return ""
+    content = message.get("content")
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, list):
+        return " ".join(part.get("text", "") for part in content if isinstance(part, dict)).strip()
+    return ""
+
+
+def _ms(stamp) -> int:
+    if not isinstance(stamp, str):
+        return 0
+    from datetime import datetime, timezone
+
+    try:
+        return int(datetime.fromisoformat(stamp.replace("Z", "+00:00")).astimezone(timezone.utc).timestamp() * 1000)
+    except ValueError:
+        return 0
+
+
+def find_orphans(projects: Path, indexes: list[Index], min_bytes: int = 1024) -> list[Orphan]:
+    """Transcripts no account lists, large enough to be worth showing."""
+    known = known_ids(indexes)
+    found: list[Orphan] = []
+    if not projects.is_dir():
+        return found
+    for project in sorted(projects.iterdir()):
+        if not project.is_dir():
+            continue
+        for path in sorted(project.glob("*.jsonl")):
+            cli_id = path.stem
+            if cli_id in known or path.stat().st_size < min_bytes:
+                continue
+            scanned = _scan(path)
+            if scanned is None:
+                continue
+            cwd, title, first, last = scanned
+            found.append(Orphan(cli_id, path, cwd, title or cli_id[:8], first, last or int(path.stat().st_mtime * 1000), path.stat().st_size))
+    found.sort(key=lambda o: o.last_ms, reverse=True)
+    return found
+
+
+def entry_for(orphan: Orphan) -> dict:
+    """A minimal index entry in the shape the app writes for its own sessions."""
+    return {
+        "sessionId": f"{ENTRY_PREFIX}{orphan.cli_id}",
+        "cliSessionId": orphan.cli_id,
+        "cwd": orphan.cwd,
+        "originCwd": orphan.cwd,
+        "createdAt": orphan.first_ms or orphan.last_ms,
+        "lastActivityAt": orphan.last_ms,
+        "lastFocusedAt": orphan.last_ms,
+        "isArchived": False,
+        "title": orphan.title,
+        "titleSource": "user",
+        "previousTitles": [],
+    }

multicc_sync/cli.py

@@ -0,0 +1,247 @@
+"""Command line entry point. ``mccsync`` alone runs a sync; the other commands are explicit."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from . import __version__
+from .adopt import entry_for, find_orphans
+from .index import Index, discover, pick, transcript_path
+from .layout import TESTED_WITH, app_running, check_layout, index_root, projects_root, signed_in_account
+from .merge import ADD, DELETE, SKIP, UPDATE, Plan, apply, plan, snapshot_after
+from .state import backup, list_backups, load_snapshot, restore, save_snapshot
+
+COMMANDS = ("sync", "list", "find", "adopt", "restore", "mcp")
+APP_OPEN = (
+    "the Claude desktop app is running; quit it first (it keeps the session list in memory "
+    "and rewrites the directory on exit), or pass --force"
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argparse parser; ``sync`` is inserted when no command is given."""
+    parser = argparse.ArgumentParser(
+        prog="mccsync",
+        description="Keep the Claude desktop app's session list the same across two accounts on this machine.",
+        epilog=f"Tested with {TESTED_WITH}. Transcripts are never touched; only the app's per-account index is.",
+    )
+    parser.add_argument("--version", action="version", version=f"mccsync {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_sync = sub.add_parser("sync", help="make both accounts list the same sessions (the default)")
+    p_sync.add_argument("-n", "--dry-run", action="store_true", help="show the plan, write nothing")
+    p_sync.add_argument("--accounts", metavar="A,B", help="uuid prefixes of the two accounts (needed when more than two hold sessions)")
+    p_sync.add_argument("--keep-deleted", action="store_true", help="do not carry deletions across; only block re-adding")
+    p_sync.add_argument("--allow-missing", action="store_true", help="copy entries whose transcript is not on this machine")
+    p_sync.add_argument("--force", action="store_true", help="write even while the desktop app is running")
+    p_sync.set_defaults(func=cmd_sync)
+
+    p_list = sub.add_parser("list", help="show every account and its sessions")
+    p_list.set_defaults(func=cmd_list)
+
+    p_find = sub.add_parser("find", help="search session titles and working directories across all accounts")
+    p_find.add_argument("query")
+    p_find.set_defaults(func=cmd_find)
+
+    p_adopt = sub.add_parser("adopt", help="list terminal-only transcripts in the app (experimental)")
+    p_adopt.add_argument("-n", "--dry-run", action="store_true")
+    p_adopt.add_argument("--account", help="uuid prefix of the account to add them to (default: the signed-in one)")
+    p_adopt.add_argument("--min-kb", type=int, default=100, help="ignore transcripts smaller than this; one-shot claude -p runs are tiny (default 100)")
+    p_adopt.add_argument("--force", action="store_true")
+    p_adopt.set_defaults(func=cmd_adopt)
+
+    p_restore = sub.add_parser("restore", help="put back a backup (the latest when none is named)")
+    p_restore.add_argument("backup", nargs="?")
+    p_restore.add_argument("--force", action="store_true")
+    p_restore.set_defaults(func=cmd_restore)
+
+    p_mcp = sub.add_parser("mcp", help="run the MCP server over stdio")
+    p_mcp.set_defaults(func=cmd_mcp)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] not in COMMANDS and argv[0] not in ("-h", "--help", "--version"):
+        argv.insert(0, "sync")
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args) or 0
+    except (LookupError, FileNotFoundError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def load_indexes() -> list[Index]:
+    """All account indexes, after checking the directory still looks as expected."""
+    root = index_root()
+    problems = check_layout(root)
+    if problems:
+        raise RuntimeError("\n  ".join([f"{root} does not look like a session index this tool understands:"] + problems))
+    return discover(root)
+
+
+def choose_pair(indexes: list[Index], spec: str | None) -> tuple[Index, Index]:
+    """The two accounts to sync: named by prefix, or the only two that hold sessions."""
+    if spec:
+        parts = [p.strip() for p in spec.split(",") if p.strip()]
+        if len(parts) != 2:
+            raise LookupError("--accounts takes exactly two uuid prefixes, comma separated")
+        a, b = pick(indexes, parts[0]), pick(indexes, parts[1])
+        if a is b:
+            raise LookupError("both prefixes name the same account")
+        return a, b
+    used = indexes if len(indexes) == 2 else [i for i in indexes if not i.empty]
+    if len(used) != 2:
+        names = ", ".join(i.label for i in used) or "none"
+        raise LookupError(f"{len(used)} accounts hold sessions ({names}); say which two with --accounts A,B")
+    return used[0], used[1]
+
+
+def fmt_time(ms: int | None) -> str:
+    return datetime.fromtimestamp(ms / 1000).strftime("%m-%d %H:%M") if ms else "-" * 11
+
+
+def describe(plan_: Plan, dry_run: bool) -> str:
+    """Human readable plan."""
+    lines: list[str] = []
+    for target in (plan_.a, plan_.b):
+        other = plan_.b if target is plan_.a else plan_.a
+        steps = plan_.for_target(target)
+        verb = "would change" if dry_run else "changing"
+        lines.append(f"{verb} {target.label} (from {other.label}):")
+        for step in steps:
+            flag = " !" if step.conflict else ""
+            lines.append(f"  {step.action:<6} {fmt_time(step.data.get('lastActivityAt') or step.target.sessions.get(step.app_id, {}).get('lastActivityAt'))}  {step.title[:32]:<32} {step.note}{flag}")
+        if not steps:
+            lines.append("  nothing")
+    counts = plan_.counts()
+    lines.append(
+        f"{counts[ADD]} to add, {counts[UPDATE]} to update, {counts[DELETE]} to delete, "
+        f"{plan_.unchanged} already in step, {counts[SKIP]} skipped"
+        + (f", {counts['conflict']} conflicts resolved by recency (!)" if counts["conflict"] else "")
+    )
+    return "\n".join(lines)
+
+
+def make_plan(a: Index, b: Index, keep_deleted: bool, allow_missing: bool) -> Plan:
+    projects = projects_root()
+    return plan(a, b, load_snapshot(a, b), keep_deleted, allow_missing, lambda cli: transcript_path(cli, projects) is not None)
+
+
+def cmd_sync(args) -> int:
+    indexes = load_indexes()
+    a, b = choose_pair(indexes, args.accounts)
+    plan_ = make_plan(a, b, args.keep_deleted, args.allow_missing)
+    print(describe(plan_, args.dry_run))
+    if args.dry_run:
+        print("dry run, nothing written")
+        return 0
+    if not plan_.changes():
+        save_snapshot(a, b, snapshot_after(a, b))
+        print("nothing to do")
+        return 0
+    if app_running() and not args.force:
+        raise RuntimeError(APP_OPEN)
+    dest = backup()
+    written = apply(plan_)
+    saved = save_snapshot(a, b, snapshot_after(a, b))
+    print(f"wrote {written} entries; backup at {dest}; state at {saved}")
+    print("start the Claude app to see the result")
+    return 0
+
+
+def cmd_list(args) -> int:
+    current = signed_in_account()
+    projects = projects_root()
+    for index in load_indexes():
+        mark = "  (signed in)" if index.account == current else ""
+        print(f"account {index.account}  org {index.org}{mark}")
+        rows = sorted(index.sessions.values(), key=lambda e: e.get("lastActivityAt") or 0, reverse=True)
+        for entry in rows:
+            path = transcript_path(entry.get("cliSessionId"), projects)
+            size = f"{path.stat().st_size / 1048576:6.1f}MB" if path else " missing"
+            archived = "  archived" if entry.get("isArchived") else ""
+            print(f"  {fmt_time(entry.get('lastActivityAt'))}  {(entry.get('title') or '(untitled)')[:32]:<32} {(entry.get('cliSessionId') or '')[:8]} {size}{archived}")
+        print(f"  {len(index.sessions)} sessions, {len(index.tombstones)} deleted")
+    return 0
+
+
+def search(indexes: list[Index], query: str) -> list[tuple[Index, str, dict]]:
+    """Entries whose title, cwd or ids contain the query, most recent first."""
+    needle = query.lower()
+    hits = []
+    for index in indexes:
+        for app_id, entry in index.sessions.items():
+            haystack = " ".join(str(entry.get(k) or "") for k in ("title", "cwd", "cliSessionId", "sessionId")).lower()
+            haystack += " " + " ".join(entry.get("previousTitles") or []).lower()
+            if needle in haystack:
+                hits.append((index, app_id, entry))
+    hits.sort(key=lambda h: h[2].get("lastActivityAt") or 0, reverse=True)
+    return hits
+
+
+def cmd_find(args) -> int:
+    projects = projects_root()
+    hits = search(load_indexes(), args.query)
+    for index, app_id, entry in hits:
+        path = transcript_path(entry.get("cliSessionId"), projects)
+        print(f"{fmt_time(entry.get('lastActivityAt'))}  {(entry.get('title') or '(untitled)')[:32]:<32} account {index.label}")
+        print(f"             transcript {path or 'missing'}")
+    if not hits:
+        print("no session matches")
+        return 1
+    return 0
+
+
+def cmd_adopt(args) -> int:
+    indexes = load_indexes()
+    target = pick(indexes, args.account) if args.account else None
+    if target is None:
+        current = signed_in_account()
+        candidates = [i for i in indexes if i.account == current] if current else []
+        if len(candidates) != 1:
+            raise LookupError("cannot tell which account is signed in; pass --account")
+        target = candidates[0]
+    orphans = find_orphans(projects_root(), indexes, args.min_kb * 1024)
+    for orphan in orphans:
+        print(f"  {fmt_time(orphan.last_ms)}  {orphan.title[:32]:<32} {orphan.cli_id[:8]} {orphan.size / 1048576:6.1f}MB  {orphan.cwd}")
+    print(f"{len(orphans)} terminal-only transcripts" + (f" to add to {target.label}" if orphans else ""))
+    if args.dry_run or not orphans:
+        return 0
+    if app_running() and not args.force:
+        raise RuntimeError(APP_OPEN)
+    dest = backup()
+    for orphan in orphans:
+        target.write(f"local_{orphan.cli_id}", entry_for(orphan))
+    print(f"added {len(orphans)} entries; backup at {dest}; start the Claude app to see them")
+    return 0
+
+
+def cmd_restore(args) -> int:
+    if args.backup:
+        source = Path(args.backup)
+    else:
+        backups = list_backups()
+        if not backups:
+            raise FileNotFoundError("no backups yet")
+        source = backups[-1]
+    if app_running() and not args.force:
+        raise RuntimeError(APP_OPEN)
+    root = restore(source)
+    print(f"restored {source} -> {root}")
+    return 0
+
+
+def cmd_mcp(args) -> int:
+    from .mcp import main as mcp_main
+
+    mcp_main()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

multicc_sync/index.py

@@ -0,0 +1,131 @@
+"""One account's session index directory, read into memory and written back entry by entry."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .layout import UUID
+
+ENTRY_PREFIX = "local_"
+TOMBSTONE_PREFIX = "deleted_"
+
+
+def now_ms() -> int:
+    """Milliseconds since the epoch, the unit the app uses."""
+    return int(time.time() * 1000)
+
+
+@dataclass
+class Index:
+    """The entries and tombstones of ``<root>/<account>/<org>``."""
+
+    path: Path
+    sessions: dict[str, dict] = field(default_factory=dict)
+    tombstones: dict[str, int] = field(default_factory=dict)
+    problems: list[str] = field(default_factory=list)
+
+    @classmethod
+    def load(cls, path: Path) -> "Index":
+        """Read every ``local_*.json`` and ``deleted_*`` file in the directory."""
+        index = cls(path=path)
+        for child in sorted(path.iterdir()):
+            name = child.name
+            if name.startswith(ENTRY_PREFIX) and name.endswith(".json"):
+                try:
+                    with open(child, encoding="utf-8") as fh:
+                        index.sessions[name[: -len(".json")]] = json.load(fh)
+                except (OSError, ValueError) as exc:
+                    index.problems.append(f"{child}: {exc}")
+            elif name.startswith(TOMBSTONE_PREFIX):
+                index.tombstones[name[len(TOMBSTONE_PREFIX):]] = _read_stamp(child)
+        return index
+
+    @property
+    def account(self) -> str:
+        return self.path.parent.name
+
+    @property
+    def org(self) -> str:
+        return self.path.name
+
+    @property
+    def label(self) -> str:
+        return self.account[:8]
+
+    @property
+    def empty(self) -> bool:
+        return not self.sessions and not self.tombstones
+
+    def tombstone_for(self, app_id: str) -> int | None:
+        """Deletion time of an entry the user removed here, if any."""
+        return self.tombstones.get(app_id[len(ENTRY_PREFIX):])
+
+    def write(self, app_id: str, data: dict) -> None:
+        """Create or replace an entry, clearing any tombstone that would contradict it."""
+        with open(self.path / f"{app_id}.json", "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False)
+        self.sessions[app_id] = data
+        bare = app_id[len(ENTRY_PREFIX):]
+        if bare in self.tombstones:
+            grave = self.path / f"{TOMBSTONE_PREFIX}{bare}"
+            if grave.exists():
+                os.remove(grave)
+            del self.tombstones[bare]
+
+    def delete(self, app_id: str, stamp: int | None = None) -> None:
+        """Remove an entry and leave the tombstone the app itself would leave."""
+        target = self.path / f"{app_id}.json"
+        if target.exists():
+            os.remove(target)
+        self.sessions.pop(app_id, None)
+        bare = app_id[len(ENTRY_PREFIX):]
+        stamp = stamp or now_ms()
+        with open(self.path / f"{TOMBSTONE_PREFIX}{bare}", "w", encoding="utf-8") as fh:
+            fh.write(str(stamp))
+        self.tombstones[bare] = stamp
+
+
+def _read_stamp(path: Path) -> int:
+    try:
+        return int(path.read_text().strip() or 0)
+    except (OSError, ValueError):
+        return 0
+
+
+def discover(root: Path) -> list[Index]:
+    """Every ``<account>/<org>`` directory under the root, loaded."""
+    found: list[Index] = []
+    if not root.is_dir():
+        return found
+    for account in sorted(root.iterdir()):
+        if not (account.is_dir() and UUID.match(account.name)):
+            continue
+        for org in sorted(account.iterdir()):
+            if org.is_dir() and UUID.match(org.name):
+                found.append(Index.load(org))
+    return found
+
+
+def pick(indexes: list[Index], needle: str) -> Index:
+    """The index whose account or org uuid starts with ``needle``; must be unique."""
+    hits = [i for i in indexes if i.account.startswith(needle) or i.org.startswith(needle)]
+    if not hits:
+        raise LookupError(f"no account matches {needle!r}")
+    if len(hits) > 1:
+        raise LookupError(f"{needle!r} matches {len(hits)} accounts, use a longer prefix")
+    return hits[0]
+
+
+def transcript_path(cli_session_id: str | None, projects: Path) -> Path | None:
+    """Locate a transcript by id without guessing the project directory's name."""
+    if not cli_session_id or not projects.is_dir():
+        return None
+    for project in projects.iterdir():
+        candidate = project / f"{cli_session_id}.jsonl"
+        if candidate.is_file():
+            return candidate
+    return None

multicc_sync/layout.py

@@ -0,0 +1,109 @@
+"""Where the desktop app keeps things, and a check that the layout still looks the way this tool expects.
+
+The app stores conversation transcripts under ``~/.claude/projects`` and, separately, a
+per-account session index::
+
+    <app support>/claude-code-sessions/<accountUuid>/<orgUuid>/local_<appSessionId>.json
+    <app support>/claude-code-sessions/<accountUuid>/<orgUuid>/deleted_<appSessionId>
+
+Transcripts are shared by every account; only the index decides what the sidebar shows.
+None of this is a documented interface, so every path here can be overridden by an
+environment variable and ``check_layout`` refuses to proceed when the directory does not
+look right.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+TESTED_WITH = "Claude desktop 1.49585.0 (runtime 2.1.260) on macOS"
+UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+ENTRY_KEYS = ("sessionId", "cliSessionId", "cwd")
+
+
+def app_support() -> Path:
+    """The desktop app's data directory for this platform."""
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude"
+    if sys.platform == "win32":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "Claude"
+    return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "Claude"
+
+
+def index_root() -> Path:
+    """Directory holding one subdirectory per account (``MCCSYNC_ROOT`` overrides)."""
+    return Path(os.environ.get("MCCSYNC_ROOT") or app_support() / "claude-code-sessions")
+
+
+def projects_root() -> Path:
+    """Where the CLI writes transcripts (``MCCSYNC_PROJECTS`` overrides)."""
+    return Path(os.environ.get("MCCSYNC_PROJECTS") or Path.home() / ".claude" / "projects")
+
+
+def tool_home() -> Path:
+    """This tool's own directory for state and backups (``MCCSYNC_HOME`` overrides)."""
+    return Path(os.environ.get("MCCSYNC_HOME") or Path.home() / ".multicc-sync")
+
+
+def signed_in_account() -> str | None:
+    """The account the app last used, from ``config.json``.
+
+    Only ``lastKnownAccountUuid`` is read; the same file holds OAuth tokens, which this
+    tool never touches or copies.
+    """
+    path = Path(os.environ.get("MCCSYNC_CONFIG") or app_support() / "config.json")
+    try:
+        with open(path, encoding="utf-8") as fh:
+            value = json.load(fh).get("lastKnownAccountUuid")
+    except (OSError, ValueError):
+        return None
+    return value if isinstance(value, str) else None
+
+
+def check_layout(root: Path) -> list[str]:
+    """Reasons the directory does not look like a session index; empty when it does."""
+    if not root.is_dir():
+        return [f"{root} does not exist; is the Claude desktop app installed and signed in?"]
+    accounts = [p for p in root.iterdir() if p.is_dir() and UUID.match(p.name)]
+    if not accounts:
+        return [f"{root} has no account directories named by uuid"]
+    problems: list[str] = []
+    entries = 0
+    for account in accounts:
+        for org in account.iterdir():
+            if not org.is_dir():
+                continue
+            if not UUID.match(org.name):
+                problems.append(f"unexpected directory {org}")
+                continue
+            for path in org.glob("local_*.json"):
+                entries += 1
+                try:
+                    with open(path, encoding="utf-8") as fh:
+                        data = json.load(fh)
+                except (OSError, ValueError) as exc:
+                    problems.append(f"unreadable entry {path}: {exc}")
+                    continue
+                missing = [key for key in ENTRY_KEYS if key not in data]
+                if missing:
+                    problems.append(f"{path.name} lacks {', '.join(missing)}")
+    if entries == 0 and not problems:
+        problems.append(f"{root} holds no session entries at all")
+    return problems
+
+
+def app_running() -> bool:
+    """Whether the desktop app is open; it caches the index in memory and rewrites it on exit."""
+    try:
+        if sys.platform == "win32":
+            out = subprocess.run(["tasklist"], capture_output=True, text=True, check=True).stdout
+            return "claude.exe" in out.lower()
+        out = subprocess.run(["ps", "-Ao", "comm="], capture_output=True, text=True, check=True).stdout
+    except (OSError, subprocess.CalledProcessError):
+        return False
+    return any(line.strip().endswith("/Claude.app/Contents/MacOS/Claude") for line in out.splitlines())

multicc_sync/mcp.py

@@ -0,0 +1,155 @@
+"""MCP server so an agent can find a session in any account and preview or run a sync.
+
+Every tool answers with a ``summary`` line first. Applying a sync needs the desktop app closed,
+which is rarely true while an agent inside that app is asking, so ``sync_sessions`` previews by
+default and says plainly when it cannot write.
+"""
+
+from __future__ import annotations
+
+from .adopt import find_orphans
+from .cli import choose_pair, describe, load_indexes, make_plan, search
+from .index import transcript_path
+from .layout import TESTED_WITH, app_running, projects_root, signed_in_account
+from .merge import apply, snapshot_after
+from .state import backup, save_snapshot
+
+INSTRUCTIONS = (
+    "Session list sync for the Claude desktop app across two accounts on this machine. "
+    "Call find_sessions to locate a past session by title or directory in any account, "
+    "list_accounts to see what each account lists, sync_sessions to preview or apply a sync. "
+    "Writing requires the desktop app to be closed; when it is open, report the plan and tell "
+    "the user to quit the app and run `mccsync` in a terminal. Never touch transcripts. "
+    f"Tested with {TESTED_WITH}."
+)
+
+
+async def list_accounts() -> dict:
+    """Every account index on this machine with its session count, which one is signed in, and whether the app is running."""
+    try:
+        indexes = load_indexes()
+    except RuntimeError as exc:
+        return {"summary": str(exc), "accounts": []}
+    current = signed_in_account()
+    accounts = [
+        {
+            "account": i.account,
+            "org": i.org,
+            "signed_in": i.account == current,
+            "sessions": len(i.sessions),
+            "deleted": len(i.tombstones),
+            "archived": sum(1 for e in i.sessions.values() if e.get("isArchived")),
+        }
+        for i in indexes
+    ]
+    running = app_running()
+    return {
+        "summary": f"{len(accounts)} account indexes, app {'running' if running else 'closed'}",
+        "app_running": running,
+        "accounts": accounts,
+    }
+
+
+async def find_sessions(query: str, limit: int = 10) -> dict:
+    """Find sessions whose title, previous titles, working directory or id contain ``query``, in any account.
+
+    Returns, most recent first, the account, title, cwd, cli session id and the transcript path on disk,
+    so the caller can open the transcript directly even when the session belongs to another account.
+    """
+    try:
+        indexes = load_indexes()
+    except RuntimeError as exc:
+        return {"summary": str(exc), "sessions": []}
+    projects = projects_root()
+    hits = search(indexes, query)[:limit]
+    sessions = []
+    for index, app_id, entry in hits:
+        path = transcript_path(entry.get("cliSessionId"), projects)
+        sessions.append(
+            {
+                "title": entry.get("title"),
+                "account": index.account,
+                "cwd": entry.get("cwd"),
+                "cli_session_id": entry.get("cliSessionId"),
+                "prior_cli_session_ids": entry.get("priorCliSessionIds") or [],
+                "last_activity_ms": entry.get("lastActivityAt"),
+                "archived": bool(entry.get("isArchived")),
+                "transcript": str(path) if path else None,
+            }
+        )
+    return {"summary": f"{len(sessions)} sessions match {query!r}", "sessions": sessions}
+
+
+async def sync_sessions(apply_changes: bool = False, keep_deleted: bool = False, accounts: str | None = None) -> dict:
+    """Preview (default) or apply a sync between the two accounts that hold sessions.
+
+    ``accounts`` names the pair as two uuid prefixes separated by a comma when more than two accounts
+    exist. Applying is refused while the desktop app runs; the plan is returned either way.
+    """
+    try:
+        indexes = load_indexes()
+        a, b = choose_pair(indexes, accounts)
+    except (RuntimeError, LookupError) as exc:
+        return {"summary": str(exc), "applied": False}
+    plan_ = make_plan(a, b, keep_deleted, False)
+    counts = plan_.counts()
+    text = describe(plan_, not apply_changes)
+    result = {"applied": False, "plan": text, "counts": counts, "pair": [a.account, b.account]}
+    if not apply_changes:
+        result["summary"] = f"preview: {counts['add']} add, {counts['update']} update, {counts['delete']} delete"
+        return result
+    if not plan_.changes():
+        save_snapshot(a, b, snapshot_after(a, b))
+        result["summary"] = "nothing to do"
+        return result
+    if app_running():
+        result["summary"] = "not applied: the desktop app is running; ask the user to quit it and run mccsync"
+        return result
+    dest = backup()
+    written = apply(plan_)
+    save_snapshot(a, b, snapshot_after(a, b))
+    result.update(applied=True, written=written, backup=str(dest))
+    result["summary"] = f"applied: {written} entries written, backup at {dest}"
+    return result
+
+
+async def terminal_only_sessions(min_kb: int = 1) -> dict:
+    """Transcripts that only the terminal `claude` created and no account lists; `mccsync adopt` can add them."""
+    try:
+        indexes = load_indexes()
+    except RuntimeError as exc:
+        return {"summary": str(exc), "sessions": []}
+    orphans = find_orphans(projects_root(), indexes, min_kb * 1024)
+    return {
+        "summary": f"{len(orphans)} terminal-only transcripts",
+        "sessions": [
+            {"title": o.title, "cwd": o.cwd, "cli_session_id": o.cli_id, "transcript": str(o.path), "bytes": o.size, "last_activity_ms": o.last_ms}
+            for o in orphans
+        ],
+    }
+
+
+def build_server():
+    """The MCP server with the tools registered; works with mcp 1.x (FastMCP) and 2.x (MCPServer)."""
+    try:
+        try:
+            from mcp.server.mcpserver import MCPServer as Server
+        except ImportError:
+            from mcp.server.fastmcp import FastMCP as Server
+    except ImportError as exc:
+        raise SystemExit("the MCP server needs the 'mcp' package: pip install 'multicc-sync[mcp]'") from exc
+    server = Server("multicc-sync", instructions=INSTRUCTIONS)
+    server.tool()(list_accounts)
+    server.tool()(find_sessions)
+    server.tool()(sync_sessions)
+    server.tool()(terminal_only_sessions)
+    return server
+
+
+def main() -> None:
+    """Run the server over stdio."""
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()

multicc_sync/merge.py

@@ -0,0 +1,200 @@
+"""Three-way merge of two session indexes against the snapshot left by the previous sync.
+
+Without a snapshot the first sync takes the union, and where both sides hold an entry the
+more recently active copy wins. With a snapshot, a side that still matches it did not change,
+so whatever the other side did (renamed, archived, deleted) is carried across. When both
+sides changed the same thing, the more recently active side wins and the step is reported
+as a conflict rather than silently chosen.
+
+Deletion in the app removes the entry and leaves a timestamped tombstone; the transcript
+stays on disk. Propagating a deletion therefore only changes what the sidebar lists.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .index import Index, now_ms
+
+MUTABLE = (
+    "title",
+    "titleSource",
+    "previousTitles",
+    "isArchived",
+    "lastActivityAt",
+    "lastFocusedAt",
+    "completedTurns",
+    "cliSessionId",
+    "priorCliSessionIds",
+)
+ACCOUNT_SCOPED = ("remoteMcpServersConfig", "enabledMcpTools", "bridgeSessionIds")
+
+ADD, UPDATE, DELETE, SKIP = "add", "update", "delete", "skip"
+
+
+@dataclass
+class Step:
+    """One change the sync would make to ``target``."""
+
+    action: str
+    target: Index
+    app_id: str
+    title: str
+    note: str = ""
+    data: dict = field(default_factory=dict)
+    stamp: int | None = None
+    conflict: bool = False
+
+
+@dataclass
+class Plan:
+    """Everything a sync between two indexes would do."""
+
+    a: Index
+    b: Index
+    steps: list[Step] = field(default_factory=list)
+    unchanged: int = 0
+
+    def changes(self) -> list[Step]:
+        return [s for s in self.steps if s.action != SKIP]
+
+    def for_target(self, index: Index) -> list[Step]:
+        return [s for s in self.steps if s.target is index]
+
+    def counts(self) -> dict[str, int]:
+        out = {ADD: 0, UPDATE: 0, DELETE: 0, SKIP: 0, "conflict": 0}
+        for step in self.steps:
+            out[step.action] += 1
+            out["conflict"] += step.conflict
+        return out
+
+
+def fingerprint(entry: dict) -> dict:
+    """The fields the sync tracks, as stored in the snapshot."""
+    return {key: entry[key] for key in MUTABLE if key in entry}
+
+
+def _title(entry: dict | None) -> str:
+    return (entry or {}).get("title") or "(untitled)"
+
+
+def _activity(entry: dict | None) -> int:
+    return int((entry or {}).get("lastActivityAt") or 0)
+
+
+def _resolve(ea: dict, eb: dict, snap: dict | None) -> tuple[dict, bool]:
+    """Merged mutable fields and whether any field was a genuine two-sided conflict."""
+    fa, fb = fingerprint(ea), fingerprint(eb)
+    if fa == fb:
+        return fa, False
+    newer = fa if _activity(ea) >= _activity(eb) else fb
+    if snap is None:
+        return dict(newer), False
+    merged: dict = {}
+    conflict = False
+    for key in MUTABLE:
+        va, vb, vs = fa.get(key), fb.get(key), snap.get(key)
+        if va == vb:
+            value = va
+        elif va == vs:
+            value = vb
+        elif vb == vs:
+            value = va
+        else:
+            value = newer.get(key)
+            conflict = True
+        if value is not None:
+            merged[key] = value
+    return merged, conflict
+
+
+def plan(
+    a: Index,
+    b: Index,
+    snapshot: dict[str, dict],
+    keep_deleted: bool = False,
+    allow_missing: bool = False,
+    has_transcript: Callable[[str | None], bool] = lambda cli: True,
+) -> Plan:
+    """Compute the steps that make ``a`` and ``b`` agree."""
+    result = Plan(a=a, b=b)
+    ids = sorted(set(a.sessions) | set(b.sessions) | set(snapshot))
+    for app_id in ids:
+        ea, eb, snap = a.sessions.get(app_id), b.sessions.get(app_id), snapshot.get(app_id)
+        if ea is not None and eb is not None:
+            _both(result, app_id, ea, eb, snap)
+        elif ea is not None:
+            _one_sided(result, app_id, ea, a, b, snap, keep_deleted, allow_missing, has_transcript)
+        elif eb is not None:
+            _one_sided(result, app_id, eb, b, a, snap, keep_deleted, allow_missing, has_transcript)
+    return result
+
+
+def _both(result: Plan, app_id: str, ea: dict, eb: dict, snap: dict | None) -> None:
+    merged, conflict = _resolve(ea, eb, snap)
+    touched = False
+    for entry, index in ((ea, result.a), (eb, result.b)):
+        if fingerprint(entry) != merged:
+            note = "both sides changed, newer kept" if conflict else "carried across"
+            result.steps.append(Step(UPDATE, index, app_id, merged.get("title") or _title(entry), note, merged, conflict=conflict))
+            touched = True
+    if not touched:
+        result.unchanged += 1
+
+
+def _one_sided(
+    result: Plan,
+    app_id: str,
+    entry: dict,
+    have: Index,
+    lack: Index,
+    snap: dict | None,
+    keep_deleted: bool,
+    allow_missing: bool,
+    has_transcript: Callable[[str | None], bool],
+) -> None:
+    title = _title(entry)
+    stamp = lack.tombstone_for(app_id)
+    if stamp is not None:
+        removed_there = stamp >= _activity(entry)
+    else:
+        removed_there = snap is not None
+    if removed_there:
+        if keep_deleted:
+            result.steps.append(Step(SKIP, have, app_id, title, f"deleted on {lack.label}, kept"))
+        else:
+            result.steps.append(Step(DELETE, have, app_id, title, f"deleted on {lack.label}", stamp=stamp or now_ms()))
+        return
+    if not has_transcript(entry.get("cliSessionId")) and not allow_missing:
+        result.steps.append(Step(SKIP, lack, app_id, title, "no transcript on this machine"))
+        return
+    data = {k: v for k, v in entry.items() if k not in ACCOUNT_SCOPED}
+    result.steps.append(Step(ADD, lack, app_id, title, f"new on {have.label}", data))
+
+
+def apply(plan_: Plan) -> int:
+    """Write every change in the plan; returns how many entries were touched."""
+    written = 0
+    for step in plan_.steps:
+        if step.action == ADD:
+            step.target.write(step.app_id, step.data)
+        elif step.action == UPDATE:
+            current = dict(step.target.sessions[step.app_id])
+            for key in MUTABLE:
+                if key in step.data:
+                    current[key] = step.data[key]
+                else:
+                    current.pop(key, None)
+            step.target.write(step.app_id, current)
+        elif step.action == DELETE:
+            step.target.delete(step.app_id, step.stamp)
+        else:
+            continue
+        written += 1
+    return written
+
+
+def snapshot_after(a: Index, b: Index) -> dict[str, dict]:
+    """The state to remember for next time: every entry both sides now hold."""
+    return {app_id: fingerprint(a.sessions[app_id]) for app_id in a.sessions if app_id in b.sessions}

multicc_sync/state.py

@@ -0,0 +1,77 @@
+"""The snapshot left by the last sync of a pair of accounts, and backups of the whole index."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import time
+from pathlib import Path
+
+from .index import Index
+from .layout import index_root, tool_home
+
+STATE_VERSION = 1
+
+
+def pair_key(a: Index, b: Index) -> str:
+    return "-".join(sorted((a.account[:8], b.account[:8])))
+
+
+def state_path(a: Index, b: Index) -> Path:
+    return tool_home() / f"state-{pair_key(a, b)}.json"
+
+
+def load_snapshot(a: Index, b: Index) -> dict[str, dict]:
+    """Entries as they were after the previous sync of this pair; empty on the first run."""
+    path = state_path(a, b)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return {}
+    if data.get("version") != STATE_VERSION:
+        return {}
+    return data.get("sessions", {})
+
+
+def save_snapshot(a: Index, b: Index, sessions: dict[str, dict]) -> Path:
+    path = state_path(a, b)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump({"version": STATE_VERSION, "synced_at": int(time.time() * 1000), "sessions": sessions}, fh)
+    return path
+
+
+def backups_dir() -> Path:
+    return tool_home() / "backups"
+
+
+def backup(root: Path | None = None) -> Path:
+    """Copy the whole index tree aside before anything is written."""
+    root = root or index_root()
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    dest = backups_dir() / stamp
+    for n in range(1, 1000):
+        if not dest.exists():
+            break
+        dest = backups_dir() / f"{stamp}-{n}"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(root, dest)
+    return dest
+
+
+def list_backups() -> list[Path]:
+    if not backups_dir().is_dir():
+        return []
+    return sorted(p for p in backups_dir().iterdir() if p.is_dir())
+
+
+def restore(source: Path, root: Path | None = None) -> Path:
+    """Replace the index tree with a backup."""
+    root = root or index_root()
+    if not source.is_dir():
+        raise FileNotFoundError(source)
+    if root.exists():
+        shutil.rmtree(root)
+    shutil.copytree(source, root)
+    return root

multicc_sync-1.0.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: multicc-sync
+Version: 1.0.0
+Summary: Keep the Claude desktop app's session list the same across two accounts on one machine
+Project-URL: Homepage, https://github.com/kangkangzi2025/multicc-sync
+Project-URL: Repository, https://github.com/kangkangzi2025/multicc-sync
+Project-URL: Issues, https://github.com/kangkangzi2025/multicc-sync/issues
+Author: Fukang Wen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accounts,claude,claude-code,desktop,sessions,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# multicc-sync
+
+Two Claude accounts on one Mac, one session list. Sign out of the Claude desktop app
+and into another account and every Claude Code session disappears from the sidebar.
+Nothing was deleted: transcripts live in `~/.claude/projects` and are shared, but the
+app keeps a separate list of sessions per account. `mccsync` makes both accounts list
+the same sessions, and keeps them in step afterwards: renames, archives and deletions
+made in one account carry over to the other.
+
+It never touches transcripts, never reads tokens, and makes no network calls. Every
+write is preceded by a backup.
+
+## Install
+
+```bash
+uv tool install multicc-sync
+```
+
+Python 3.11 or newer. For the MCP server as well, install `multicc-sync[mcp]`.
+
+## Use
+
+Quit the Claude app, then:
+
+```bash
+mccsync
+```
+
+That is the whole update. The first run takes the union of both accounts; later runs
+carry across whatever changed on either side since the previous run, and say so
+entry by entry.
+
+```bash
+mccsync -n                  # show the plan, write nothing
+mccsync list                # every account and what it lists
+mccsync find "case study"   # locate a session in any account, with its transcript path
+mccsync adopt               # list terminal-only sessions in the app (experimental)
+mccsync restore             # put back the last backup
+```
+
+`mccsync --help` lists the rest, including `--keep-deleted` and `--accounts A,B` for
+machines with more than two accounts.
+
+For agents, `mccsync-mcp` is a stdio MCP server with four tools: `find_sessions`,
+`list_accounts`, `sync_sessions` and `terminal_only_sessions`. Register it in Claude
+Code with `claude mcp add multicc-sync -- mccsync-mcp`. The repository carries a
+matching skill in `skills/session-sync`.
+
+The app's session index is not a documented interface. This tool was written against
+Claude desktop 1.49585.0 on macOS and checks the directory layout before every run;
+if the app changes it, `mccsync` stops rather than guesses. Windows and Linux paths
+are present but untested.
+
+MIT license.

multicc_sync-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+multicc_sync/__init__.py,sha256=u_eZFFbLN4KK09GgsDAZo8gCcPNO6lRMFnsy4P4uzmY,117
+multicc_sync/__main__.py,sha256=gpkBTmx4wywhhrDVI7qD6nJ_3sNSnvaNk0VMShXQViM,120
+multicc_sync/adopt.py,sha256=i12r9ayqJI6aNbfOBOM3SmcKaAoLKoiFH83OpbNayrk,4177
+multicc_sync/cli.py,sha256=KXsMKXMeht_XSeBSGdZurAf3gMVCfFxbF6dFmQIzDBQ,10850
+multicc_sync/index.py,sha256=kFYNUmDjqV48aBYt_B0_pSP0dDz-Nu446xhx_mpQ0kY,4557
+multicc_sync/layout.py,sha256=9bZSJsNARv5pDvHMoVPe5-tdk7mSphna_TN6nJ20ljA,4542
+multicc_sync/mcp.py,sha256=wuP-ZNj21_4x4pCex8YM-HeU4QN8hgovnjwDrtswWyc,6358
+multicc_sync/merge.py,sha256=7G6Y0cojy09i3cY4c2d3ObVcE3ghLrHO2RUx0xlrTso,6683
+multicc_sync/state.py,sha256=FFMelAhOUP6oysyQYyNkZSEwv0sMByUAX7SV28fM4zc,2222
+multicc_sync-1.0.0.dist-info/METADATA,sha256=7Urzn8pPcOc_cDaxQFztW8LfDbkyFgLLduJ6mKK9gI8,2956
+multicc_sync-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+multicc_sync-1.0.0.dist-info/entry_points.txt,sha256=BZ1M1J9sWRzZXnIcNEPJaWXsQEqAQuKjgidHA_v1_J0,86
+multicc_sync-1.0.0.dist-info/licenses/LICENSE,sha256=lgXSdW18iC8F_rrHev08Aaf1RHBsElY1CJOCgyUWWQ0,1067
+multicc_sync-1.0.0.dist-info/RECORD,,

multicc_sync-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

multicc_sync-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mccsync = multicc_sync.cli:main
+mccsync-mcp = multicc_sync.mcp:main

multicc_sync-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fukang Wen
+
+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.