find-my-session

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.

Screenshots use synthetic fixture data.

中文说明

Supported harnesses

Sixteen adapters are ready; two more are planned. Verified versions, surfaces, and caveats live in the compatibility matrix; per-harness store details live in references/.

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).
• 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

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, 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.

   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, 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

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

Useful options

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 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 — setup, tests, and how to add or verify a harness.
• docs/compatibility.md — the detailed, per-harness compatibility matrix.
• docs/json-output.md — the --json field contract and pre-1.0 stability policy.
• ROADMAP.md — near-term plans.
• SECURITY.md — supported versions and private vulnerability reporting.
• skills/find-my-session/references/ — per-harness store schemas and verification recipes; start with extending.md to add a harness.

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.