DEV Community

Cover image for Vicem v1.3.0: Reversible Repo Maps, AST Side-Effect Tags, and Honest Net-Token Benchmarks (0 Dependencies)
Im Woojin
Im Woojin

Posted on

Vicem v1.3.0: Reversible Repo Maps, AST Side-Effect Tags, and Honest Net-Token Benchmarks (0 Dependencies)

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:

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

GitHub logo 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 Logo

Vicem — Diet the Context, Pass the Baton

Reviewed by HOL Guard Vicem MCP server rated A on Glama Listed on MCP.so Listed on mcpservers.org npm vicem-cli Release v1.3.0 Zero Dependencies MIT License

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.

Vicem 15s Relay Promo — Diet the Context, Pass the Baton (Click for 1080p60 with sound)
🎬 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] */ }
Enter fullscreen mode Exit fullscreen mode

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_rehydrate MCP 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 both BATON.md AND every vicem_rehydrate JSON-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
Enter fullscreen mode Exit fullscreen mode

4. Defanging Prompt Injections & Protecting Invariants

Three more additions in v1.3.0 came directly from real-world handoff failures:

  1. 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.
  2. vicem map & --compact-all: Generates a reversible whole-repo skeleton map (8,678 tokens from 87,460) with every body indexed in .vicem/ledger.json.
  3. 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.

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
Enter fullscreen mode Exit fullscreen mode

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)