session-compass 0.1.0__tar.gz

session_compass-0.1.0/.github/scripts/update_compatibility_issue.js

@@ -0,0 +1,106 @@
+"use strict";
+
+const UUID_RE = /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\b/g;
+const SECRET_RE = /\b(?:sk|ghp|github_pat)[_-][A-Za-z0-9_-]+\b/g;
+const PATH_RE = /(?<!\w)(?:\/Users|\/home|\/tmp|[A-Z]:\\)[^\s,;]+/g;
+
+function sanitizeText(value) {
+  return String(value)
+    .replace(PATH_RE, "<path>")
+    .replace(UUID_RE, "<uuid>")
+    .replace(SECRET_RE, "<secret>")
+    .slice(0, 200);
+}
+
+function issueTitle(agent, problemType) {
+  return `[compat] ${agent} ${problemType}`;
+}
+
+function issueLabels(agent) {
+  return ["compatibility", "automated-detection", `agent:${agent}`];
+}
+
+function problemType(result) {
+  if (result.failure === "executable_not_found" || result.failure === "execution_error") {
+    return "CLI installation failure";
+  }
+  if (Array.isArray(result.missing_flags) && result.missing_flags.length > 0) {
+    return "resume capability mismatch";
+  }
+  if (result.failure && String(result.failure).includes("storage")) {
+    return "storage contract mismatch";
+  }
+  return "CLI compatibility failure";
+}
+
+function failureBody(result, artifactUrl, runUrl) {
+  const safe = {
+    agent: result.agent,
+    version: result.version || "unknown",
+    status: result.status,
+    failure: result.failure ? sanitizeText(result.failure) : undefined,
+    detected_flags: result.detected_flags || [],
+    missing_flags: result.missing_flags || [],
+  };
+  return [
+    "## CLI compatibility failure",
+    "",
+    "```json",
+    JSON.stringify(safe, null, 2),
+    "```",
+    "",
+    `Artifact: ${artifactUrl}`,
+    `Workflow run: ${runUrl}`,
+  ].join("\n");
+}
+
+function recoveryComment(agent, runUrl) {
+  return `Compatibility check recovered for ${agent}. The issue remains open for maintainer review. Workflow run: ${runUrl}`;
+}
+
+async function updateCompatibilityIssues({ github, context, results, artifactUrl, runUrl }) {
+  const repo = { owner: context.repo.owner, repo: context.repo.repo };
+  for (const result of results) {
+    if (result.status === "pass") {
+      const open = await github.rest.search.issuesAndPullRequests({
+        q: `repo:${repo.owner}/${repo.repo} is:issue is:open [compat] ${result.agent}`,
+      });
+      for (const issue of open.data.items.filter((item) => item.title.startsWith(`[compat] ${result.agent} `))) {
+        await github.rest.issues.createComment({
+          ...repo,
+          issue_number: issue.number,
+          body: recoveryComment(result.agent, runUrl),
+        });
+      }
+      continue;
+    }
+
+    const title = issueTitle(result.agent, problemType(result));
+    const all = await github.rest.search.issuesAndPullRequests({
+      q: `repo:${repo.owner}/${repo.repo} is:issue "${title}"`,
+    });
+    const exact = all.data.items.find((item) => item.title === title);
+    const body = failureBody(result, artifactUrl, runUrl);
+    if (exact && exact.state === "open") {
+      await github.rest.issues.createComment({ ...repo, issue_number: exact.number, body });
+    } else {
+      const previous = exact ? `\n\nPrevious issue: #${exact.number}` : "";
+      await github.rest.issues.create({
+        ...repo,
+        title,
+        labels: issueLabels(result.agent),
+        body: body + previous,
+      });
+    }
+  }
+}
+
+module.exports = {
+  sanitizeText,
+  issueTitle,
+  issueLabels,
+  problemType,
+  failureBody,
+  recoveryComment,
+  updateCompatibilityIssues,
+};

session_compass-0.1.0/.github/workflows/cli-compatibility-pr.yml

@@ -0,0 +1,80 @@
+name: CLI compatibility PR check
+
+on:
+  pull_request:
+    branches:
+      - main
+      - dev
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  compatibility:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out pull request
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Run unit and metadata regression tests
+        shell: bash
+        run: PYTHONPATH=src python -m unittest discover -s tests -v
+
+      - name: Install latest public agent CLIs
+        shell: bash
+        run: |
+          set +e
+          npm install --global @anthropic-ai/claude-code
+          npm install --global @openai/codex
+          npm install --global @github/copilot
+          curl -fsSL https://antigravity.google/cli/install.sh | bash
+          exit 0
+
+      - name: Probe version and help contracts
+        continue-on-error: true
+        shell: bash
+        run: |
+          PYTHONPATH=src python scripts/probe_cli_compatibility.py \
+            --output compatibility-report.json
+
+      - name: Sanitize compatibility report
+        if: ${{ always() }}
+        shell: bash
+        run: |
+          if test -f compatibility-report.json; then
+            PYTHONPATH=src python scripts/build_compatibility_report.py \
+              compatibility-report.json \
+              --commit-sha "${GITHUB_SHA}" > compatibility-report-sanitized.json
+          else
+            printf '{"commit_sha":"%s","results":[],"failure":"probe_report_missing"}\n' \
+              "${GITHUB_SHA}" > compatibility-report-sanitized.json
+          fi
+
+      - name: Upload PR compatibility artifact
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-compatibility-pr-${{ github.event.pull_request.number }}-${{ github.run_id }}
+          path: |
+            compatibility-report.json
+            compatibility-report-sanitized.json
+          if-no-files-found: warn
+
+      - name: Fail when any capability check fails
+        if: ${{ always() }}
+        shell: bash
+        run: |
+          test -f compatibility-report.json
+          PYTHONPATH=src python - <<'PY'
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("compatibility-report.json").read_text())
+          raise SystemExit(0 if report and all(item.get("status") == "pass" for item in report) else 1)
+          PY

session_compass-0.1.0/.github/workflows/cli-compatibility.yml

@@ -0,0 +1,101 @@
+name: CLI compatibility
+
+on:
+  schedule:
+    - cron: "0 0 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  compatibility:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Run unit and metadata regression tests
+        shell: bash
+        run: PYTHONPATH=src python -m unittest discover -s tests -v
+
+      - name: Install latest public agent CLIs
+        shell: bash
+        run: |
+          set +e
+          npm install --global @anthropic-ai/claude-code
+          npm install --global @openai/codex
+          npm install --global @github/copilot
+          curl -fsSL https://antigravity.google/cli/install.sh | bash
+          exit 0
+
+      - name: Probe version and help contracts
+        id: probe
+        continue-on-error: true
+        shell: bash
+        run: |
+          # Check resume and native dangerous-permission capabilities only.
+          PYTHONPATH=src python scripts/probe_cli_compatibility.py \
+            --output compatibility-report.json
+
+      - name: Sanitize compatibility report
+        if: ${{ always() }}
+        shell: bash
+        run: |
+          if test -f compatibility-report.json; then
+            PYTHONPATH=src python scripts/build_compatibility_report.py \
+              compatibility-report.json \
+              --commit-sha "${GITHUB_SHA}" > compatibility-report-sanitized.json
+          else
+            printf '{"commit_sha":"%s","results":[],"failure":"probe_report_missing"}\n' \
+              "${GITHUB_SHA}" > compatibility-report-sanitized.json
+          fi
+
+      - name: Upload compatibility artifact
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-compatibility-${{ github.run_id }}
+          path: |
+            compatibility-report.json
+            compatibility-report-sanitized.json
+          if-no-files-found: warn
+
+      - name: Update compatibility issues
+        if: ${{ always() }}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require("fs");
+            const { updateCompatibilityIssues } = require(
+              `${process.env.GITHUB_WORKSPACE}/.github/scripts/update_compatibility_issue.js`
+            );
+            const report = JSON.parse(fs.readFileSync("compatibility-report-sanitized.json", "utf8"));
+            const runUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            await updateCompatibilityIssues({
+              github,
+              context,
+              results: report.results || [],
+              artifactUrl: runUrl,
+              runUrl,
+            });
+
+      - name: Fail when any capability check fails
+        if: ${{ always() }}
+        shell: bash
+        run: |
+          test -f compatibility-report.json
+          PYTHONPATH=src python - <<'PY'
+          import json
+          from pathlib import Path
+
+          report = json.loads(Path("compatibility-report.json").read_text())
+          raise SystemExit(0 if report and all(item.get("status") == "pass" for item in report) else 1)
+          PY

session_compass-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish Session Compass to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/session-compass
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build distributions
+        shell: bash
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Validate distributions
+        shell: bash
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

session_compass-0.1.0/.gitignore

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

session_compass-0.1.0/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.

session_compass-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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