MCP server passbaton
Коммит 7 нояб. 2026 г.Обеспечивает непрерывность сессий для ИИ-агентов при написании кода, автоматически внедряя контекст проекта и историю недавних действий в новые сессии.
Также известен как leesgit/passbaton
- Звёзды
- 7
- Инструменты
- —
- Загрузки, 30 дней
- —
- Последняя версия
- —
- Последний коммит
- 7 нояб. 2026 г.
- Лицензия
- MIT
Что такое passbaton MCP?
passbaton — это MCP server. Обеспечивает непрерывность сессий для ИИ-агентов при написании кода, автоматически внедряя контекст проекта и историю недавних действий в новые сессии.
Сводка сгенерирована из README проекта
О passbaton MCP server
passbaton обеспечивает непрерывность сессий для ИИ-агентов, автоматически управляя контекстом проекта и историей недавних действий. Инструмент разработан для разработчиков, использующих Claude Code, OpenAI Codex CLI или Google Gemini CLI. Система работает локально с использованием базы данных SQLite, что гарантирует хранение всех данных на вашем устройстве без дополнительных затрат на API и необходимости использования внешних облачных сервисов.
Вместо того чтобы каждый раз вручную объяснять архитектуру проекта или принятые решения при запуске новой сессии, этот инструмент использует хуки жизненного цикла для автоматического внедрения релевантных воспоминаний, результатов недавней работы и пар «ошибка — решение». Он поддерживает семантический поиск и выполняет сжатие контекста, чтобы даже после длительных диалогов агент сохранял четкое понимание текущей задачи. Разработчики также могут настроить чтение определенных файлов проекта, таких как HANDOFF.md или файлы планов, в рамках последовательности запуска сессии.
Что вы можете с ним делать
- 1Возобновление задачи по написанию кодаПопросите агента продолжить работу над конкретной функцией, автоматически загрузив состояние предыдущей сессии и недавние коммиты.
- 2Исправление ошибок на основе прошлого опытаПредоставьте агенту историю прошлых ошибок и соответствующих им исправлений, чтобы предотвратить повторение одних и тех же ошибок.
Взято из README проекта. Каждый вариант использования проверен на соответствие цитате из него.
Конфигурация
MCP_HOOKS_DISABLED
| Название | Описание | Тип |
|---|---|---|
| MCP_HOOKS_DISABLED | — |
Автоматические проверки
Запущено 14 нояб. 2026 г.Полный отчёт →Еще не проверено. Для сервера требуется оценка 80, отсутствие серьезных проблем и достаточно данных для нашей проверки. Как работают проверки · Что исправить, чтобы получить больше баллов
- Связанный и доступный исходный репозиторийleesgit/passbaton is public and reachablegithub.com/leesgit/passbaton ↗Пройдено
- Пакет указывает этот репозиторий как источникНе проверялось
- Происхождение сборки (аттестация Sigstore)Не проверялось
- Open source лицензия (OSI)MITspdx.org/licenses/MIT.html ↗Пройдено
- Коммит или релиз за последний годLast commit or release 2026-11-07github.com/leesgit/passbaton ↗Пройдено
- OpenSSF ScorecardНе проверялось
- Имя пакета не похоже на популярный пакетНе проверялось
- Нет критических предупреждений в пакете или его зависимостяхНе проверялось
- Нет скрытых инструкций для модели0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersПройдено
- Деструктивные инструменты помеченыНе проверялось
- Удалённая конечная точка отвечает на рукопожатие MCPНе проверялось
README
Открыть на GitHubpassbaton
Session continuity for AI coding agents. Your agent picks up where it left off — never re-explain your project again. Persistent memory for Claude Code, OpenAI Codex CLI & Google Gemini CLI, sharing one local db: auto context injection, compaction handover, semantic search, and error→solution recall. Zero config, zero API cost, 100% local.
⚡ One install → context auto-loads every session · 🧩 survives compaction (0 re-explaining) · 🔒 100% local, $0 API

Renamed (v2.0.0): this project was previously
claude-session-continuity-mcp. The old name suggested it was Claude-only — it never was. Claude Code, Codex CLI, and Gemini CLI are all first-class and share one local memory. Existing installs keep working: the oldclaude-hook-*commands still ship as aliases. See Migrating from v1.
The Problem
Every new session — whether you're in Claude Code, Codex CLI, or Gemini CLI:
"This is a Next.js 15 project with App Router..."
"We decided to use Server Actions because..."
"Last time we were working on the auth system..."
"The build command is pnpm build..."
5 minutes of context-setting. Every. Single. Time.
The Solution
Fully automatic. Lifecycle hooks handle everything without manual calls — on Claude Code, OpenAI Codex CLI, and Google Gemini CLI, sharing one local memory so context carries across all three:
# Session start → Auto-loads relevant context + recent session history
# When asking → Auto-injects relevant memories/solutions
# During conversation → Tracks active files (Edit, Write)
# On compact → Structured handover context for continuity
# On exit → Extracts commits, decisions, error-fix pairs from transcript
← Auto-output on session start:
# my-app - Session Resumed
📍 **State**: Implementing signup form
## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration with Google provider
**Commits**: feat: add OAuth callback handler; fix: redirect URI config
**Decisions**: Use Server Actions instead of API routes
### 2026-02-27
**Work**: Set up authentication foundation
**Next**: Implement signup form validation
## Directives
- 🔴 Always use Zod for form validation
- 📎 Prefer Server Components by default
## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env file
Zero manual work. Context follows you.
Why this over other memory tools?
Most Claude memory tools rely on explicit tool calls ("remember this"), a cloud API, or a background AI worker. This one is deliberately different:
| passbaton | Typical cloud/AI-memory MCP | |
|---|---|---|
| Setup | npm i -g → hooks auto-install |
Manual server + API key |
| Trigger | 5 automatic hooks (no commands) | You call a remember tool |
| Storage | 100% local SQLite | Cloud / external service |
| API cost | $0 — local embeddings | Per-token / subscription |
| Latency | < 5ms (on-device) | Network round-trip |
| Privacy | Never leaves your machine | Sent to a provider |
| Search | FTS5 + local semantic, KO/EN/JA cross-lingual | Varies |
If you want zero-config, offline, no-cost memory that just happens while you work — this is it.
Auto-injection vs. explicit search
There's also a great class of local search tools (e.g. ctx) that index your agent history so you can query it (search "failed migration"). That's complementary, not the same job:
| passbaton | Local-search tools (ctx, etc.) | |
|---|---|---|
| How you use it | Automatic — context appears on session start, no command | You (or the agent) run a search query |
| Compaction | PreCompact hook re-injects a handover → 0 context re-explained after a compact | Not its job (it's a search index) |
| Best at | Never losing your thread across sessions & compacts, hands-off | Finding a specific past decision/command on demand |
| Coverage | Claude Code + Codex CLI + Gemini CLI (where auto-injection is possible) | Often 30+ agents indexed for search |
Use search when you want to look something up. Use this when you want your context to follow you without asking.
Resume card — the repo is the source of truth (v2.6.0+)
Long-running projects usually keep their real hand-off in the repo — a HANDOFF.md whose newest
entry is on top, a plan file with a "current task" block, a stop file left by an unattended loop.
A DB summary of the last session cannot replace those, and it goes stale the moment someone else
edits them. Since 2.6.0 a project can declare those files, and SessionStart shows verbatim
excerpts of them first, each with its line range and a content hash:
// <project>/.claude/passbaton.config.json
{
"continuity": {
"sources": [
{ "path": "docs/HANDOFF.md", "lines": 30, "label": "HANDOFF (newest entry)" },
{ "path": ".ralph/fix_plan.md", "block": "지금 할 일", "label": "current task" },
{ "path": ".ralph/DEMO_STOP", "lines": 3, "label": "loop stop reason" }
]
}
}
lines— the first N lines (default 40, max 200)block— the first list item or heading containing that text, up to the next item/heading of the same or higher level (max 120 lines)- Files are re-read on every start (never cached). A source that cannot be read is shown as NOT READ, never silently dropped
- When a card is present the DB state is relabelled Last recorded state (may be stale)
- The same card is available as the read-only MCP tool
resume_card, so another agent can read it too - Boundaries — the real path (after links/junctions) must stay inside the project; regular text files only
(
.md.markdown.txt.rstor no extension, checked on the link target too); at most the first 2 MB is read; at most 8 sources. Names that usually hold secrets are never read even if declared: any path segment matching.env*,.git,.ssh,.aws,.gnupg,.npmrc,.netrc,id_*,credentials*,secret(s)*,*.pem,*.key,*.pfx… (sodocs/credentials-guide.mdis refused;docs/secret-sauce.mdis not — rename rather than weaken the rule) PASSBATON_CARD_CHARS(default 3200, 400–20000) caps the whole card, headings included- (v2.7.2+) Space a missing or short source leaves unused is handed once, evenly, to the sources that were cut by their share
(never to a source that hit its own
lines/block cap, never reviving an omitted one). What was already shown stays as the start of each excerpt; if the files change between reads or the rendered card would exceed the cap, the card stays as it was. Ashfall: 2,390 → 3,064 of 3,200 chars, +3 ms - (v2.7.3+) Run origin. A loop (e.g. Ralph) exports
PASSBATON_ROLE=loop; Stop stores it per row (sessions.run_origin). Only the exact valueloopcounts — unset or anything else isunknown(never assumed to be a conversation); old rows stayunknown. The origin is not part of duplicate suppression, so a re-delivered Stop is still one row. - (v2.7.3+) Conversation cards hide confirmed loop rows from Recent Sessions (filtered in SQL before
LIMIT 3, rows are never deleted);unknownrows stay and are tagged[origin unknown]. A loop session keeps the old behaviour. The same applies to the card's 📍 State line: if the stored state links to a confirmed loop row, the card shows the newest eligible non-loop record instead (text, time and origin from that one record), ornone— never the loop state. The line now carriesrecorded … · origin unknown; a state that links to no session row is not assumed to be a conversation. The verification Heads up is not filtered by origin — it is labelled a project-wide verification record. - (v2.7.3+) Current-task warning. Mark a source
"role": "current-task"; if that block is missing (no_block), the file is missing/unreadable, or the block is empty, the card's first line is⚠ CURRENT TASK UNKNOWN …. An explicit "none — waiting" block is a normal read (no warning); a source hidden by the budget getsℹ … (card budget — not a failure). - (v2.7.3+, off by default) Loop minimal card. With
"continuity": { "loopCard": "minimal" }andPASSBATON_ROLE=loop, sources marked"role": "current-task"or"history"show only path · range · sha1 · status ("read the source directly"); unmarked sources (stop file, decision index) keep their bodies, and Recent Sessions is left out. Sources are still read every time. Node comparison on an Ashfall copy:docs/pb154-m1-card-compare.md - (v2.7.3+) Optional sources.
"optional": trueon a source turns only "file not found" into a neutralfile absent (optional source — not an error)line (for a stop file that normally does not exist). Boundary/secret/type refusals, unreadable files, a missing block, an empty range and truncation still show as before; an absent source never counts as "read". A non-boolean value is reported as ignored and the source keeps the default behaviour. - (v2.7.3+) Summary provenance. Stop stores which branch produced the summary (
sessions.summary_source,active_context.state_source): commit message · assistant text · fallback (action line or file list) · no result. The 📍 State line and each Recent Sessions row show it from that same record (_(via commit message · …)_); old rows and rows written by other tools showvia unknown(never guessed from the text). A commit-message summary is still not proof that the work is done. - (v2.7.3+) Less noise, same meaning. A Recent row with zero observations from a complete check is shortened to
files: 0 obs in checked scope · 1/1 roots · boundary=turn_start · declared 1 (valid 1); partial checks, skipped roots, no baseline, declaration errors and "not recorded" keep the long form. TheSolutions: N recordedstatistic is left out only when a resume card with at least one read source was delivered to a non-loop session. - (v2.8+) No error-time solution injection. The PostToolUse Bash-error →
<past-solution>path is gone: the installer only ever registered that hook forEdit/Write, so no installed setup ever reached it. Recording error→fix pairs at Stop and the MCP tools (solution_record,solution_find,solution_suggest) are unchanged. - (v2.8+) Compaction recovery fixes. PreCompact no longer fails on a hooks-only database (no
project_contexttable — that table is created only by the MCP server): the handover row is stored and the "context saved" notice is shown. A table that exists but cannot be read is still reported as an error. The "Last human request" line is taken only from realusertranscript lines — API request copies (api-request-blob) and notification renders are skipped, and notifications with attributes (<system-reminder id="…">) are stripped. If no human request can be identified, the line saysnot identifiedinstead of showing leftover text. - (v2.8+) Partial state writes keep the other fields. Every writer of
active_context(Stop, PostToolUse, PreCompact, MCPsession_end, …) now updates only the columns it actually has. An omitted field is kept; an explicitnull/empty string still clears it. Writing the State also writes where it came from, and only a State write movesupdated_at. - (v2.8+) Past-work lookup stays in the current project. "Last time …" prompts search sessions, memories and solutions
filtered to the current project before sorting and
LIMIT; rows with no project are never shown, nothing is searched when the project is unknown, and memories need the same eligibility as at SessionStart (unverified ones are not injected). - (v2.8+) Injection ledger (with
hookTraceon). Each hook writes, per emitted fragment, its source, source ids, UTF-8 bytes, byte offset in the emitted body and a hash, plus one line per omitted fragment with the reason and anemittedtotal — all measured on the body actually printed; turning the trace on or off does not change that body. Source ids are the real ones: DB rows by their keys (s:12,m:4,active_context,session_route:<session>/<project>); files in a routed card as<workspace path>:<from>-<to>@<sha1 of that range>(~<last shown line>when cut), files in the SessionStart card as<path>@<sha1>. A source that could not be read is written as<path>@<outcome>without a hash; no DB id is written for a row that does not exist.
Two side-effect-free CLIs for hand-offs between agents (v2.8+)
Both are separate entry points that never open the database (the passbaton binary opens it on start) and never write
hook traces or settings.
passbaton-card — a snapshot of the resume card, for handing to another agent (e.g. a reviewer model) exactly as built.
passbaton-card --project-dir <dir> --out <card.md> [--meta <meta.json>] [--max-chars N] [--origin loop|unknown] [--no-git] [--force]
passbaton-card --verify <meta.json> [--card <card.md>]
- Writes only
--out(the card bytes) and--meta(or prints the meta to stdout). Refuses to overwrite without--forceand does not create directories — a snapshot is meant to be immutable. - Each source file is read once; the card text, the whole-file SHA-256, the selected range (and its SHA-256), truncation /
omission / budget-hidden state and
delivery: full | partial | noneall come from that same buffer. The meta also records the render version, the SHA-256 ofpassbaton.config.jsonand of the whole card. Git blob/HEAD comparison is auxiliary only — untracked and modified files are identified by their bytes. - The meta says
claims: card-file-created-only. A snapshot proves which bytes were in the card when it was made; it is not proof that anyone received or read it.--verifyre-reads the files and reports what changed since (the card file itself, a source, or the config). - A card can be complete while a source inside it is only partly shown (
delivery: partial): "the card arrived whole" is not "every source arrived whole". - Exit codes:
0ok / match ·1verify mismatch ·2usage ·3no sources declared (no card) ·4write refused or failed.
passbaton-search — direct text search over declared sources only. No index, no embeddings.
passbaton-search --project-dir <dir> [--config <file>] [--max-results N] [--no-git] [--json] <query…>
passbaton-search --verify <report.json>
passbaton-search --project-dir <dir> --gold <gold.json> [--config <file>] [--no-git]
- Searches
search.sourcesin.claude/passbaton.config.json({path}·{glob}· optionalblock= only under that heading); without it, only thecontinuity.sourcespaths...and absolute paths are refused; a sub-folder with its own passbaton config or.gitis treated as another project and skipped. Default 20 results (max 200). - Each hit: path, heading path, line range, SHA-256 of the whole file, of the range and of the excerpt (bytes actually read),
the excerpt, and git status (auxiliary).
--verifyre-reads a saved--jsonreport and flags changed or deleted sources. - Supersession is only shown from explicit evidence: rows of a declared
search.supersessiontable (| target | relation | evidence |) that name a section (§N). Rows without a section are listed underignoredEvidence. Without evidence the label is대체 관계 미확인(supersession unknown) — never "still valid" and never "wholly replaced". ⚠ Labels attach to a whole numbered section, while real evidence is often one clause of it; a clause-level replacement can therefore look like a whole-section one. Don't wire a supersession table into real search until that is fixed. - Text search only finds the words that are there. Measured on one project's decision records (8 fixed questions): 0/8 with the default sources, 2/8 with the decision replies declared — every remaining miss was a vocabulary mismatch (the answer section never uses the question's words). Paraphrased questions miss.
- Output carries
authority: none — lookup aid only …— results are pointers to read, not permission to act, and nothing is written back. - Exit codes:
0ok / match / gold passed ·1verify mismatch / gold failed ·2usage ·3no sources declared.
Routing from a workspace root (v2.7.0+)
Project detection follows the cwd, so a conversation opened at a monorepo root never got a sub-project's card.
Declare which commands select which project in the root .claude/passbaton.config.json:
{ "routing": { "commands": { "/ashfall": "apps/kenshi-fantasy", "/astra": "apps/kenshi-fantasy", "/home": "." } } }
- Only a registered command at the very start of what you type selects a project (
/ashfall …). The same text inside a sentence, a quote, code, a path mention or a harness notification does not. (Claude Code passes the typed text to the hook as-is — observed with a no-output probe hook underclaude -p,tests/fixtures/hook-input-claude-code-2026-10-23.json— so the expanded<command-name>form seen in transcripts is not accepted.) Define every routing and release command as a real command (.claude/commands/<name>.md): whether an undefined/namereaches the hook in the interactive UI was not observed - Routing runs only when the hook's
cwdis the workspace root (same real path — a sub-app with the root's name does not count; nocwdin the input means no routing) - A release command (mapped to
".") is required. Without one, routing is off as a whole - The choice is per session and survives compaction/resume of that session; a new session starts unrouted. Another routed command switches; the release command releases. If the chosen mapping disappears from the config, the next turn says once that the route was cleared
- The card is sent when the choice changes, when the card (or its header — e.g. a renamed release command) changes, and after compaction — not every turn. If the post-compaction card did not fit the budget, it is sent on the next turn
- The card says what selected it and that the conversation is still recorded under the root project — passbaton does not re-file root sessions under the sub-project
- Paths must be real directories inside the workspace (checked after links/junctions); invalid entries are ignored
- All of this goes out in the hook's single output (Codex/Gemini receive one JSON object)
- Cost (Ashfall data, 15 runs, median, Windows): 94 ms (2.6.1) → 100 ms with nothing selected, 112 ms with a selection held
Recording routed turns under the routed project — opt-in (v2.9.0+)
By default (above) every turn of a root conversation is recorded under the root, so the root's next card fills up with sub-project work. Opt in per workspace:
{ "routing": { "commands": { "/ashfall": "apps/kenshi-fantasy", "/home": "." }, "record": "target" } }
- From then on, each turn taken while a route is selected is recorded under the routed project (same DB file — only the
projectvalue changes). The root card no longer shows it; a session opened inside that project does. Turns after the release command go back to the root. Old rows are not moved or re-classified. - A routed turn's summary comes from that turn's answer only — commits, decisions and earlier answers collected from the whole transcript (possibly another project's segment) are not used for it
- Provenance:
sessions.routed_from={root, via, target, since, session, turn}. When the route no longer maps, the target name equals the root's, or two routed folders share a name, the turn stays under the root with{root, unattributed, …} - Auto-extracted memories, solutions and decisions still go to the root project (unchanged)
- Any other
recordvalue is ignored (root) and reported as invalid; the same command declared twice with different case is rejected (it used to be silently overwritten)
Check what the hooks will read, without a DB or side effects:
npx passbaton-card --routes # or: --workspace <root>
# ROUTES workspace=… record=target · ROUTE /ashfall -> apps/kenshi-fantasy project=kenshi-fantasy dir=… · ROUTES-CHECK ok
Exit 0 = fine · 1 = invalid entry, disabled declaration or a project-name clash · 3 = no declaration.
One workspace root for the server, hooks and config CLI (v2.9.0+)
The MCP server and the config CLI had their own root detectors. The server stopped at the nearest .claude/ and had no
home guard, so a sub-repo apps/<app>/ with its own .claude/ made the server open apps/<app>/.claude/sessions.db
while the hooks wrote to the monorepo DB. All three now use the hooks' resolver. The home guard also stops at the real
account profile (os.userInfo().homedir), not only HOME/USERPROFILE — with HOME redirected, runs could climb into
the real ~/.claude/sessions.db.
Card source options: ages, tally, need, health — opt-in (v2.10.0+)
All four are optional per source in continuity.sources. Without them the card bytes are the same as 2.9.
{ "continuity": { "sources": [
{ "path": "docs/PENDING", "label": "requests", "ages": true, "tally": ["waiting for reply", "needs prep"] },
{ "path": "docs/INDEX.md", "block": "Active", "label": "decision index", "need": { "rows": 1, "items": ["Active"], "chars": 600 } },
{ "path": ".runner/health.json", "label": "run health", "health": { "maxAgeMinutes": 45 } }
] } }
ages: true— each ISO-8601 time with an offset orZin the shown excerpt gets its age relative to the card timetally: [...](1–6 words, 30 chars each) — counts lines containing each word across the whole selected range, including lines cut by the budget, so "3 waiting" stays true when only one is shownneed: { rows?, items?, chars? }— what the shown excerpt must contain to count as enough:rows= table data rows (header, separator and fenced lines excluded — a header-only table is 0),items= words that must appear verbatim,chars= a minimum body share taken from other sources inside the same total budget. Withrows/itemsdeclared the header saysneed met, or⚠ INSUFFICIENT — … — read <path:lines> directlywith the omitted amount. Undeclared = no verdicthealth: { maxAgeMinutes }— the source is a run-state JSON written by your own runner or supervisor; passbaton only shows it (it does not count logs or interpret words). Shape:observed_at(required, ISO with offset),state(required, producer's word),attention,normal_stop(booleans),last_attempt,last_success(ISO),failure {count, first, last, text}. Card lines:run health: …·⚠ RUN NEEDS ATTENTION — …·stopped normally·⚠ RUN HEALTH STALE(older thanmaxAgeMinutes) ·⚠ RUN HEALTH UNKNOWN(missing, broken, clock going backwards, or contradictory)
Stop summary picks the explicit status first (v2.10.0+)
The saved summary of a turn now prefers an explicit status / next step / blocker line. A heading-only line ("Review results") or a mid-sentence fragment is never used as the state, and the row records where the summary came from.