Skip to main content
Glama

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.md across Claude Code, Cursor, Codex CLI, Gemini CLI, Windsurf, Antigravity IDE, and Web AI in 3 seconds — with 0 npm dependencies and 0 network 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 setup

2. 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 mcp

Add 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

  1. Review your work (01 · Source conversation): Select the active project and source conversation, and inspect or edit the extracted handoff goal.

  2. 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, or Prepare handoff only).

  3. Review and hand off (03 · Review handoff): Inspect the exact .vicem/BATON.md summary before anything is written or launched. If automatic launch is unavailable, copy the saved BATON.md path, 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 Goal, Done, Failed Attempts, Immediate NEXT & git diff into .vicem/BATON.md

< 3s handoff across 12+ CLI, IDE & Web AI agents

2. Side-Effect AST Skeletonizer

Full source files with unchanged function bodies (~59,100 tok)

Signatures + [pure] / [effects: ...] tags + 1-hop call graph; bodies in .vicem/ledger.json

90–98% cache hit rate, -84% to -92% net tokens (eval)

3. Test & Log Slimmer

Verbose ANSI spinners & node_modules stack frames (~45,000 tok)

Failing assertion + top 5 user-code stack frames (~1,200 tok)

-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 .env keys, skeleton stub writes, or indirect prompt-injection in logs

Regex + Shannon-entropy secret scrubbing, BatonInjectionGuard (Unicode Trojan / fence-escape / hijack defanging) & SkeletonWriteGuard

4-layer defense & 0 npm dependencies

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 (o200k_base)

Reduction

Reversible Bodies (rehydrate)

Secret / Injection Defense

Vicem v1.3.0 (diet — Task Baton + Hot-Expand)

0.47 MB (0)

133 ms

55 MB

1,051 tok

-98.8%

Yes (active fn inline, 0 RPC)

Redacted / Defanged

Vicem v1.3.0 (vicem map — Whole-Repo Map)

0.47 MB (0)

161 ms

77 MB

8,678 tok

-90.1%

Yes (221 symbols via MCP)

Redacted / Defanged

Vicem v1.3.0 (--compact-all Full Baton)

0.47 MB (0)

219 ms

77 MB

9,721 tok

-88.9%

Yes (221 symbols via MCP)

Redacted / Defanged

Tree-sitter WASM Repo Packer (--compress, Full)

~102 MB (84)

333 ms

208 MB

18,587 tok

-78.7%

No (one-way deletion)

Secrets only / Injection leaked

Tree-sitter WASM Repo Packer (--compress, Code-Only)

~102 MB (84)

331 ms

207 MB

9,844 tok

-86.1%*

No (one-way deletion)

Secrets only / Injection leaked

Standard XML Repo Packer (Default)

~102 MB (84)

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 bench
git 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.mjs

Reviewed 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 tools
vicem_check_guardA
Read-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_batonA
Idempotent

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_batonA
Read-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_rehydrateA
Read-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

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Local-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.
      15
      241 npm
      9
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      3
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 PyPI
      322
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -