Six days ago, I shipped Vicem v1.2.0 to solve session handoff amnesia across Claude Code, Codex, and Cursor. Since then, the toughest engineering pushback I got came down to two questions:
-
The Raw Dump vs. One-Way Compression Trap: Existing repo packers either dump 80k tokens of XML/Markdown, or strip function bodies with Tree-sitter WASM (
~100 MB, 80+ npm dependencies) with no way for the agent to restore a body when it actually needs to edit it. - Net Token Math & Untrusted Input: What is the net token savings after the agent pays for MCP tool calls to fetch missing bodies—and what happens if a malicious comment or test log inside the repo tries to prompt-inject your next agent?
Today (Nov 13), I shipped Vicem v1.3.0 (npm i -g vicem-cli or npx vicem-cli)—still 0 npm dependencies, 0 network calls, and 0.47 MB unpacked—built to answer both with reproducible numbers.
RAKKUNN
/
vicem
Zero-dependency AI agent context baton & diet suite. Hand off sessions between Claude Code, Codex, Gemini, and Cursor with 80% fewer tokens.
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.
🎬 15s Relay Overview — Watch in 1080p60 with sound (MP4) · All Links & Quick Copy
⚡ 10-Second Quick Start (npx — Zero Install)
1. Run the Local Handoff GUI or
…
1. Deterministic AST Side-Effect Tags ([pure] vs [effects: ...])
When an agent reads a skeletonized file, seeing only the function signature isn't always enough. If you're debugging a race condition or auditing security boundaries, you need to know which elided functions touch the filesystem, network, or subprocesses—without rehydrating every single one.
Vicem v1.3.0 runs a zero-dependency static analyzer over JS/TS and Python ASTs and annotates every skeletonized symbol with deterministic purity tags and 1-hop intra-file propagation:
// 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] */ }
In our security audit benchmark (S3-Audit, inspecting 10 functions across TypeScript and Python for fs-write and proc effects):
-
v1.2.0 (blind inspection): Required 10
vicem_rehydrateMCP calls. -
v1.3.0 (effect-guided + 1-hop propagation): Required 4 calls (-60% fewer MCP tool calls), skipping
[pure]and read-only helpers while still flagging callers that transitively invoke side-effecting callees.
2. Measuring Honest Net Token Savings (Including MCP Rehydration Costs)
Initial compression numbers are easy to game if you ignore what happens after the handoff.
Vicem v1.3.0 instruments .vicem/metrics.json (vicem stats / vicem://metrics/cache) with CPU-cache-style telemetry:
-
Symbol Cache Hit Rate (
CHR_symbol): % of skeletonized functions whose L1 signature +[pure]/[effects]tag + 1-hop call graph satisfied the task without fetching the body. -
Net Effective Token Reduction (
NTR): End-to-end token savings after charging bothBATON.mdAND everyvicem_rehydrateJSON-RPC response.
Standard Handoff Scenarios (125-symbol polyglot JS/TS/Python corpus)
| Scenario | Raw Context | Baton + All Rehydrate RPCs | Rehydrated Symbols | Skeleton Cache Hit Rate | Net Effective Savings (NTR) | Avg RPC Latency |
|---|---|---|---|---|---|---|
S0-HotFix (Active diff/error auto-expanded) |
66.3k | 5.0k | 0 / 124 (0 RPCs) | 100% | -92.4% | 0 ms |
S1-Bugfix (Targeted 2-symbol fix) |
66.2k | 5.3k | 2 / 125 (2 RPCs) | 98.4% | -92.1% | 15.32 ms |
S2-Refactor (5 roots + 1-hop callees) |
66.2k | 9.9k | 11 / 125 (5 RPCs) | 91.2% | -85.0% | 31.55 ms |
S3-Audit (Effect-guided security audit) |
66.2k | 5.4k | 4 / 125 (4 RPCs) | 96.8% | -91.9% | 10.9 ms |
The Honest Break-Even Curve (S4-Stress)
Skeletonization isn't magic—if an agent rehydrates everything, MCP round-trips add overhead. Here is the exact break-even curve from npm run bench:
| % of Codebase Rehydrated | Symbol Cache Hit Rate | Net Effective Savings (NTR) | Recommended Strategy |
|---|---|---|---|
| 10% (13 / 125 syms) | 89.6% | -87.0% | Use Skeleton + Rehydrate |
| 30% (38 / 125 syms) | 69.6% | -52.6% | Use Skeleton + Rehydrate |
| 50% (57 / 125 syms) | 54.4% | -22.2% | Use Skeleton + Rehydrate |
| 80% (87 / 125 syms) | 30.4% | +28.4% (Overhead) | Read Raw File Directly |
| 100% (111 / 125 syms) | 11.2% | +56.2% (Overhead) | Read Raw File Directly |
Takeaway: Break-even sits at ~65% of skeletonized symbols. For targeted bugfixes, reviews, and multi-agent handoffs (typically 1–30% edits), net savings stay between -52% and -92%.
3. Architectural Benchmark vs. Existing Repo Packers
To see where Vicem stands against common repo-packing architectures, I ran a head-to-head local benchmark on an Apple M2 Pro (darwin-arm64, Node v25.9.0, /usr/bin/time -l median of 5 runs, OpenAI o200k_base BPE tokenizer) against an 87,460-token polyglot JS/TS/Python/JSON repo 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 |
On code-only files (70,682 raw tokens), vicem map produces **8,583 tok (-87.9%)* in 160 ms while keeping all 221 elided functions restorable on demand via vicem_rehydrate.
You can reproduce every number in this post locally with zero network access:
git clone https://github.com/RAKKUNN/vicem.git && cd vicem
npm run bench
4. Defanging Prompt Injections & Protecting Invariants
Three more additions in v1.3.0 came directly from real-world handoff failures:
-
BatonInjectionGuard: Harvested test logs, stack traces, and code comments are untrusted input. Vicem now detects and defangs Unicode Trojan bidirectional overrides, markdown fence-escape payloads, and instruction-hijack strings before writing.vicem/BATON.md. -
vicem map&--compact-all: Generates a reversible whole-repo skeleton map (8,678tokens from87,460) with every body indexed in.vicem/ledger.json. -
vicem decide&vicem init --agent-hooks:- Pin architectural invariants (
vicem decide "Keep zero npm dependencies") so they never get compacted away across 5+ agent handoffs. - Install Claude Code lifecycle hooks (
vicem init --agent-hooks) to automate baton checkpoints around compaction and session boundaries.
- Pin architectural invariants (
Try It in 10 Seconds
# 1. Guided Handoff GUI (preview & edit before sending)
npx -y vicem-cli gui
# 2. Pack & hand off directly between CLI agents
npx -y vicem-cli codex
npx -y vicem-cli claude
npx -y vicem-cli cursor
# 3. Generate a reversible whole-repo map
npx -y vicem-cli map
# 4. Register as an MCP server (Claude Code / Codex)
claude mcp add vicem -- npx -y vicem-cli mcp
codex mcp add vicem -- npx -y vicem-cli mcp
- GitHub (MIT, 775/775 tests passing): https://github.com/RAKKUNN/vicem
-
npm:
vicem-cli@1.3.0/@rakkunn/vicem@1.3.0 - Zero-install browser sandbox: https://rakkunn.github.io/vicem/
If you test vicem map or npm run bench on your own codebase, drop your token reduction % and CHR numbers in the comments—I'd love to see how it holds up on larger monorepos!

Top comments (0)