find-my-session

find-my-session

🌐 中文说明

[CI] [OpenSSF Scorecard] [PyPI] [Python 3.9–3.14] [License: MIT]

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]

[Counting and paging the human prompts of one session]

[The find-my-session browser panel reading a synthetic session store]

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-two adapters are ready; one more is 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.

   bash

   git clone https://github.com/SomeNoneAI/find-my-session.gitcd find-my-sessionln -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 harnessesfms search "quota handoff" --harness claude-code  # find sessions by keywordsfms latest --harness claude-code --cwd .          # most recent session in this repofms show claude-code:c1a0de01                     # low-token handoff digestfms prompts claude-code:c1a0de01 --count          # count human prompts, then page with --limit/--offsetfms resume claude-code:e1a2b3c4 --exec            # jump straight back into a sessionfms 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 -vpython3 -m compileall -q core fms_ui skills/find-my-session/scripts tools testspython3 tools/build_artifacts.py   # rebuild dist/find-my-session-skill(.zip) and dist/find-my-session-ui(.zip)

License

MIT. See LICENSE.