@rakkunn/vicem 0.0.0-stage → 1.1.0

package/.agents/skills/vicem/SKILL.md

@@ -0,0 +1,57 @@
+---
+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`.

package/AGENTS.snippet.md

@@ -0,0 +1,7 @@
+<!-- VICEM-AGENTS-SNIPPET -->
+## Vicem Baton & Context Diet Protocol
+
+- If `.vicem/BATON.md` exists in the workspace, read it before starting work and execute **Section 2 (`Immediate NEXT #1`)**.
+- **Safety Rule (`SkeletonWriteGuard`):** Code blocks in `.vicem/BATON.md` may contain skeletonized function bodies (`/* ... */` or `pass`) and redacted secrets (`‹REDACTED:PROVIDER:HASH4›`). **Never** write these placeholders into real source files.
+- If you need the full implementation of a skeletonized function, call the MCP tool `vicem_rehydrate(file_path, symbol_name)` or read the source file directly before editing.
+- Before finishing or handing back work, run `node vicem.mjs guard` to verify zero placeholder or redaction token leaks.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rakkunn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, following the conditions below:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+<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>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Vicem — Diet the Context, Pass the Baton
+
+<p align="left">
+  <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://github.com/RAKKUNN/vicem/releases/tag/v1.1.0"><img src="https://img.shields.io/badge/release-v1.1.0%20(Desktop%20GUI)-10B981" alt="Release v1.1.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's 5-hour quota limit mid-refactor? Or watching your AI agent lose its mind after 150k tokens of context rot?**
+>
+> **Hand off your exact coding session, git diff, and compressed code skeletons to Codex, Gemini, Cursor, Antigravity IDE, or Web AI in 3 seconds — with up to 90% fewer tokens and `0` third-party dependencies.**
+
+<p align="left">
+  <a href="https://rakkunn.github.io/vicem/"><strong>Launch Zero-Install Browser Studio (GitHub Pages)</strong></a> ·
+  <a href="https://github.com/Rakkunn/vicem"><strong>GitHub Repository</strong></a> ·
+  <a href="./SECURITY.md"><strong>Security &amp; Minimal TCB</strong></a>
+</p>
+
+<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 Unified Desktop Utility GUI (Dark & Light Mode)" />
+  </picture>
+</p>
+
+![Vicem 3-Second Context Baton & Diet Demo](./demo.gif)
+
+```text
+$ vicem 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...
+```
+
+---
+
+## Measured Pipeline Contribution (Before vs. After Vicem)
+
+| Pipeline Stage | Raw Session State (Before Vicem) | After Vicem Baton & Diet | Measured Contribution |
+| :--- | :--- | :--- | :--- |
+| **1. Session Continuity Relay** | 40+ turns of raw JSONL / SQLite history locked inside a single agent | Harvests active `Goal`, `Done`, `Immediate NEXT` & `git diff` into `.vicem/BATON.md` | **< 3s handoff** across 15+ CLI, IDE & Web AI agents |
+| **2. Code Skeletonization** | Full source files with long implementation bodies (`~120,000 tok`) | Types & signatures 100% intact; bodies `>= 12` lines indexed in `.vicem/ledger.json` | **-80% to -90% code tokens** (100% lossless via MCP `vicem_rehydrate`) |
+| **3. Test & Error Log Slimming** | Verbose ANSI spinners & `node_modules` stack frames (`~45,000 tok`) | Root failure message + top 5 project stack frames (`~1,200 tok`) | **-95% log noise** while preserving exact failure root cause |
+| **4. Data Sampling & Noise Gate** | Lockfiles, build bundles, and multi-megabyte JSON / CSV / SQL dumps | Artifacts filtered; data files reduced to inferred schema + 2 sample rows | **-98% data bloat** & zero context window overflow |
+| **5. Security & Write Integrity** | Plaintext credentials in logs & risk of placeholder overwrites | 3-Tier local secret redaction + `SkeletonWriteGuard` & `SecretCommitGuard` | **0 leaked secrets** & **0 external packages (`dependencies: 0`)** |
+
+---
+
+## 1-Click Setup (macOS, Windows, Linux — Zero Terminal Config Needed)
+
+### Option A: Double-Click Installer (Recommended)
+```bash
+git clone https://github.com/Rakkunn/vicem.git && cd vicem
+```
+1. **macOS / Linux:** Double-click **`setup.command`** (or run `./vicem.mjs setup`).
+2. **Windows:** Double-click **`setup.bat`**.
+3. **Browser-Only (Air-Gapped / No Node.js):** Open **[https://rakkunn.github.io/vicem/](https://rakkunn.github.io/vicem/)** or double-click **`index.html`** locally in Chrome, Edge, Brave, or Safari (`connect-src 'none'`).
+
+Wait 2 seconds — Vicem automatically registers the global `vicem` command, configures MCP servers across your installed agents (Claude Code, Codex, Cursor, Windsurf, Antigravity IDE), and installs the `.agents/skills/vicem/SKILL.md` skill.
+
+### Option B: Interactive Desktop Utility GUI & Direct CLI Usage
+Vicem consists of **standalone files** (`vicem.mjs`, `vicem-gui.mjs`, `index.html`, `.agents/skills/vicem/SKILL.md`) built entirely on Node.js standard library modules:
+
+```bash
+# 1. Launch the interactive Desktop Utility GUI (12 platforms, live quota telemetry, 1-click handoff)
+vicem gui
+
+# 2. One-click auto-setup (PATH + MCP registration + Git pre-commit guard)
+./vicem.mjs setup
+
+# 3. Auto-detect active session and pass baton to recommended target
+vicem
+
+# 4. Pass baton to a specific CLI, IDE, or Web AI target (12 platforms across macOS / Windows / Linux)
+vicem codex
+vicem claude
+vicem gemini
+vicem cursor
+vicem windsurf
+vicem vscode
+vicem cline
+vicem opencode
+vicem aider
+vicem goose
+vicem ide
+vicem web
+
+# 5. Compact current bloated session in-place (Context Rot Rescue)
+vicem self
+
+# 6. Return baton to previous agent & auto-unmount temporary rules
+vicem back
+
+# 7. Restore pre-handoff file snapshot or roll back session
+vicem rollback
+
+# 8. Open Hydrated Zero-Network Web Studio (.vicem/studio.live.html)
+vicem studio
+
+# 9. Extract & smart-patch code blocks from Web AI clipboard reply
+vicem land
+
+# 10. Run <50ms zero-spawn environment & agent storage diagnostics
+vicem doctor
+```
+
+---
+
+## Architecture & Core Capabilities
+
+1. **Zero-Config 1-Command Relay (`vicem codex`, `vicem claude`, `vicem ide`, `vicem web`):**
+   - Auto-detects the active source session strictly scoped to the current project directory (`cwd`), preventing cross-project session bleed.
+   - Length-adaptive fuzzy target matching (`vicem codexx` → `codex`, `vicem claud` → `claude`).
+   - Interactive CLI handoff preserves full TTY keyboard control (`stdio: 'inherit'`).
+2. **4-Stage Context Diet Engine (`-75%` to `-90%` Token Reduction):**
+   - **Stage 1 (Noise Gate):** Drops lockfiles, build artifacts, binaries, and minified bundles.
+   - **Stage 2 (Code Skeletonizer):** Preserves `interface`, `type`, `enum`, and class/method signatures 100% intact while replacing function bodies `>= 12` lines with `/* ... */` or `pass` (indexing full bodies in `.vicem/ledger.json` for on-demand MCP rehydration).
+   - **Stage 3 (Log Slimmer):** Strips ANSI codes, carriage-return spinners, and `node_modules`/`site-packages` frames while preserving the root error and 5 user stack frames.
+   - **Stage 4 (Data Sampler):** Compresses large JSON/CSV/SQL files into compact schemas + 2 sample rows.
+3. **Bookended U-Shaped Attention Baton IA (`.vicem/BATON.md`):**
+   - **Zone 1 (Top Primacy 15%):** `# BATON` header, `## 1. Goal`, and `## 2. Immediate NEXT`.
+   - **Zone 2 (Middle Evidence 75%):** `## 3. Done`, `## 4. Work Evidence (Git Diff & Slimmed Logs)`, `## 5. Architectural Context (Code Skeletons)`, and `## 6. Diet Ledger`.
+   - **Zone 3 (Bottom Recency 10%):** `EXECUTION ANCHOR` preventing placeholder writes and anchoring immediate execution.
+4. **3-Tier Secret Redactor & 3-Pillar Safety Guards:**
+   - Redacts AWS, GitHub, OpenAI, Anthropic, Google, Slack, Stripe, JWT, PEM private keys, and high-entropy assignments into `‹REDACTED:PROVIDER:HASH4›`.
+   - **Pre-Handoff Lossless Snapshot (`.vicem/snapshots/<batonId>/`):** Protects dirty working-tree files without ever running destructive `git checkout --`.
+   - **`SkeletonWriteGuard` & `SecretCommitGuard`:** Blocks agents from writing `{ ... }`, `/* ... */`, `‹REDACTED:...›`, or `<!-- VICEM-BATON-START -->` markers into source files.
+
+---
+
+## Manual MCP Server Registration (Optional)
+
+If you prefer manual registration over `./vicem.mjs setup`, register `vicem.mjs mcp` so agents can call `vicem_create_baton`, `vicem_read_baton`, `vicem_rehydrate`, and `vicem_check_guard`:
+
+```bash
+# Claude Code
+claude mcp add vicem -- node /absolute/path/to/vicem.mjs mcp
+
+# OpenAI Codex CLI
+codex mcp add vicem -- node /absolute/path/to/vicem.mjs mcp
+```
+
+---
+
+## Supply-Chain Verification & Minimal TCB
+
+Verify zero third-party dependencies and cryptographic artifact integrity in one command:
+
+```bash
+# 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 under strict Node.js Permission Model sandbox
+node --permission \
+  --allow-fs-read=. \
+  --allow-fs-write=.vicem \
+  --allow-child-process \
+  vicem.mjs diet
+```
+
+---
+
+## Automated Test Suite
+
+```bash
+node --test test/*.test.mjs
+```

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy & Zero-Trust Verification (`SECURITY.md`)
+
+## 1. Zero-Dependency & Zero-Network Guarantee
+
+- **Zero External Dependencies (`C-10`):** `vicem.mjs` uses **only** Node.js built-in modules (`node:fs`, `node:path`, `node:os`, `node:crypto`, `node:child_process`, `node:readline`, `node:util`, `node:url`, `node:sqlite`). There is no `package.json` dependency tree and zero supply-chain risk from third-party npm packages.
+- **Zero Network Calls (`C-11`):**
+  - `vicem.mjs` never imports `node:http`, `node:https`, `node:net`, `node:tls`, or `node:dgram`, and never calls `fetch()`.
+  - `index.html` enforces `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline';">`, making outbound network connections impossible at the browser engine level.
+
+## 2. Credential Blindness (`C-06`)
+
+Vicem enforces a hardcoded blacklist (`CREDENTIAL_BLACKLIST_PATTERNS`) and never opens or harvests:
+- `.env`, `.env.*`
+- `auth.json`, `credentials.json`, `.credentials.json`
+- `id_rsa`, `id_ed25519`, `*.pem`, `*.key`, `*.p12`, `*.pfx`
+- `.npmrc`, `.pypirc`, `.netrc`, `kubeconfig`
+
+## 3. 3-Tier Secret Redaction & No-Unredaction Policy (`UC-15`)
+
+All harvested text, git diffs, logs, `.vicem/BATON.md`, and `.vicem/ledger.json` entries pass through `SecretRedactor.redact()`:
+1. **Provider Regex Rules:** AWS (`AKIA`/`ASIA`), GitHub (`ghp_`/`github_pat_`), Anthropic (`sk-ant-`), OpenAI (`sk-`/`sk-proj-`), Google (`AIza`), Slack (`xox*`), Stripe (`sk_live_`), JWT, and PEM Private Keys.
+2. **Shannon Entropy Detector:** High-entropy (`H >= 4.2` bits/char) secret assignments are masked while whitelisting UUIDs, Git SHAs, file paths, and CSS classes.
+3. **No-Unredaction Rule:** Even when an agent calls `vicem_rehydrate(file_path, symbol_name)` via MCP, secrets remain redacted as `‹REDACTED:PROVIDER:HASH4›`.
+
+## 4. Node.js Permission Model Sandbox
+
+You can restrict `vicem.mjs` at the OS/V8 level using Node.js `--permission`:
+
+```bash
+node --permission \
+  --allow-fs-read=/path/to/repo \
+  --allow-fs-write=/path/to/repo/.vicem \
+  --allow-child-process \
+  vicem.mjs diet
+```

package/SHA256SUMS

@@ -0,0 +1,4 @@
+4e35eed0de4d811c7bfbaf60edf209909822d18a1e07b1e7455c3d0f467a7815  vicem.mjs
+860cc494a127310766df1668b8e3014f5b8d1609b5ac02a314214e8d39458027  index.html
+ce2cb3163d018ea796bcbecbbd954f7aa0834c8a273cfbd7ba510eb28e22aa84  .agents/skills/vicem/SKILL.md
+6080f065cb682ed8085859ab76814f1fc61963e32e91ece63cb36dc74b31e8b5  AGENTS.snippet.md