find-my-session 0.1.1__tar.gz

find_my_session-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 find-my-session contributors
+
+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.

find_my_session-0.1.1/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: find-my-session
+Version: 0.1.1
+Summary: Read-only, cross-harness agent-session finder and handoff tool
+Author: find-my-session contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SomeNoneAI/find-my-session
+Project-URL: Repository, https://github.com/SomeNoneAI/find-my-session
+Project-URL: Issues, https://github.com/SomeNoneAI/find-my-session/issues
+Project-URL: Changelog, https://github.com/SomeNoneAI/find-my-session/blob/main/CHANGELOG.md
+Project-URL: Roadmap, https://github.com/SomeNoneAI/find-my-session/blob/main/ROADMAP.md
+Keywords: agent,ai,claude-code,cli,codex,developer-tools,handoff,session-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: coverage>=7.6; extra == "dev"
+Requires-Dist: mypy<2,>=1.11; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Dynamic: license-file
+
+# find-my-session
+
+[![CI](https://github.com/SomeNoneAI/find-my-session/actions/workflows/ci.yml/badge.svg)](https://github.com/SomeNoneAI/find-my-session/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/find-my-session.svg)](https://pypi.org/project/find-my-session/)
+[![Python 3.9–3.14](https://img.shields.io/badge/python-3.9%E2%80%933.14-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A local, read-only session finder and handoff tool for coding agents, shipped in two forms that share one `fms_lib` core:
+
+- **find-my-session-skill** — an agent skill (`fms` CLI) that finds the right session across harnesses and prints a low-token handoff digest instead of the whole transcript.
+- **find-my-session-ui** — a human-friendly browser panel for the same stores.
+
+When a harness runs out of quota, you usually remember *what* you were doing but not *where* the session lives. `fms` answers that with one compact command.
+
+![fms search and fms show in a terminal](docs/assets/demo.svg)
+
+![Counting and paging the human prompts of one session](docs/assets/prompts-paging.svg)
+
+![The find-my-session browser panel reading a synthetic session store](docs/assets/ui.png)
+
+Screenshots use synthetic fixture data.
+
+[中文说明](README.zh-CN.md)
+
+## Supported harnesses
+
+Sixteen adapters are ready; two more are planned. Verified versions, surfaces, and caveats live in the [compatibility matrix](docs/compatibility.md); per-harness store details live in [references/](skills/find-my-session/references/).
+
+| Harness | Ref prefix | Store |
+| --- | --- | --- |
+| Qoder CN | `qoder-cn` | `~/.qoder-cn` |
+| Qoder (international) | `qoder` | `~/.qoder` |
+| Kimi Code | `kimi-code` | `~/.kimi-code` |
+| ZCode | `zcode` | `~/.zcode` |
+| CodeArts Agent | `codearts-agent` | `~/.codeartsdoer` |
+| ChatGPT Codex | `codex` | `~/.codex` |
+| DeepSeek Harness | `deepseek` | `~/.dsh` |
+| Claude Code | `claude-code` | `~/.claude` |
+| Cline | `cline` | `~/.cline` |
+| Grok Build | `grok-build` | `~/.grok` |
+| WorkBuddy AI | `workbuddy` | `~/.workbuddy-ai` |
+| WorkBuddy (domestic) | `workbuddy-cn` | `~/.workbuddy` |
+| Antigravity | `antigravity` | `~/.gemini/antigravity` |
+| Antigravity CLI | `antigravity-cli` | `~/.gemini/antigravity-cli` |
+| MiniMax Code | `minimax-code` | `~/.minimax/v2` |
+| Cursor | `cursor` | `~/.cursor/projects` |
+| CodeBuddy | `codebuddy` (planned) | `~/.codebuddy` |
+| Cline (VS Code extension) | `cline-vscode` (planned) | VS Code globalStorage |
+
+## Requirements
+
+- Python 3.9 or newer; macOS or Linux. Python 3.9 is end-of-life upstream and 0.2 is planned to require 3.10+ (see [ROADMAP.md](ROADMAP.md)).
+- No third-party Python packages
+- Compressed stores (`codex` `.jsonl.zst`, `deepseek` `.zstd`) need a zstd decoder: Python 3.14+ or the `zstd` CLI; otherwise those sessions are skipped
+- Windows is exercised by an experimental, non-blocking CI job but is not supported yet; see [ROADMAP.md](ROADMAP.md)
+
+## Install
+
+### CLI and UI commands
+
+`pipx install find-my-session` installs the `fms` and `fms-ui` commands from PyPI. To run an unreleased commit, install from Git instead: `pipx install git+https://github.com/SomeNoneAI/find-my-session.git`. Use `pipx upgrade find-my-session` to upgrade or `pipx uninstall find-my-session` to remove them. With `uv`, `uvx --from find-my-session fms ...` runs the PyPI release without a permanent install.
+
+### For agents: the skill
+
+1. **Release ZIP.** Each GitHub Release publishes `find-my-session-skill.zip`. Download it from the [latest release](https://github.com/SomeNoneAI/find-my-session/releases/latest), then install it into your harness (for example, upload it in Qoder Desktop under **Extensions → Skills**, or unzip it and link the directory into your harness's skills folder).
+2. **Source checkout.**
+
+   ```bash
+   git clone https://github.com/SomeNoneAI/find-my-session.git
+   cd find-my-session
+   qoderclicn skills link "$PWD/skills/find-my-session"   # Qoder CN CLI; Claude Code: symlink into ~/.claude/skills
+   ```
+
+   From a checkout you can also run the CLI directly as `python3 skills/find-my-session/scripts/fms`, or run `python3 tools/build_artifacts.py` to build `dist/find-my-session-skill.zip` yourself. To remove a linked skill, delete its symlink from the harness's skills folder.
+
+### For humans: the UI panel
+
+1. **Release ZIP.** Download `find-my-session-ui.zip` from the [latest release](https://github.com/SomeNoneAI/find-my-session/releases/latest), extract it, and run `python3 fms-ui` from the extracted directory (or `./fms-ui` when your extractor preserves executable bits). Replace that directory to upgrade or delete it to uninstall.
+2. **pipx.** The same pipx install above provides the `fms-ui` command.
+3. **Source checkout.** Run `fms_ui/fms-ui` (use `--no-browser --port 8765` to pick a port without opening a browser).
+
+The panel starts a read-only server on `127.0.0.1` with keyword and metadata filters, session overviews, paged user prompts, recent turns, and copyable refs. The static frontend uses only same-origin JSON APIs — no Node.js, no external assets. Language follows the local system, with an explicit zh/en switch. The interface also follows the system light/dark preference, with a manual toggle and a non-black dark palette. The frontend is built with Vue 3 + TypeScript + Vite; Node.js is needed only when developing it from `fms_ui/frontend/`, never to run the panel.
+
+## Quick start
+
+```bash
+fms harnesses                                   # list ready and planned harnesses
+fms search "quota handoff" --harness kimi-code  # find sessions by keywords
+fms latest --harness kimi-code --cwd .          # most recent session in this repo
+fms show kimi-code:e5f6a7b8                     # low-token handoff digest
+fms prompts kimi-code:e5f6a7b8 --count          # count human prompts, then page with --limit/--offset
+```
+
+Search prefers an explicit `--harness`; omit the query to list recent sessions. Archived sessions are excluded from `search`/`latest` unless `--include-archived` is passed. `show` stays read-only and prints the raw source path so an agent can grep the original file when the digest is not enough.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `fms harnesses` | List ready and planned harnesses, variants, and stores. |
+| `fms search [query ...]` | Search session metadata by keywords; omit the query to list recent sessions. |
+| `fms latest` | Return the most recent matching session. |
+| `fms show <ref>` | Print a handoff digest for one session. |
+| `fms prompts <ref>` | List every human prompt in one session; count, page, and order them. |
+| `fms doctor [--harness] [--json] [--fingerprint]` | Check the local environment and stores (decoder availability, readable roots, per-harness health); `--fingerprint` adds a content-free shape summary for drift reports. |
+
+## Useful options
+
+| Option | Applies to | Meaning |
+| --- | --- | --- |
+| `--harness NAME[,NAME]` | search, latest, show, prompts, doctor | Restrict lookup to a harness. Recommended for speed and precision. |
+| `--cwd PATH` | search, latest | Match a session whose working directory contains, or is contained by, `PATH`. |
+| `--since 7d` / `--since 2026-10-01` | search, latest | Filter by last update time. |
+| `--limit N` | search, latest, prompts | Limit results or prompts; `0` means unlimited. |
+| `--offset N` | prompts | Skip the first N prompts. |
+| `--order oldest/newest` | prompts | Page order; original indices are preserved. |
+| `--count` | prompts | Print only the total prompt count. |
+| `--deep` | search, latest | Also scan full transcripts. Slower; still prints metadata only. |
+| `--include-archived` | search, latest | Include archived sessions. Off by default. |
+| `--verbose` | search, latest | Warn about skipped sessions on stderr without changing stdout. |
+| `--messages N` / `--chars N` / `--summary-chars N` | show | Cap turns, per-message characters, and summary characters. |
+| `--json` | harnesses, search, latest, prompts, doctor | Machine-readable output; use `--format json` for `show`. See [docs/json-output.md](docs/json-output.md) for the field contract. |
+
+Session references use `harness:session-prefix` (for example `kimi-code:e5f6a7b8`); a raw transcript path from a supported store works too. Desktop/CLI surfaces that share one store share one ref space — see the [compatibility matrix](docs/compatibility.md) for which surfaces are verified.
+
+## Privacy and safety
+
+- Everything runs locally; the CLI makes no network requests.
+- The CLI only reads session files and databases, opening SQLite stores read-only; it never edits or deletes session content.
+- Search output is metadata-only; `show` and `prompts` can print conversation content, so treat their output like the original transcript.
+
+## Development and documentation
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, and how to add or verify a harness.
+- [docs/compatibility.md](docs/compatibility.md) — the detailed, per-harness compatibility matrix.
+- [docs/json-output.md](docs/json-output.md) — the `--json` field contract and pre-1.0 stability policy.
+- [ROADMAP.md](ROADMAP.md) — near-term plans.
+- [SECURITY.md](SECURITY.md) — supported versions and private vulnerability reporting.
+- [skills/find-my-session/references/](skills/find-my-session/references/) — per-harness store schemas and verification recipes; start with [extending.md](skills/find-my-session/references/extending.md) to add a harness.
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 -m compileall -q core fms_ui skills/find-my-session/scripts tools tests
+python3 tools/build_artifacts.py   # rebuild dist/find-my-session-skill(.zip) and dist/find-my-session-ui(.zip)
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

find_my_session-0.1.1/README.md

@@ -0,0 +1,149 @@
+# find-my-session
+
+[![CI](https://github.com/SomeNoneAI/find-my-session/actions/workflows/ci.yml/badge.svg)](https://github.com/SomeNoneAI/find-my-session/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/find-my-session.svg)](https://pypi.org/project/find-my-session/)
+[![Python 3.9–3.14](https://img.shields.io/badge/python-3.9%E2%80%933.14-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A local, read-only session finder and handoff tool for coding agents, shipped in two forms that share one `fms_lib` core:
+
+- **find-my-session-skill** — an agent skill (`fms` CLI) that finds the right session across harnesses and prints a low-token handoff digest instead of the whole transcript.
+- **find-my-session-ui** — a human-friendly browser panel for the same stores.
+
+When a harness runs out of quota, you usually remember *what* you were doing but not *where* the session lives. `fms` answers that with one compact command.
+
+![fms search and fms show in a terminal](docs/assets/demo.svg)
+
+![Counting and paging the human prompts of one session](docs/assets/prompts-paging.svg)
+
+![The find-my-session browser panel reading a synthetic session store](docs/assets/ui.png)
+
+Screenshots use synthetic fixture data.
+
+[中文说明](README.zh-CN.md)
+
+## Supported harnesses
+
+Sixteen adapters are ready; two more are planned. Verified versions, surfaces, and caveats live in the [compatibility matrix](docs/compatibility.md); per-harness store details live in [references/](skills/find-my-session/references/).
+
+| Harness | Ref prefix | Store |
+| --- | --- | --- |
+| Qoder CN | `qoder-cn` | `~/.qoder-cn` |
+| Qoder (international) | `qoder` | `~/.qoder` |
+| Kimi Code | `kimi-code` | `~/.kimi-code` |
+| ZCode | `zcode` | `~/.zcode` |
+| CodeArts Agent | `codearts-agent` | `~/.codeartsdoer` |
+| ChatGPT Codex | `codex` | `~/.codex` |
+| DeepSeek Harness | `deepseek` | `~/.dsh` |
+| Claude Code | `claude-code` | `~/.claude` |
+| Cline | `cline` | `~/.cline` |
+| Grok Build | `grok-build` | `~/.grok` |
+| WorkBuddy AI | `workbuddy` | `~/.workbuddy-ai` |
+| WorkBuddy (domestic) | `workbuddy-cn` | `~/.workbuddy` |
+| Antigravity | `antigravity` | `~/.gemini/antigravity` |
+| Antigravity CLI | `antigravity-cli` | `~/.gemini/antigravity-cli` |
+| MiniMax Code | `minimax-code` | `~/.minimax/v2` |
+| Cursor | `cursor` | `~/.cursor/projects` |
+| CodeBuddy | `codebuddy` (planned) | `~/.codebuddy` |
+| Cline (VS Code extension) | `cline-vscode` (planned) | VS Code globalStorage |
+
+## Requirements
+
+- Python 3.9 or newer; macOS or Linux. Python 3.9 is end-of-life upstream and 0.2 is planned to require 3.10+ (see [ROADMAP.md](ROADMAP.md)).
+- No third-party Python packages
+- Compressed stores (`codex` `.jsonl.zst`, `deepseek` `.zstd`) need a zstd decoder: Python 3.14+ or the `zstd` CLI; otherwise those sessions are skipped
+- Windows is exercised by an experimental, non-blocking CI job but is not supported yet; see [ROADMAP.md](ROADMAP.md)
+
+## Install
+
+### CLI and UI commands
+
+`pipx install find-my-session` installs the `fms` and `fms-ui` commands from PyPI. To run an unreleased commit, install from Git instead: `pipx install git+https://github.com/SomeNoneAI/find-my-session.git`. Use `pipx upgrade find-my-session` to upgrade or `pipx uninstall find-my-session` to remove them. With `uv`, `uvx --from find-my-session fms ...` runs the PyPI release without a permanent install.
+
+### For agents: the skill
+
+1. **Release ZIP.** Each GitHub Release publishes `find-my-session-skill.zip`. Download it from the [latest release](https://github.com/SomeNoneAI/find-my-session/releases/latest), then install it into your harness (for example, upload it in Qoder Desktop under **Extensions → Skills**, or unzip it and link the directory into your harness's skills folder).
+2. **Source checkout.**
+
+   ```bash
+   git clone https://github.com/SomeNoneAI/find-my-session.git
+   cd find-my-session
+   qoderclicn skills link "$PWD/skills/find-my-session"   # Qoder CN CLI; Claude Code: symlink into ~/.claude/skills
+   ```
+
+   From a checkout you can also run the CLI directly as `python3 skills/find-my-session/scripts/fms`, or run `python3 tools/build_artifacts.py` to build `dist/find-my-session-skill.zip` yourself. To remove a linked skill, delete its symlink from the harness's skills folder.
+
+### For humans: the UI panel
+
+1. **Release ZIP.** Download `find-my-session-ui.zip` from the [latest release](https://github.com/SomeNoneAI/find-my-session/releases/latest), extract it, and run `python3 fms-ui` from the extracted directory (or `./fms-ui` when your extractor preserves executable bits). Replace that directory to upgrade or delete it to uninstall.
+2. **pipx.** The same pipx install above provides the `fms-ui` command.
+3. **Source checkout.** Run `fms_ui/fms-ui` (use `--no-browser --port 8765` to pick a port without opening a browser).
+
+The panel starts a read-only server on `127.0.0.1` with keyword and metadata filters, session overviews, paged user prompts, recent turns, and copyable refs. The static frontend uses only same-origin JSON APIs — no Node.js, no external assets. Language follows the local system, with an explicit zh/en switch. The interface also follows the system light/dark preference, with a manual toggle and a non-black dark palette. The frontend is built with Vue 3 + TypeScript + Vite; Node.js is needed only when developing it from `fms_ui/frontend/`, never to run the panel.
+
+## Quick start
+
+```bash
+fms harnesses                                   # list ready and planned harnesses
+fms search "quota handoff" --harness kimi-code  # find sessions by keywords
+fms latest --harness kimi-code --cwd .          # most recent session in this repo
+fms show kimi-code:e5f6a7b8                     # low-token handoff digest
+fms prompts kimi-code:e5f6a7b8 --count          # count human prompts, then page with --limit/--offset
+```
+
+Search prefers an explicit `--harness`; omit the query to list recent sessions. Archived sessions are excluded from `search`/`latest` unless `--include-archived` is passed. `show` stays read-only and prints the raw source path so an agent can grep the original file when the digest is not enough.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `fms harnesses` | List ready and planned harnesses, variants, and stores. |
+| `fms search [query ...]` | Search session metadata by keywords; omit the query to list recent sessions. |
+| `fms latest` | Return the most recent matching session. |
+| `fms show <ref>` | Print a handoff digest for one session. |
+| `fms prompts <ref>` | List every human prompt in one session; count, page, and order them. |
+| `fms doctor [--harness] [--json] [--fingerprint]` | Check the local environment and stores (decoder availability, readable roots, per-harness health); `--fingerprint` adds a content-free shape summary for drift reports. |
+
+## Useful options
+
+| Option | Applies to | Meaning |
+| --- | --- | --- |
+| `--harness NAME[,NAME]` | search, latest, show, prompts, doctor | Restrict lookup to a harness. Recommended for speed and precision. |
+| `--cwd PATH` | search, latest | Match a session whose working directory contains, or is contained by, `PATH`. |
+| `--since 7d` / `--since 2026-10-01` | search, latest | Filter by last update time. |
+| `--limit N` | search, latest, prompts | Limit results or prompts; `0` means unlimited. |
+| `--offset N` | prompts | Skip the first N prompts. |
+| `--order oldest/newest` | prompts | Page order; original indices are preserved. |
+| `--count` | prompts | Print only the total prompt count. |
+| `--deep` | search, latest | Also scan full transcripts. Slower; still prints metadata only. |
+| `--include-archived` | search, latest | Include archived sessions. Off by default. |
+| `--verbose` | search, latest | Warn about skipped sessions on stderr without changing stdout. |
+| `--messages N` / `--chars N` / `--summary-chars N` | show | Cap turns, per-message characters, and summary characters. |
+| `--json` | harnesses, search, latest, prompts, doctor | Machine-readable output; use `--format json` for `show`. See [docs/json-output.md](docs/json-output.md) for the field contract. |
+
+Session references use `harness:session-prefix` (for example `kimi-code:e5f6a7b8`); a raw transcript path from a supported store works too. Desktop/CLI surfaces that share one store share one ref space — see the [compatibility matrix](docs/compatibility.md) for which surfaces are verified.
+
+## Privacy and safety
+
+- Everything runs locally; the CLI makes no network requests.
+- The CLI only reads session files and databases, opening SQLite stores read-only; it never edits or deletes session content.
+- Search output is metadata-only; `show` and `prompts` can print conversation content, so treat their output like the original transcript.
+
+## Development and documentation
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, and how to add or verify a harness.
+- [docs/compatibility.md](docs/compatibility.md) — the detailed, per-harness compatibility matrix.
+- [docs/json-output.md](docs/json-output.md) — the `--json` field contract and pre-1.0 stability policy.
+- [ROADMAP.md](ROADMAP.md) — near-term plans.
+- [SECURITY.md](SECURITY.md) — supported versions and private vulnerability reporting.
+- [skills/find-my-session/references/](skills/find-my-session/references/) — per-harness store schemas and verification recipes; start with [extending.md](skills/find-my-session/references/extending.md) to add a harness.
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 -m compileall -q core fms_ui skills/find-my-session/scripts tools tests
+python3 tools/build_artifacts.py   # rebuild dist/find-my-session-skill(.zip) and dist/find-my-session-ui(.zip)
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

find_my_session-0.1.1/core/fms_lib/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"