vicem
This MCP server lets an AI agent create, inspect, restore from, and safety-check Vicem context handoff batons.
Create a context baton: compress the current coding session/git state into
.vicem/BATON.mdand.vicem/ledger.json, with optional goal override, persisted decisions, target agent formatting, token budget, and whole-repo compaction.Read an existing baton: inspect the handoff goal, next steps, and diet ledger, and get a staleness warning if git HEAD has drifted since the baton was created.
Rehydrate skeletonized symbols: restore exact, secret-redacted source for functions/classes elided into the ledger, optionally including 1-hop callees, with drift warnings.
Check safety guards: validate a diff or code snippet against skeleton-write placeholders, leaked secrets/credentials, and baton staleness, returning remediation prompts when violations are found.
Relays the coding session and BATON to OpenAI Codex CLI and supports registering the Vicem MCP server with Codex for context handoff and rehydration.
Vicem — Diet the Context, Pass the Baton
Hit Claude Code's 5-hour quota mid-feature? Or watching Cursor / Codex slow to a crawl after 150k tokens of context rot?
Vicem compacts your active coding session by 80–92% net effective tokens (Measured Eval — via deterministic AST code skeletonization with
[pure]/[effects: ...]tags + SHA-256-checked, secret-redacted MCP rehydration) and hands off a hardened.vicem/BATON.mdacross Claude Code, Cursor, Codex CLI, Gemini CLI, Windsurf, Antigravity IDE, and Web AI in 3 seconds — with0npm dependencies and0network calls.⭐ Tip: Click Star (top-right) to bookmark this repo for the next time your coding agent hits a 5-hour quota limit or context rot.
⚡ 10-Second Quick Start (npx — Zero Install)
1. Run the Local Handoff GUI or Pass a Baton Immediately
# Launch the local Handoff GUI (3-step guided handoff, preview confirmation & manual recovery)
npx -y vicem-cli gui
# Or pack a compressed baton from your current repo & hand off in 1 command
npx -y vicem-cli codex
npx -y vicem-cli claude
npx -y vicem-cli cursor
# Or auto-configure global `vicem` CLI + MCP servers across all installed agents
npx -y vicem-cli setup2. Add as an Agent Skill & MCP Server in 1 Line (Claude Code / Codex / Cursor)
# Install the Agent Skill globally (Claude Code, Cursor, Codex, Antigravity, Windsurf)
npx skills add RAKKUNN/vicem -g
# Claude Code MCP Server
claude mcp add vicem -- npx -y vicem-cli mcp
# OpenAI Codex CLI MCP Server
codex mcp add vicem -- npx -y vicem-cli mcpAdd to ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, or claude_desktop_config.json:
{
"mcpServers": {
"vicem": {
"command": "npx",
"args": ["-y", "vicem-cli", "mcp"]
}
}
}Related MCP server: slimctx-token-optimizer
Visual Overview
Review your work (
01 · Source conversation): Select the active project and source conversation, and inspect or edit the extracted handoff goal.Choose a destination (
02 · Choose a destination): Pick the target agent (Claude Code,OpenAI Codex,Cursor,Antigravity,Gemini CLI,Windsurf,VS Code,Web Chat) and delivery action (Open the app,Open in terminal, orPrepare handoff only).Review and hand off (
03 · Review handoff): Inspect the exact.vicem/BATON.mdsummary before anything is written or launched. If automatic launch is unavailable, copy the savedBATON.mdpath, shell continuation command, and start prompt directly from the recovery panel.
$ npx -y vicem-cli codex
╭─ VICEM CONTEXT BATON & DIET RECEIPT ──────────────────────────────────╮
│ Source Session : Claude Code (sess-9f3a2c · 42 turns harvested) │
│ Context Diet : 184,200 tok ($2.76) ──► 14,800 tok ($0.22) [-91.9%] │
│ Code Skeletons : 18 files compressed (31 bodies indexed in ledger) │
│ Security Guard : 2 secrets redacted (OPENAI_KEY, AWS_ACCESS_KEY) │
│ Relay Target : OpenAI Codex CLI (interactive TTY handoff ready) │
╰───────────────────────────────────────────────────────────────────────╯
[OK] [Vicem] Baton written to .vicem/BATON.md (182ms). Launching codex...How Side-Effect-Tagged AST Skeletonization + MCP Rehydration Works
Instead of lossy LLM summarization that forgets exact type contracts or hides side effects, Vicem keeps all imports, types, and signatures intact inside .vicem/BATON.md, annotates every elided body with deterministic AST purity & side-effect tags ([pure] vs [effects: fs-write, proc, net, state, fs-read, throws, async] with 1-hop intra-file propagation), and indexes raw bodies in .vicem/ledger.json:
// What the receiving agent sees in .vicem/BATON.md (disk file untouched):
export interface JwtPayload { sub: string; exp: number; role: 'admin' | 'user'; }
export function normalizeBearerHeader(rawHeader: string): string { /* ... [pure] */ }
export async function verifySessionToken(rawToken: string, secret: string): Promise<JwtPayload> { /* ... [effects: fs-read, throws, async] */ }When the receiving agent actually needs to edit verifySessionToken, it calls the MCP tool vicem_rehydrate("src/auth.ts", "verifySessionToken") (optionally with include_callees: true) for SHA-256-checked, secret-redacted AST rehydration on demand — while .vicem/metrics.json (vicem stats) tracks your live Skeleton Cache Hit Rate (CHR) and Net Token Reduction (NTR) (see full benchmark & break-even curve).
Pipeline Stage | Before Vicem (Raw Session) | After Vicem Baton & Diet (v1.3.0) | Measured Impact |
1. Session Handoff | 40+ turns of raw JSONL / SQLite history locked in one tool | Extracts | < 3s handoff across 12+ CLI, IDE & Web AI agents |
2. Side-Effect AST Skeletonizer | Full source files with unchanged function bodies ( | Signatures + | 90–98% cache hit rate, -84% to -92% net tokens (eval) |
3. Test & Log Slimmer | Verbose ANSI spinners & | Failing assertion + top 5 user-code stack frames ( | -95% log noise |
4. Data & Noise Gate | Lockfiles, build bundles, and huge JSON / CSV / SQL dumps | Lockfiles dropped; data files reduced to inferred schema + 2 sample rows | -98% data bloat |
5. 4-Pillar Safety & Injection Guard | Plaintext | Regex + Shannon-entropy secret scrubbing, | 4-layer defense & |
Architectural Benchmark vs. Existing Context Packers
Measured on Apple M2 Pro (darwin-arm64, Node v25.9.0, /usr/bin/time -l median of 5 runs, OpenAI o200k_base BPE tokenizer) on a polyglot JS/TS/Python/JSON repository (87,460 total tokens / 70,682 code-only tokens, containing an inline test secret and an untrusted prompt-injection comment):
Tool / Architecture Category | Install Footprint (Deps) | Median Time | Peak RSS | Output ( | Reduction | Reversible Bodies ( | Secret / Injection Defense |
Vicem v1.3.0 ( | 0.47 MB ( | 133 ms | 55 MB | 1,051 tok | -98.8% | Yes (active fn inline, 0 RPC) | Redacted / Defanged |
Vicem v1.3.0 ( | 0.47 MB ( | 161 ms | 77 MB | 8,678 tok | -90.1% | Yes (221 symbols via MCP) | Redacted / Defanged |
Vicem v1.3.0 ( | 0.47 MB ( | 219 ms | 77 MB | 9,721 tok | -88.9% | Yes (221 symbols via MCP) | Redacted / Defanged |
Tree-sitter WASM Repo Packer ( | ~102 MB ( | 333 ms | 208 MB | 18,587 tok | -78.7% | No (one-way deletion) | Secrets only / Injection leaked |
Tree-sitter WASM Repo Packer ( | ~102 MB ( | 331 ms | 207 MB | 9,844 tok | -86.1%* | No (one-way deletion) | Secrets only / Injection leaked |
Standard XML Repo Packer (Default) | ~102 MB ( | 274 ms | 164 MB | 79,934 tok | -8.6% | Full raw dump | Leaked / Leaked |
Python Repo Ingestor | ~25 MB | 419 ms | 145 MB | 79,650 tok | -8.9% | Full raw dump | Leaked / Leaked |
Raw File Concatenator | ~0.2 MB | 36 ms | 18 MB | 87,537 tok | 0% | Full raw dump | Leaked / Leaked |
*Code-only comparison (70,682 raw code tokens, excluding JSON fixtures): vicem map produces 8,583 tok (-87.9%) in 160 ms while keeping all 221 elided functions restorable on demand via vicem_rehydrate. See docs/BENCHMARK.md for the reproducible CHR/NTR evaluation and break-even curve.
Direct CLI Commands & Offline Source Setup
# 1. Launch the interactive Desktop Utility GUI
vicem gui
# 2. Compact current bloated session in-place (Context Rot Rescue)
vicem self
# 3. Pass baton to any CLI, IDE, or Web AI target
vicem codex | vicem claude | vicem gemini | vicem cursor | vicem windsurf | vicem vscode | vicem web
# 4. Return baton to previous agent & auto-unmount temporary rules
vicem back
# 5. Extract & smart-patch code blocks from a Web AI clipboard reply
vicem land
# 6. Build reversible whole-repo map, pin architectural decisions & install Claude lifecycle hooks
vicem map
vicem decide "Keep zero npm dependencies and preserve backward-compatible API"
vicem init --agent-hooks
# 7. Inspect Skeleton Cache Hit Rate (CHR), Net Token Savings (NTR) & run diagnostics
vicem stats
vicem doctor
npm run benchgit clone https://github.com/RAKKUNN/vicem.git && cd vicem
./vicem.mjs setup # or double-click setup.command (macOS/Linux) / setup.bat (Windows)For browser-only air-gapped environments without Node.js, open index.html directly in Chrome, Edge, Brave, or Safari (enforced by connect-src 'none' CSP).
Supply-Chain Verification & Minimal TCB
Verify zero third-party dependencies and cryptographic artifact integrity in one command:
# 1. Confirm zero npm dependencies
node -e "console.log(JSON.parse(fs.readFileSync('package.json')).dependencies ?? '0 dependencies')"
# 2. Verify SHA-256 checksums of all core artifacts
shasum -a 256 -c SHA256SUMS
# 3. Run the 775-test automated suite
node --test test/*.test.mjsReviewed handoffs and safe recovery
Start the local interface with node vicem.mjs gui. Select the project and source conversation, edit the goal, choose the destination and launch mode, then review before delivery. Technical telemetry is available under details.
node vicem.mjs codex --preview: preview without saving handoff artifacts or launching an app.node vicem.mjs codex --preview --json: structured preview for automation.node vicem.mjs status --json/node vicem.mjs history --json: inspect recorded outcomes.node vicem.mjs undo <handoff-id>: restore instruction changes for that handoff only. If those instructions have since changed, recovery refuses to overwrite them. This does not undo agent edits to source code.
The GUI rejects a reviewed handoff if its content changes before delivery. Delivery and application launch do not establish that an agent has read the context: reception remains unconfirmed. The preview token is a consistency check, not authentication. Legacy --dry-run still writes handoff artifacts; use --preview for a read-only preview.
Validation: automated unit/integration tests and local macOS browser checks. Windows/Linux real-agent launch and actual target-agent reception are not certified by these tests. GUI and CLI share preparation, rule mounting, outcome history and instruction recovery; platform launch adapters remain distinct.
See compatibility verification for tested operating systems, actual agent read proofs, and limitations.
Automatic launch and manual continuation
Windows CLI/package behavior is verified in native CI on Node 22 and 24. Windows desktop integration remains Preview; desktop auto-launch on every OS is best effort. View the passing CI run and the precise support scope.
If automatic launch fails, the handoff stays saved. The GUI provides Copy command, Copy start prompt, and the saved file path. Open the destination manually, select your project, and paste the start prompt. CLI failures provide the same guide. Successful delivery does not confirm that an agent read it.
Available Tools
4 toolsvicem_check_guardARead-onlyIdempotent
Verifies a code snippet or git diff against three safety checks: (1) SkeletonWriteGuard (blocks "{ ... }", "/* ... */", "⋮", or stub "pass" placeholders written into code files), (2) SecretCommitGuard (blocks raw API keys/credentials, leaked "‹REDACTED:...›" tokens, and baton markers), and (3) StalenessDriftGuard (flags git HEAD drift from .vicem/baton.json). Use before committing or finalizing edits to skeletonized files; do not use to read baton state (vicem_read_baton) or restore elided code (vicem_rehydrate). Parameter semantics: pass diff_text to inspect a specific unified diff or code snippet; omitting diff_text falls back to inspecting staged and unstaged working tree changes (git diff HEAD). Non-mutating read-only check (no auth, rate limits, or file overwrites): returns "OK: All 3 Safety Guards passed." (isError=false) when clean, or isError=true with per-violation findings and self-healing remediation prompts when a guard trips.
Inputs: diff_text.
vicem_create_batonAIdempotent
Creates a compressed U-Shaped Context Baton (.vicem/BATON.md) and symbol ledger (.vicem/ledger.json) from the current project session and git state. Use at session end or before quota limits to hand off work; do not use to read an existing baton (vicem_read_baton), restore a skeletonized function (vicem_rehydrate), or validate edits (vicem_check_guard). Compresses context by skeletonizing unchanged functions >=12 lines into .vicem/ledger.json while keeping signatures intact. Idempotently overwrites .vicem/BATON.md, .vicem/baton.json, and .vicem/ledger.json after saving a rollback snapshot in .vicem/snapshots/, with secret redaction and zero source file mutations (no auth or rate limits). Parameter semantics: goal overrides auto-extracted session intent in Section 1; targetAgent tailors receiver rules (default "codex"); budgetTokens (500-128000, default 4000) controls skeletonization depth. Returns the generated Markdown baton (isError=false).
Inputs: goal, decisions, compactAll, targetAgent, +1 more.
vicem_read_batonARead-onlyIdempotent
Reads the current .vicem/BATON.md handoff document and checks whether git HEAD has drifted from .vicem/baton.json. Use first when starting a handed-off session to inspect the goal, next steps, and Section 6 Diet Ledger index; do not use to create a baton (vicem_create_baton), restore an individual function body (vicem_rehydrate), or validate code diffs (vicem_check_guard). Read-only local operation (no auth, rate limits, or file mutations). Returns the full BATON.md text with isError=false; if git HEAD moved ahead of the baton commit, the call still succeeds and prepends a "> ⚠️ [STALENESS DRIFT WARNING]" banner with both commit hashes so you can check git diff before editing. Returns isError=true if .vicem/BATON.md does not exist.
Inputs: no named parameters.
vicem_rehydrateARead-onlyIdempotent
Restores the exact, secret-redacted source code of a skeletonized function, method, or class from .vicem/ledger.json so you never write { ... } placeholders. Use after vicem_read_baton whenever you need to inspect or edit a symbol listed in .vicem/BATON.md Section 6 (Diet Ledger); do not use to read the full baton (vicem_read_baton), build a baton (vicem_create_baton), or check diff safety (vicem_check_guard). Parameter semantics: file_path (repo-relative POSIX path validated against path traversal) and symbol_name must match a ledger entry (camelCase filePath/symbolName aliases also accepted). Read-only lookup (no auth, rate limits, or disk writes): returns the redacted source code (isError=false), prepending a "// ⚠️ [STALENESS DRIFT WARNING]" comment if git HEAD or the on-disk file changed since snapshot. If the symbol is missing or was not skeletonized, returns isError=true with a not-found message so you can read the file directly.
Inputs: file_path (required), symbol_name (required), include_callees.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: create a baton, read a baton, restore a skeletonized symbol, or validate safety guards. The descriptions explicitly cross-reference alternatives and state when not to use each tool, leaving no practical ambiguity.
All tool names use the same `vicem_` prefix followed by a snake_case verb_noun pattern: `create_baton`, `read_baton`, `rehydrate`, and `check_guard`. There are no deviations in casing or verb style.
Four tools tightly map to the handoff workflow: create, read, rehydrate, and guard. The set is small but each tool has a necessary, non-overlapping purpose for this focused protocol.
The core lifecycle is covered: creating and reading a baton, restoring skeletonized symbols, and validating edits before commit. Minor gaps exist around explicit snapshot restore/cleanup or standalone ledger inspection, though idempotent create and read_baton's Section 6 index largely mitigate them.
Maintenance
Related MCP Connectors
Compress coding-agent context ~64%. Hosted Neural Keep MCP for Cursor/Claude/Codex.
A paid remote MCP for OpenAI Codex context compressor, built to return verdicts, receipts, usage log
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal-first MCP server that watches your coding sessions and injects a compact summary at the start of each new session. 85.6% token reduction, SQLite storage, no cloud. Works with Claude Code, Cursor, Cline, and Windsurf.15241 npm9MIT
- AlicenseAqualityCmaintenanceProvides reversible context compression for AI agents, reducing token usage while preserving the ability to retrieve original content, and serves as an MCP server for integration with tools like GitHub Copilot and Claude Code.31Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA task-aware context compression layer for Agent workflows, RAG pipelines, and AI Coding assistants, reducing noisy logs, retrieval chunks, and code context into high-signal LLM inputs via CLI, Python SDK, and MCP.20 PyPI322MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents and MCP-compliant clients to dynamically shrink long-horizon context windows, pruning verbose tool outputs, HTML boilerplate, and semantic redundancy by roughly 40-70% without frontier LLM round-trips. Runs deterministically as a zero-dependency Python stdio server, accepting a payload plus optional compression and risk-bound options.7-