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.

Ask your agent

If the skill is installed, just talk to your agent in plain language — no fms flags needed:

• /find-my-session 找到 claude-code 最近的一个会话，继续那个任务
• /find-my-session find the most recent claude-code session and continue that task
• /find-my-session 额度用完了，在 claude-code 里找昨天关于鉴权的那次会话并接力
• /find-my-session search my claude-code sessions about token refresh and show the handoff digest
• /find-my-session 列出这个项目最近一次 claude-code 会话里我提过的所有需求

The agent resolves the harness, runs search / latest / show / prompts, and continues the work.

Supported harnesses

Twenty-one 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, unzip it into ~/.claude/skills for Claude Code, or 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
   ln -s "$PWD/skills/find-my-session" ~/.claude/skills/find-my-session   # Claude Code; adapt the path for your harness
   

   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 claude-code  # find sessions by keywords
fms latest --harness claude-code --cwd .          # most recent session in this repo
fms show claude-code:c1a0de01                     # low-token handoff digest
fms prompts claude-code:c1a0de01 --count          # count human prompts, then page with --limit/--offset
fms resume claude-code:e1a2b3c4 --exec            # jump straight back into a session
fms stats --since 7d                              # token/cost totals across harnesses

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 claude-code:c1a0de01); a raw transcript path from a supported store works too.

Picking with fzf

Every listing is plain TSV, so interactive picking is a pipe away:

fms search --limit 0 | fzf | cut -f1 | xargs -I{} fms show {}
fms search --limit 0 --include-archived | fzf --with-nth=2,4 | cut -f1 | xargs -I{} fms resume {}

The second recipe resumes the picked session in its own harness when the harness has a verified resume command (see fms resume --help). 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.
• docs/faq.md — 5-minute tutorial and answers to the most common "where is my session" questions.
• 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.