passbaton MCP server
2026년 11월 7일 커밋새로운 세션에 프로젝트 컨텍스트와 최근 이력을 자동으로 주입하여 AI 코딩 에이전트의 지속적인 세션 연속성을 제공합니다.
다른 이름 leesgit/passbaton
- 스타
- 7
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 7일
- 라이선스
- MIT
passbaton MCP란?
passbaton은(는) MCP server입니다. 새로운 세션에 프로젝트 컨텍스트와 최근 이력을 자동으로 주입하여 AI 코딩 에이전트의 지속적인 세션 연속성을 제공합니다.
프로젝트 README에서 생성된 요약
passbaton MCP server 정보
passbaton은 프로젝트 컨텍스트와 최근 이력을 자동으로 관리하여 AI 코딩 에이전트에게 지속적인 세션 연속성을 제공합니다. Claude Code, OpenAI Codex CLI 또는 Google Gemini CLI를 사용하는 개발자를 위해 설계되었습니다. 이 시스템은 SQLite 데이터베이스를 사용하여 로컬에서 작동하므로, API 비용이 발생하거나 외부 클라우드 서비스를 사용할 필요 없이 모든 데이터가 사용자의 기기에 안전하게 보관됩니다.
새 세션을 시작할 때마다 프로젝트 아키텍처나 최근 결정 사항을 수동으로 설명할 필요 없이, 이 도구는 라이프사이클 훅을 사용하여 관련 메모리, 최근 작업 내용, 에러-해결 쌍을 자동으로 주입합니다. 시맨틱 검색을 지원하며 컨텍스트 압축 기능을 통해 긴 대화 후에도 에이전트가 현재 작업을 명확하게 이해할 수 있도록 돕습니다. 또한 개발자는 HANDOFF.md 또는 플랜 파일과 같은 특정 프로젝트 파일을 세션 시작 시퀀스의 일부로 읽도록 설정할 수 있습니다.
활용 사례
- 1코딩 작업 재개이전 세션의 상태와 최근 커밋을 자동으로 로드하여 에이전트가 특정 기능에 대한 작업을 계속하도록 요청합니다.
- 2이전 에러로부터 복구과거의 에러 이력과 그에 따른 해결 방법을 에이전트에게 제공하여 동일한 실수를 반복하는 것을 방지합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
MCP_HOOKS_DISABLED
| 이름 | 설명 | 유형 |
|---|---|---|
| MCP_HOOKS_DISABLED | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능leesgit/passbaton is public and reachablegithub.com/leesgit/passbaton ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스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
GitHub에서 보기passbaton
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.