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 old claude-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 + auto-injects error solutions
# 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:

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:

Use search when you want to look something up. Use this when you want your context to follow you without asking.

Codex CLI support (v1.16.0+)

Beyond Claude Code, this also supports OpenAI Codex CLI. If ~/.codex exists, the installer registers the same hooks in ~/.codex/hooks.json (SessionStart, UserPromptSubmit, PreCompact, Stop), and the hooks auto-detect the host and emit the right output format (Codex's hookSpecificOutput.additionalContext).

The same local sessions.db is shared, so context carries across both agents: what you did in Codex is available in Claude Code and vice versa.

Scope: session save + context injection work on both. Codex file-change tracking (PostToolUse) isn't wired yet — session save already covers most of it via transcript parsing. Codex's transcript_path is treated as an unstable interface (it can be null at startup), so host detection uses an installer-injected --codex marker rather than relying on the path.

Gemini CLI support (v1.17.0+)

Also supports Google Gemini CLI. If ~/.gemini exists, the installer registers the hooks in ~/.gemini/settings.json (SessionStart, BeforeAgent, PreCompress, SessionEnd — Gemini's event names), preserving your other settings. Same shared local sessions.db, so context carries across all three agents.

Gemini's transcript format was verified against real ~/.gemini/tmp/.../chats/*.jsonl files — it uses two shapes (a flat {type, content} line and an older {"$set":{"messages":[…]}} diff line); the parser handles both. Like Codex, transcript_path can be null at startup, so host detection uses a --gemini marker.

Honest scope note: session save (SessionEnd) and context output are verified working. Gemini's SessionStart context injection is documented as advisory-only upstream (gemini-cli#15413) — if your Gemini build doesn't render the injected context on startup, that's an upstream limit, not this tool. Session continuity still works via the saved history.

Migrating from v1

If you installed this as claude-session-continuity-mcp (v1.x), nothing breaks — the v1 claude-hook-* commands still ship as aliases in v2.

To move to the new name:

npm install -g passbaton          # installs the new package
npm uninstall -g claude-session-continuity-mcp   # optional: drop the old one

The installer rewrites your hook entries to passbaton-hook-* and removes the old claude-hook-* lines — it matches on both names, so you won't end up with duplicates. Your existing sessions.db is untouched: all past sessions, memories, and solutions carry over.

Nothing else changes — same hooks, same database, same behavior.

Quick Start

Requires Node.js 22+. The native better-sqlite3 dependency only ships prebuilt binaries for Node 22, 24, and 26 (the currently supported lines — Node 18 and 20 are both end-of-life). On older Node it falls back to compiling from source, which fails without build tools. Node 22 and up install cleanly with no compiler needed.

Recommended: Global Installation

npm install -g passbaton

That's it! The postinstall script automatically:

1. Registers MCP server in ~/.claude.json
2. Installs Claude Hooks in ~/.claude/settings.json

Why Global (-g)?

This tool is designed to track all your Claude Code projects in a single unified database. Global installation is strongly recommended because:

Add the database to your project's .gitignore. Since 2.4.0 passbaton creates <project>/.claude/sessions.db on the first session in any project it recognises as a workspace root, so a project that had no database before will get one:

.claude/sessions.db
.claude/sessions.db-shm
.claude/sessions.db-wal
.claude/*.log

Do not ignore all of .claude/ — settings.json there is meant to be committed.

Important: Even with global install, you can still disable the hook for specific projects (see below). Global ≠ forced on every project.

Disabling Hooks for Specific Projects

Global install does not mean "always on everywhere". You have three layers of control: