# vicem

Adopt this skill: https://proskills.md/skills/other/rakkunn-vicem-agents-skills-vicem

Page: https://proskills.md/skills/other/rakkunn-vicem-agents-skills-vicem
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/vicem/SKILL.md
size: 2804
sha: 678ed75bbd30b8caa45c2f1d49467e881b41b38f
upstream: https://github.com/rakkunn/vicem/blob/main/.agents/skills/vicem/SKILL.md

````text
---
name: vicem
description: Zero-dependency AI Agent Context Baton & Diet Suite. Use this skill when handing off coding tasks between AI agents (Claude Code, OpenAI Codex, Antigravity IDE, Cursor, VS Code, Gemini CLI, Web AI), compacting bloated sessions (Context Rot Rescue), or rehydrating skeletonized functions from .vicem/ledger.json.
---

# Vicem (`vicem.mjs`) — Universal Agent Baton & Diet Skill

Vicem packages the active project state, git diff, task progress, and compressed code skeletons into a bookended U-Shaped Attention Baton (`.vicem/BATON.md`), redacts secrets (`‹REDACTED:PROVIDER:HASH4›`), and hands off or compacts sessions in a single command.

## 1. Receiving a Baton (Mandatory Rules for Target Agents)

1. **Read `.vicem/BATON.md` First:**
   - **Zone 1 (Top Primacy Zone):** Read `## 1. Goal` and `## 2. Immediate NEXT` first.
   - **Zone 2 (Middle Evidence Zone):** Review `## 3. Done`, `## 4. Work Evidence (Git Diff & Slimmed Logs)`, and `## 5. Architectural Context (Code Skeletons)`.
   - **Zone 3 (Bottom Recency Anchor):** Begin immediately from **Immediate NEXT #1**.
2. **NEVER Write Skeleton Placeholders to Disk (`SkeletonWriteGuard`):**
   - Functions `>= 12` lines in Section 5 have their bodies replaced with `/* ... */` or `pass` to save tokens.
   - **Strictly Forbidden:** Never write `{ ... }`, `/* ... */`, `⋮`, or `‹REDACTED:...›` tokens into real source files.
   - **How to Rehydrate:** Call MCP tool `vicem_rehydrate(file_path, symbol_name)` (or read the original file directly) before modifying a skeletonized function.

## 2. Daily Zero-Flag Commands

```bash
# Auto-detect active session and pass baton to recommended target
node vicem.mjs

# Hand off to a specific CLI, IDE, or Web AI target
node vicem.mjs codex
node vicem.mjs claude
node vicem.mjs ide
node vicem.mjs web

# Compact current bloated session (Context Rot Rescue)
node vicem.mjs self

# Return baton to previous agent & auto-unmount temporary rule files
node vicem.mjs back

# Restore pre-handoff file snapshot or roll back session
node vicem.mjs rollback

# Install idempotent Git pre-commit safety guard hook
node vicem.mjs init

# Run <50ms zero-spawn environment & agent storage diagnostics
node vicem.mjs doctor

# Apply Web AI clipboard reply safely (2-Phase Guard + SmartPatchApplier)
node vicem.mjs land
```

## 3. MCP Tools Provided (`node vicem.mjs mcp`)

- `vicem_create_baton`: Build `.vicem/BATON.md` with 4-stage Context Diet and 3-tier Secret Redaction.
- `vicem_read_baton`: Read `.vicem/BATON.md` and check `StalenessDriftGuard` (`git HEAD` drift).
- `vicem_rehydrate(file_path, symbol_name)`: Retrieve omitted raw function/method bodies from `.vicem/ledger.json`.
- `vicem_check_guard`: Verify diffs against `SkeletonWriteGuard` and `SecretCommitGuard`.
````

## File: README.md
upstream: https://github.com/rakkunn/vicem/blob/main/README.md

````text
<p align="left">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./logo-dark-transparent.png" />
    <source media="(prefers-color-scheme: light)" srcset="./logo-light-transparent.png" />
    <img src="./logo.png" width="88" height="88" alt="Vicem Logo" />
  </picture>
</p>

# Vicem — Diet the Context, Pass the Baton

<p align="left">
  <a href="https://hol.org/guard/extensions/mcp.vicem"><img src="https://img.shields.io/badge/HOL_Guard%20|%20Vicem_Context_Baton_MCP-2E5AAC?logo=shield&logoColor=white" alt="Reviewed by HOL Guard" /></a>
  <a href="https://glama.ai/mcp/servers/RAKKUNN/vicem"><img src="https://glama.ai/mcp/servers/RAKKUNN/vicem/badges/score.svg" alt="Vicem MCP server rated A on Glama" /></a>
  <a href="https://mcp.so/servers/vicem"><img src="https://img.shields.io/badge/MCP.so-Listed-0F172A?logo=modelcontextprotocol&logoColor=white" alt="Listed on MCP.so" /></a>
  <a href="https://mcpservers.org/servers/rakkunn/vicem"><img src="https://mcpservers.org/badge.svg" alt="Listed on mcpservers.org" /></a>
  <a href="https://www.npmjs.com/package/vicem-cli"><img src="https://img.shields.io/npm/v/vicem-cli?color=CB3837&label=npm%20(vicem-cli)" alt="npm vicem-cli" /></a>
  <a href="https://github.com/RAKKUNN/vicem/releases/tag/v1.3.0"><img src="https://img.shields.io/badge/release-v1.3.0-10B981" alt="Release v1.3.0" /></a>
  <img src="https://img.shields.io/badge/dependencies-0-3B82F6" alt="Zero Dependencies" />
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-F59E0B" alt="MIT License" /></a>
</p>

> **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](./docs/BENCHMARK.md) — 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.

<p align="center">
  <a href="https://rakkunn.github.io/vicem/promo.mp4">
    <img src="./promo.gif" width="100%" alt="Vicem 15s Relay Promo — Diet the Context, Pass the Baton (Click for 1080p60 with sound)" />
  </a>
  <br />
  <sub>🎬 <strong>15s Relay Overview</strong> — <a href="https://rakkunn.github.io/vicem/promo.mp4">Watch in 1080p60 with sound (MP4)</a> · <a href="https://rakkunn.github.io/vicem/links.html">All Links &amp; Quick Copy</a></sub>
</p>

---

## ⚡ 10-Second Quick Start (`npx` — Zero Install)

### 1. Run the Local Handoff GUI or Pass a Baton Immediately
```bash
# 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)
```bash
# 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
```

<details>
<summary><strong>Cursor / Windsurf / Claude Desktop (<code>mcp.json</code> config)</strong></summary>

Add to `~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vicem": {
      "command": "npx",
      "args": ["-y", "vicem-cli", "mcp"]
    }
  }
}
```
</details>

<p align="left">
  <a href="https://rakkunn.github.io/vicem/"><strong>🌐 Try Zero-Install Browser Sandbox (GitHub Pages)</strong></a> ·
  <a href="https://www.npmjs.com/package/vicem-cli"><strong>📦 npm (vicem-cli / @rakkunn/vicem)</strong></a> ·
  <a href="./docs/BENCHMARK.md"><strong>📊 Cache Hit Rate &amp; Break-Even Eval</strong></a> ·
  <a href="./SECURITY.md"><strong>🔒 Security &amp; Zero-Network Proof</strong></a>
</p>

---

## Visual Overview

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./gui-dark.png" />
    <source media="(prefers-color-scheme: light)" srcset="./gui-light.png" />
    <img src="./gui-dark.png" width="100%" alt="Vicem Guided Handoff GUI (Dark & Light Mode)" />
  </picture>
</p>

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.

```text
$ 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`:

```ts
// 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](./docs/BENCHMARK.md)).

| 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/
````
