session-compass 0.1.0__py3-none-any.whl

session_compass/__init__.py

@@ -0,0 +1,3 @@
+"""session-compass: list and resume Claude Code, Codex, Antigravity, and Copilot CLI sessions."""
+
+__version__ = "0.1.0"

session_compass/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Service-specific coding agent integrations."""
+
+from .registry import get_adapter, get_adapters
+
+__all__ = ["get_adapter", "get_adapters"]

session_compass/agents/antigravity.py

@@ -0,0 +1,173 @@
+"""Antigravity session discovery and resume integration."""
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .base import (
+    AgentAdapter,
+    AgentCompatibility,
+    ContractReport,
+    classify_resumability,
+    file_mtime,
+    parse_timestamp,
+    read_jsonl_lines,
+)
+
+
+HOME = Path.home()
+AGY_DIR = HOME / ".gemini" / "antigravity-cli"
+AGY_CONVERSATIONS_DIR = AGY_DIR / "conversations"
+AGY_HISTORY_FILE = AGY_DIR / "history.jsonl"
+AGY_METADATA_FILE = AGY_DIR / "cache" / "conversation_metadata.json"
+AGY_SUMMARIES_DB = AGY_DIR / "conversation_summaries.db"
+
+
+def count_steps(db_file: Path) -> int:
+    try:
+        connection = sqlite3.connect(f"file:{db_file}?mode=ro", uri=True)
+        try:
+            row = connection.execute("SELECT count(*) FROM steps").fetchone()
+        finally:
+            connection.close()
+        return int(row[0]) if row else 0
+    except sqlite3.Error:
+        return 0
+
+
+def read_summary_catalog(path: Path) -> dict[str, dict[str, Any]]:
+    """Read Antigravity's user-facing conversation catalog without writing to it."""
+    try:
+        connection = sqlite3.connect(f"file:{path.resolve()}?mode=ro", uri=True)
+        try:
+            rows = connection.execute(
+                """
+                SELECT conversation_id, title, preview, workspace_uris, last_modified_time
+                FROM conversation_summaries
+                """
+            ).fetchall()
+        finally:
+            connection.close()
+    except (OSError, sqlite3.Error):
+        return {}
+
+    catalog: dict[str, dict[str, Any]] = {}
+    for conversation_id, title, preview, workspace_uris, last_modified_time in rows:
+        try:
+            parsed_workspaces = json.loads(workspace_uris or "[]")
+        except (TypeError, json.JSONDecodeError):
+            parsed_workspaces = []
+        if not isinstance(parsed_workspaces, list):
+            parsed_workspaces = []
+        catalog[str(conversation_id)] = {
+            "title": str(title or "").strip(),
+            "preview": str(preview or "").strip(),
+            "workspace_uris": [str(value) for value in parsed_workspaces if value],
+            "last_modified_time": last_modified_time,
+        }
+    return catalog
+
+
+def read_conversation_metadata(path: Path) -> dict[str, dict[str, Any]]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, TypeError):
+        return {}
+    conversations = data.get("conversations", {}) if isinstance(data, dict) else {}
+    return conversations if isinstance(conversations, dict) else {}
+
+
+class AntigravityAdapter:
+    name = "agy"
+    executable = "agy"
+    required_help_flags = ("--conversation", "--dangerously-skip-permissions")
+
+    def check_storage_contract(self, path: Path) -> ContractReport:
+        try:
+            connection = sqlite3.connect(f"file:{path.resolve()}?mode=ro", uri=True)
+            try:
+                rows = connection.execute("PRAGMA table_info(steps)").fetchall()
+            finally:
+                connection.close()
+        except (OSError, sqlite3.Error):
+            return ContractReport(self.name, False, ("steps",))
+        if not rows:
+            return ContractReport(self.name, False, ("steps",))
+        columns = {row[1] for row in rows}
+        missing = ("steps.idx",) if "idx" not in columns else ()
+        return ContractReport(self.name, not missing, missing)
+
+    def collect_sessions(self) -> list[dict[str, Any]]:
+        sessions = []
+        if not AGY_CONVERSATIONS_DIR.is_dir():
+            return sessions
+
+        from_history: dict[str, dict[str, Any]] = {}
+        for entry in read_jsonl_lines(AGY_HISTORY_FILE):
+            conversation_id = entry.get("conversationId")
+            if not conversation_id:
+                continue
+            record = from_history.setdefault(str(conversation_id), {})
+            if entry.get("workspace"):
+                record["workspace"] = entry["workspace"]
+            if entry.get("type") != "slash_command" and str(entry.get("display", "")).strip():
+                record["summary"] = entry["display"]
+            timestamp = entry.get("timestamp")
+            if timestamp and (not record.get("last_active") or timestamp > record["last_active"]):
+                record["last_active"] = timestamp
+
+        metadata = read_conversation_metadata(AGY_METADATA_FILE)
+        catalog = read_summary_catalog(AGY_SUMMARIES_DB)
+
+        for db_file in AGY_CONVERSATIONS_DIR.glob("*.db"):
+            if count_steps(db_file) == 0:
+                continue
+            session_id = db_file.stem
+            catalog_record = catalog.get(session_id)
+            if not catalog_record or metadata.get(session_id, {}).get("is_internal") is True:
+                continue
+            history = from_history.get(session_id, {})
+            workspace_uris = catalog_record["workspace_uris"]
+            cwd = (
+                workspace_uris[0].removeprefix("file://") if workspace_uris else None
+            ) or history.get("workspace")
+            last_active = (
+                parse_timestamp(
+                    history.get("last_active") or catalog_record.get("last_modified_time")
+                )
+                or file_mtime(db_file)
+            )
+            summary = catalog_record["title"] or catalog_record["preview"]
+            if not summary or not cwd:
+                continue
+            session = {
+                "tool": self.name,
+                "id": session_id,
+                "cwd": cwd,
+                "summary": summary,
+                "last_active": last_active,
+                "record_kind": "conversation",
+                "has_conversation_content": True,
+                "summary_source": "catalog_title" if catalog_record["title"] else "catalog_preview",
+                "workspace_source": "catalog_workspace_uri" if workspace_uris else "history_workspace",
+            }
+            session["resume_status"] = classify_resumability(session).value
+            sessions.append(session)
+        return sessions
+
+    def build_resume_command(self, session_id: str, dangerous: bool = False) -> list[str]:
+        command = ["agy"]
+        if dangerous:
+            command.append("--dangerously-skip-permissions")
+        return command + ["--conversation", session_id]
+
+    def compatibility(self) -> AgentCompatibility:
+        return AgentCompatibility(self.name, "1.1.27", "1.1.27", "1.1.27")
+
+
+ADAPTER: AgentAdapter = AntigravityAdapter()
+
+
+def collect_sessions() -> list[dict[str, Any]]:
+    return ADAPTER.collect_sessions()

session_compass/agents/base.py

@@ -0,0 +1,141 @@
+"""Shared types and helpers for service-specific session adapters."""
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any, Optional, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class AgentCompatibility:
+    agent: str
+    resume_min_version: str
+    storage_min_version: str
+    tested_latest_version: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ProbeResult:
+    command: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+@dataclass(frozen=True)
+class CapabilityReport:
+    agent: str
+    version: Optional[str]
+    resume: bool
+    dangerous_resume: bool
+    detected_flags: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ContractReport:
+    agent: str
+    ok: bool
+    missing: tuple[str, ...] = ()
+    warnings: tuple[str, ...] = ()
+
+
+class ResumeStatus(Enum):
+    RESUMABLE = "resumable"
+    LIKELY_RESUMABLE = "likely_resumable"
+    METADATA_ONLY = "metadata_only"
+    INVALID = "invalid"
+
+
+@runtime_checkable
+class AgentAdapter(Protocol):
+    name: str
+    executable: str
+    required_help_flags: tuple[str, str]
+
+    def collect_sessions(self) -> list[dict[str, Any]]:
+        ...
+
+    def build_resume_command(self, session_id: str, dangerous: bool = False) -> list[str]:
+        ...
+
+    def compatibility(self) -> AgentCompatibility:
+        ...
+
+    def check_storage_contract(self, path: Path) -> ContractReport:
+        ...
+
+
+def classify_resumability(session: dict[str, Any]) -> ResumeStatus:
+    """Classify resume evidence without treating a summary as resume evidence."""
+    if session.get("record_kind") in {"bridge_session", "metadata_only"}:
+        return ResumeStatus.METADATA_ONLY
+    if session.get("has_conversation_content") is False:
+        return ResumeStatus.METADATA_ONLY
+    if session.get("has_rollout") is False:
+        return ResumeStatus.INVALID
+    if any(
+        session.get(field) is True
+        for field in ("has_conversation_content", "has_rollout", "has_session_record")
+    ):
+        return ResumeStatus.RESUMABLE
+    if session.get("record_kind") == "conversation":
+        return ResumeStatus.LIKELY_RESUMABLE
+    return ResumeStatus.INVALID
+
+
+def filter_resume_candidates(
+    sessions: list[dict[str, Any]], include_unverified: bool = False
+) -> list[dict[str, Any]]:
+    """Return verified candidates by default, retaining original record objects."""
+    if include_unverified:
+        return list(sessions)
+    return [
+        session
+        for session in sessions
+        if classify_resumability(session)
+        in {ResumeStatus.RESUMABLE, ResumeStatus.LIKELY_RESUMABLE}
+    ]
+
+
+def validate_help_contract(help_text: str, required_flags: tuple[str, ...]) -> bool:
+    """Return whether all required capability markers are present in help text."""
+    return all(flag in help_text for flag in required_flags)
+
+
+def read_jsonl_lines(file: Path) -> list[dict[str, Any]]:
+    """Return valid JSON object records from a JSON Lines file."""
+    try:
+        raw = file.read_text(encoding="utf-8")
+    except OSError:
+        return []
+
+    records = []
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(record, dict):
+            records.append(record)
+    return records
+
+
+def parse_timestamp(value: Any) -> Optional[datetime]:
+    if not value:
+        return None
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value / 1000, tz=timezone.utc)
+    try:
+        text = str(value).replace("Z", "+00:00")
+        date = datetime.fromisoformat(text)
+        return date.replace(tzinfo=timezone.utc) if date.tzinfo is None else date
+    except (TypeError, ValueError):
+        return None
+
+
+def file_mtime(file: Path) -> datetime:
+    return datetime.fromtimestamp(file.stat().st_mtime, tz=timezone.utc)

session_compass/agents/claude.py

@@ -0,0 +1,113 @@
+"""Claude Code session discovery and resume integration."""
+
+from pathlib import Path
+from typing import Any
+
+from .base import (
+    AgentAdapter,
+    AgentCompatibility,
+    ContractReport,
+    classify_resumability,
+    file_mtime,
+    parse_timestamp,
+    read_jsonl_lines,
+)
+
+
+HOME = Path.home()
+CLAUDE_PROJECTS_DIR = HOME / ".claude" / "projects"
+
+
+def message_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content.strip()
+    if not isinstance(content, list):
+        return ""
+    parts = []
+    for item in content:
+        if isinstance(item, dict) and isinstance(item.get("text"), str):
+            parts.append(item["text"])
+    return " ".join(part.strip() for part in parts if part.strip()).strip()
+
+
+class ClaudeAdapter:
+    name = "claude"
+    executable = "claude"
+    required_help_flags = ("--resume", "--dangerously-skip-permissions")
+
+    def check_storage_contract(self, path: Path) -> ContractReport:
+        records = read_jsonl_lines(path)
+        if not records:
+            return ContractReport(self.name, False, ("jsonl",))
+        missing = () if all("type" in record for record in records) else ("type",)
+        return ContractReport(self.name, not missing, missing)
+
+    def collect_sessions(self) -> list[dict[str, Any]]:
+        sessions = []
+        if not CLAUDE_PROJECTS_DIR.is_dir():
+            return sessions
+
+        for project_dir in CLAUDE_PROJECTS_DIR.iterdir():
+            if not project_dir.is_dir():
+                continue
+            for file in project_dir.glob("*.jsonl"):
+                lines = read_jsonl_lines(file)
+                if not lines:
+                    continue
+
+                cwd = summary = None
+                user_summary = None
+                last_timestamp = None
+                has_conversation_content = False
+                has_bridge_record = False
+                for entry in lines:
+                    has_bridge_record = has_bridge_record or entry.get("type") == "bridge-session"
+                    cwd = cwd or entry.get("cwd")
+                    message = entry.get("message") or {}
+                    content = message.get("content") if isinstance(message, dict) else None
+                    text = message_text(content)
+                    if entry.get("type") in {"user", "assistant"} and text:
+                        has_conversation_content = True
+                    if not user_summary and entry.get("type") == "user" and text:
+                        user_summary = text
+                    if entry.get("type") == "summary" and isinstance(entry.get("summary"), str):
+                        summary = entry["summary"].strip() or summary
+                    last_timestamp = entry.get("timestamp") or last_timestamp
+
+                summary = summary or user_summary
+
+                fallback_cwd = "/" + project_dir.name.lstrip("-").replace("-", "/")
+                session = {
+                        "tool": self.name,
+                        "id": file.stem,
+                        "cwd": cwd or fallback_cwd,
+                        "summary": summary or "(no summary available)",
+                        "last_active": parse_timestamp(last_timestamp) or file_mtime(file),
+                        "record_kind": (
+                            "conversation"
+                            if has_conversation_content
+                            else "bridge_session"
+                            if has_bridge_record
+                            else "metadata_only"
+                        ),
+                        "has_conversation_content": has_conversation_content,
+                    }
+                session["resume_status"] = classify_resumability(session).value
+                sessions.append(session)
+        return sessions
+
+    def build_resume_command(self, session_id: str, dangerous: bool = False) -> list[str]:
+        command = ["claude"]
+        if dangerous:
+            command.append("--dangerously-skip-permissions")
+        return command + ["--resume", session_id]
+
+    def compatibility(self) -> AgentCompatibility:
+        return AgentCompatibility(self.name, "2.1.263", "2.1.263", "2.1.263")
+
+
+ADAPTER: AgentAdapter = ClaudeAdapter()
+
+
+def collect_sessions() -> list[dict[str, Any]]:
+    return ADAPTER.collect_sessions()

session_compass/agents/codex.py

@@ -0,0 +1,152 @@
+"""Codex session discovery and resume integration."""
+
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from .base import (
+    AgentAdapter,
+    AgentCompatibility,
+    ContractReport,
+    classify_resumability,
+    parse_timestamp,
+    read_jsonl_lines,
+)
+
+
+HOME = Path.home()
+CODEX_SESSIONS_DIR = HOME / ".codex" / "sessions"
+CODEX_INDEX_FILE = HOME / ".codex" / "session_index.jsonl"
+
+
+def find_codex_rollout_file(session_id: str) -> Optional[Path]:
+    if not CODEX_SESSIONS_DIR.is_dir():
+        return None
+    for path in CODEX_SESSIONS_DIR.rglob("*"):
+        if path.is_file() and session_id in path.name:
+            return path
+    return None
+
+
+def find_codex_state_db() -> Optional[Path]:
+    state_dbs = list((HOME / ".codex").glob("state_*.sqlite"))
+    return max(state_dbs, key=lambda path: path.stat().st_mtime, default=None)
+
+
+class CodexAdapter:
+    name = "codex"
+    executable = "codex"
+    required_help_flags = ("resume", "--dangerously-bypass-approvals-and-sandbox")
+
+    def check_storage_contract(self, path: Path) -> ContractReport:
+        required = {
+            "id",
+            "cwd",
+            "title",
+            "first_user_message",
+            "preview",
+            "updated_at_ms",
+            "updated_at",
+            "archived",
+        }
+        try:
+            connection = sqlite3.connect(f"file:{path.resolve()}?mode=ro", uri=True)
+            try:
+                rows = connection.execute("PRAGMA table_info(threads)").fetchall()
+            finally:
+                connection.close()
+        except (OSError, sqlite3.Error):
+            return ContractReport(self.name, False, ("threads",))
+        if not rows:
+            return ContractReport(self.name, False, ("threads",))
+        columns = {row[1] for row in rows}
+        missing = tuple(f"threads.{column}" for column in sorted(required - columns))
+        return ContractReport(self.name, not missing, missing)
+
+    def collect_state_sessions(self) -> list[dict[str, Any]]:
+        state_db = find_codex_state_db()
+        if not state_db:
+            return []
+
+        try:
+            connection = sqlite3.connect(f"{state_db.resolve().as_uri()}?mode=ro", uri=True)
+            try:
+                rows = connection.execute(
+                    """
+                    SELECT id, cwd, title, first_user_message, preview, updated_at_ms, updated_at
+                    FROM threads
+                    WHERE archived = 0 AND preview <> ''
+                    """
+                ).fetchall()
+            finally:
+                connection.close()
+        except (OSError, sqlite3.Error):
+            return []
+
+        sessions = []
+        for session_id, cwd, title, first_message, preview, updated_at_ms, updated_at in rows:
+            session = {
+                "tool": self.name,
+                "id": str(session_id),
+                "cwd": cwd or "(unknown)",
+                "summary": title or first_message or preview or "(no summary available)",
+                "last_active": parse_timestamp(updated_at_ms)
+                or parse_timestamp(updated_at)
+                or datetime.fromtimestamp(0, tz=timezone.utc),
+                "record_kind": "conversation",
+                "has_rollout": find_codex_rollout_file(str(session_id)) is not None,
+            }
+            session["resume_status"] = classify_resumability(session).value
+            sessions.append(session)
+        return sessions
+
+    def collect_sessions(self) -> list[dict[str, Any]]:
+        sessions = self.collect_state_sessions()
+        known_ids = {session["id"] for session in sessions}
+
+        for entry in read_jsonl_lines(CODEX_INDEX_FILE):
+            session_id = entry.get("id")
+            if not session_id or str(session_id) in known_ids:
+                continue
+            cwd = None
+            rollout_file = find_codex_rollout_file(str(session_id))
+            if rollout_file:
+                meta_line = next(
+                    (line for line in read_jsonl_lines(rollout_file) if line.get("type") == "session_meta"),
+                    None,
+                )
+                payload = meta_line.get("payload", {}) if meta_line else {}
+                if isinstance(payload, dict):
+                    cwd = payload.get("cwd")
+
+            sessions.append(
+                {
+                    "tool": self.name,
+                    "id": str(session_id),
+                    "cwd": cwd or "(unknown)",
+                    "summary": entry.get("thread_name") or "(no summary available)",
+                    "last_active": parse_timestamp(entry.get("updated_at"))
+                    or datetime.fromtimestamp(0, tz=timezone.utc),
+                    "record_kind": "conversation",
+                    "has_rollout": rollout_file is not None,
+                }
+            )
+            sessions[-1]["resume_status"] = classify_resumability(sessions[-1]).value
+        return sessions
+
+    def build_resume_command(self, session_id: str, dangerous: bool = False) -> list[str]:
+        command = ["codex"]
+        if dangerous:
+            command.append("--dangerously-bypass-approvals-and-sandbox")
+        return command + ["resume", session_id]
+
+    def compatibility(self) -> AgentCompatibility:
+        return AgentCompatibility(self.name, "0.153.4", "0.153.4", "0.153.4")
+
+
+ADAPTER: AgentAdapter = CodexAdapter()
+
+
+def collect_sessions() -> list[dict[str, Any]]:
+    return ADAPTER.collect_sessions()

session_compass/agents/copilot.py

@@ -0,0 +1,97 @@
+"""Copilot session discovery and resume integration."""
+
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .base import AgentAdapter, AgentCompatibility, ContractReport, classify_resumability, parse_timestamp
+
+
+HOME = Path.home()
+COPILOT_DB_FILE = HOME / ".copilot" / "session-store.db"
+
+
+class CopilotAdapter:
+    name = "copilot"
+    executable = "copilot"
+    required_help_flags = ("--resume", "--allow-all")
+
+    def check_storage_contract(self, path: Path) -> ContractReport:
+        required = {
+            "sessions": {"id", "cwd", "summary", "updated_at"},
+            "turns": {"session_id", "user_message", "turn_index"},
+        }
+        try:
+            connection = sqlite3.connect(f"file:{path.resolve()}?mode=ro", uri=True)
+            try:
+                missing = []
+                for table, columns in required.items():
+                    rows = connection.execute(f"PRAGMA table_info({table})").fetchall()
+                    if not rows:
+                        missing.append(table)
+                        continue
+                    available = {row[1] for row in rows}
+                    missing.extend(f"{table}.{column}" for column in sorted(columns - available))
+            finally:
+                connection.close()
+        except (OSError, sqlite3.Error):
+            return ContractReport(self.name, False, ("sessions", "turns"))
+        missing_tuple = tuple(missing)
+        return ContractReport(self.name, not missing_tuple, missing_tuple)
+
+    def collect_sessions(self) -> list[dict[str, Any]]:
+        if not COPILOT_DB_FILE.is_file():
+            return []
+
+        try:
+            connection = sqlite3.connect(f"file:{COPILOT_DB_FILE}?mode=ro", uri=True)
+            try:
+                sessions_rows = connection.execute(
+                    "SELECT id, cwd, summary, updated_at FROM sessions"
+                ).fetchall()
+                first_messages = dict(
+                    connection.execute(
+                        """
+                        SELECT session_id, user_message FROM turns
+                        WHERE turn_index = 0
+                        """
+                    ).fetchall()
+                )
+            finally:
+                connection.close()
+        except (OSError, sqlite3.Error):
+            return []
+
+        sessions = []
+        for session_id, cwd, summary, updated_at in sessions_rows:
+            first_message = first_messages.get(session_id)
+            session = {
+                    "tool": self.name,
+                    "id": str(session_id),
+                    "cwd": cwd or "(unknown)",
+                    "summary": first_message or summary or "(no summary available)",
+                    "last_active": parse_timestamp(updated_at)
+                    or datetime.fromtimestamp(0, tz=timezone.utc),
+                    "record_kind": "conversation",
+                    "has_session_record": True,
+                }
+            session["resume_status"] = classify_resumability(session).value
+            sessions.append(session)
+        return sessions
+
+    def build_resume_command(self, session_id: str, dangerous: bool = False) -> list[str]:
+        command = ["copilot"]
+        if dangerous:
+            command.append("--allow-all")
+        return command + [f"--resume={session_id}"]
+
+    def compatibility(self) -> AgentCompatibility:
+        return AgentCompatibility(self.name, "1.0.82", "1.0.82", "1.0.82")
+
+
+ADAPTER: AgentAdapter = CopilotAdapter()
+
+
+def collect_sessions() -> list[dict[str, Any]]:
+    return ADAPTER.collect_sessions()

session_compass/agents/registry.py

@@ -0,0 +1,26 @@
+"""Registry of supported service adapters."""
+
+from .antigravity import ADAPTER as ANTIGRAVITY_ADAPTER
+from .base import AgentAdapter
+from .claude import ADAPTER as CLAUDE_ADAPTER
+from .codex import ADAPTER as CODEX_ADAPTER
+from .copilot import ADAPTER as COPILOT_ADAPTER
+
+
+_ADAPTERS = {
+    adapter.name: adapter
+    for adapter in (
+        CLAUDE_ADAPTER,
+        CODEX_ADAPTER,
+        ANTIGRAVITY_ADAPTER,
+        COPILOT_ADAPTER,
+    )
+}
+
+
+def get_adapters() -> list[AgentAdapter]:
+    return list(_ADAPTERS.values())
+
+
+def get_adapter(name: str) -> AgentAdapter:
+    return _ADAPTERS[name]

session_compass/cli.py

@@ -0,0 +1,139 @@
+"""List and resume Claude Code, Codex, Antigravity, and Copilot CLI sessions."""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .agents.base import ResumeStatus, classify_resumability, filter_resume_candidates
+from .agents.registry import get_adapter, get_adapters
+
+
+HOME = Path.home()
+
+
+def truncate(value: Any, length: int) -> str:
+    if not value:
+        return ""
+    clean = re.sub(r"\s+", " ", str(value)).strip()
+    return clean[: length - 1] + "…" if len(clean) > length else clean
+
+
+def format_relative_time(date: datetime) -> str:
+    diff_minutes = round((datetime.now(timezone.utc) - date).total_seconds() / 60)
+    if diff_minutes < 1:
+        return "just now"
+    if diff_minutes < 60:
+        return f"{diff_minutes}m ago"
+    diff_hours = round(diff_minutes / 60)
+    if diff_hours < 24:
+        return f"{diff_hours}h ago"
+    diff_days = round(diff_hours / 24)
+    return f"{diff_days}d ago" if diff_days < 30 else date.date().isoformat()
+
+
+def shorten_home(path: str) -> str:
+    home = str(HOME)
+    return "~" + path[len(home) :] if path.startswith(home) else path
+
+
+def collect_claude_sessions() -> list[dict[str, Any]]:
+    return get_adapter("claude").collect_sessions()
+
+
+def collect_codex_sessions() -> list[dict[str, Any]]:
+    return get_adapter("codex").collect_sessions()
+
+
+def collect_antigravity_sessions() -> list[dict[str, Any]]:
+    return get_adapter("agy").collect_sessions()
+
+
+def collect_copilot_sessions() -> list[dict[str, Any]]:
+    return get_adapter("copilot").collect_sessions()
+
+
+def resume_session(session: dict[str, Any], dangerous: bool = False) -> None:
+    cwd = session["cwd"] if Path(session["cwd"]).exists() else os.getcwd()
+    adapter = get_adapter(session["tool"])
+    command_args = adapter.build_resume_command(session["id"], dangerous=dangerous)
+    print(f"\n> cd {shorten_home(cwd)} && {' '.join(command_args)}\n")
+    if not shutil.which(command_args[0]):
+        print(f"Command not found: {command_args[0]}", file=sys.stderr)
+        return
+    subprocess.run(command_args, cwd=cwd, check=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    filters = parser.add_mutually_exclusive_group()
+    filters.add_argument("--claude", action="store_const", const="claude", dest="tool")
+    filters.add_argument("--codex", action="store_const", const="codex", dest="tool")
+    filters.add_argument("--agy", action="store_const", const="agy", dest="tool")
+    filters.add_argument("--copilot", action="store_const", const="copilot", dest="tool")
+    parser.add_argument(
+        "--include-unverified",
+        action="store_true",
+        help="Include sessions without verified resume evidence",
+    )
+    parser.add_argument(
+        "-d",
+        "--dangerously-skip-permissions",
+        action="store_true",
+        help="Use each agent's native permission-bypass option when resuming",
+    )
+    args = parser.parse_args()
+
+    sessions = [session for adapter in get_adapters() for session in adapter.collect_sessions()]
+    if args.tool:
+        sessions = [session for session in sessions if session["tool"] == args.tool]
+    visible_sessions = filter_resume_candidates(sessions, include_unverified=args.include_unverified)
+    hidden_count = len(sessions) - len(visible_sessions)
+    sessions = visible_sessions
+    if hidden_count and not args.include_unverified:
+        print(f"{hidden_count} unverified sessions hidden. Use --include-unverified to inspect them.")
+    sessions.sort(key=lambda session: session["last_active"])
+    if not sessions:
+        print("No sessions found.")
+        return
+
+    index_width = len(str(len(sessions)))
+    print()
+    for index, session in enumerate(sessions, start=1):
+        project = truncate(shorten_home(session["cwd"]), 32)
+        print(
+            f"{index:>{index_width}}) [{session['tool']:<7}] {format_relative_time(session['last_active']):<9} "
+            f"{project:<32} {truncate(session['summary'], 70)}"
+        )
+        if args.include_unverified:
+            status = classify_resumability(session)
+            if status not in {ResumeStatus.RESUMABLE, ResumeStatus.LIKELY_RESUMABLE}:
+                print(f"{' ' * (index_width + 2)}status: {status.value}")
+        print(f"{' ' * (index_width + 2)}id: {session['id']}")
+    print()
+
+    answer = input("Resume which session? (number, or q to quit): ").strip().lower()
+    if not answer or answer == "q":
+        return
+    try:
+        choice = int(answer)
+    except ValueError:
+        choice = 0
+    if not 1 <= choice <= len(sessions):
+        print("Invalid selection.")
+        return
+    selected = sessions[choice - 1]
+    status = classify_resumability(selected)
+    if status not in {ResumeStatus.RESUMABLE, ResumeStatus.LIKELY_RESUMABLE}:
+        print(f"Session is not resumable ({status.value}).")
+        return
+    resume_session(selected, dangerous=args.dangerously_skip_permissions)
+
+
+if __name__ == "__main__":
+    main()

session_compass-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: session-compass
+Version: 0.1.0
+Summary: Discover and resume local sessions from Claude Code, Codex, Antigravity, and Copilot CLI
+Author-email: Yeonchan Ahn <ahnyeonchan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: antigravity,claude-code,cli,codex,coding-agents,copilot,resume,sessions
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Session Compass
+
+[![PyPI](https://img.shields.io/pypi/v/session-compass)](https://pypi.org/project/session-compass/)
+
+Session Compass is a local-first CLI for discovering, identifying, and resuming sessions created by Claude Code, Codex, Antigravity CLI, and Copilot CLI.
+
+This project started as a fork of [cli-sessions](https://github.com/pavbyte/cli-sessions). It keeps the upstream project's practical local-session workflow while adding provider-specific metadata, resumability checks, and compatibility monitoring for independently updated agent CLIs.
+
+## Why Session Compass?
+
+Coding agents store useful session data locally, but each agent exposes that history differently. Session Compass gives you one starting point for answering:
+
+- Which agent created this session?
+- Which workspace was it using?
+- What was the session about?
+- When was it last active?
+- Can it be resumed safely?
+
+It is designed for local development machines and remote Linux servers accessed through SSH. It does not require a daemon, a central database, an account, or a web service.
+
+## Install
+
+Using `pipx` is recommended for command-line tools because it keeps Session Compass isolated from other Python applications:
+
+```bash
+pipx install session-compass
+```
+
+You can also install it with `pip`:
+
+```bash
+pip install session-compass
+```
+
+The repository includes an optional installer for machines where `pipx` is not already configured:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ycahn82/session-compass/main/install.sh | bash
+```
+
+## Usage
+
+```bash
+scompass             # List sessions from all supported agents
+scompass --claude    # Show Claude Code sessions
+scompass --codex     # Show Codex sessions
+scompass --agy       # Show Antigravity sessions
+scompass --copilot   # Show Copilot CLI sessions
+```
+
+Choose a session number to resume it in its original working directory. Press `q` to exit without resuming.
+
+Use `--include-unverified` when diagnosing records that do not have enough local evidence to be considered resumable:
+
+```bash
+scompass --include-unverified
+```
+
+### Permission bypass
+
+Use `-d` as the short alias for `--dangerously-skip-permissions` when resuming a session:
+
+```bash
+scompass -d
+scompass --claude -d
+```
+
+Session Compass translates this shared option to each provider's native permission-bypass option. This can reduce or remove safety prompts from the provider, so use it only in environments where you understand the consequences.
+
+## Supported agents
+
+Session Compass currently reads local session metadata from these locations:
+
+```text
+Claude Code:  ~/.claude/projects/*/*.jsonl
+Codex:        ~/.codex/state_*.sqlite or ~/.codex/session_index.jsonl
+Antigravity:  ~/.gemini/antigravity-cli/conversations/*.db and history.jsonl
+Copilot CLI:  ~/.copilot/session-store.db
+```
+
+An agent that is not installed is skipped. Session databases are opened for metadata discovery only; Session Compass does not migrate, rewrite, or delete them.
+
+The default list focuses on sessions with evidence that they can be resumed. Internal and metadata-only records are hidden from that list. Use `--include-unverified` to inspect diagnostic records without making them normal resume candidates.
+
+## Local-first and privacy
+
+Session Compass reads files already written on your machine. It does not send session content anywhere and does not include telemetry. The current implementation does not use an LLM to generate summaries; it prefers deterministic titles, previews, and user-message metadata already present in local storage.
+
+## Compatibility policy
+
+Agent CLIs can update independently, including their resume arguments and local storage schemas. Each Session Compass provider adapter owns its storage contract, metadata extraction, resumability evidence, and native resume command.
+
+The project maintains separate compatibility floors for the provider CLI's resume command and its session-storage schema. GitHub Actions checks supported provider versions and help contracts weekly and on pull requests. When an upstream change breaks a contract, maintainers review the report and update the affected adapter; normal runtime execution does not probe provider help on every invocation.
+
+## Current capabilities
+
+- Unified session listing across supported coding agents
+- Provider and workspace metadata
+- Deterministic title and summary extraction from local records
+- Resumability filtering for internal, incomplete, or metadata-only records
+- Native resume command mapping per provider
+- Shared `-d`/`--dangerously-skip-permissions` option
+- Read-only compatibility and storage-contract tests
+
+## Roadmap
+
+The master plan is intentionally incremental. Planned work includes:
+
+- Richer text search across agent, project, workspace, title, and branch metadata
+- A stable machine-readable JSON output mode
+- A read-only `doctor` diagnostic command
+- Optional aggregation of session metadata from explicitly selected remote hosts
+- Better provenance for workspace and Git context
+
+These roadmap items are not required for the current interactive listing and resume workflow.
+
+## Fork maintenance
+
+The upstream project is [pavbyte/cli-sessions](https://github.com/pavbyte/cli-sessions). Session Compass keeps the upstream remote separate and documents intentional differences in the repository's development plans.
+
+The public package and command are intentionally separate from the upstream project:
+
+```text
+Upstream cli-sessions:  pip install cli-sessions   -> sessions
+Session Compass:        pip install session-compass -> scompass
+```
+
+Session Compass does not provide a `sessions` alias. This prevents a new installation from replacing or shadowing an existing upstream `cli-sessions` command.
+
+## Links
+
+- Source: https://github.com/ycahn82/session-compass
+- Upstream: https://github.com/pavbyte/cli-sessions
+- PyPI: https://pypi.org/project/session-compass/
+
+## License
+
+MIT

session_compass-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+session_compass/__init__.py,sha256=85TZbuHBf2KCnIVdzkaxceAcZvV-6zwcTeOb2kysANM,121
+session_compass/cli.py,sha256=LDOUtdEsKsTbqT445REG16mSqnXOC19mKfv8uWcBxMU,5093
+session_compass/agents/__init__.py,sha256=9CSLCsWhbt-RdbSIzfSgIkjUZCnV870VxsVn__zRJMs,142
+session_compass/agents/antigravity.py,sha256=BMGEJHiaxl1laSLb9p74B2wtIKtj_FVvZnwSTvXdxA0,6584
+session_compass/agents/base.py,sha256=NA_lAYmv9dXbWIcpVuVSDlKUaAReB8cmLL99UHOd4ds,3997
+session_compass/agents/claude.py,sha256=RKSsXH3e-4Zq7ztrd_uJ7ik8p-h89t7VSza_U7VkvAU,4291
+session_compass/agents/codex.py,sha256=PcM2D27WUvTY8EJtbz-H4xjuB9QzZ7hSLgCrTuLN_K8,5507
+session_compass/agents/copilot.py,sha256=r8yA_fnalmDHp-yU3sA91U1uz4d1ziaNUb5XNpC8G_Y,3619
+session_compass/agents/registry.py,sha256=SB25joZBUR-QjoYoBnBDPZeG5R379FfNv2QWN-zEP1s,597
+session_compass-0.1.0.dist-info/METADATA,sha256=RgYkkgnElVGXRnGA7vnffAyL7QlHUFc_Zmsyr_IRgmY,6512
+session_compass-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+session_compass-0.1.0.dist-info/entry_points.txt,sha256=29oe_TPIHxSjTCHr6gqgntnR7g9g-n15fxNFfLLwkYY,54
+session_compass-0.1.0.dist-info/licenses/LICENSE,sha256=Piexuh-nEfK7-gu8JzbN_DVuNDQPHHjNmFS2_zyEOzo,1066
+session_compass-0.1.0.dist-info/RECORD,,

session_compass-0.1.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

session_compass-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scompass = session_compass.cli:main

session_compass-0.1.0.dist-info/licenses/LICENSE

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