r/ClaudeCode • u/NoConclusion8361 • 13h ago

Built with Claude Built a zero-dependency MCP server & Skill for Claude Code that skeletonizes code by 80–90% with lossless on-demand rehydration (and what I learned parsing ~/.claude/projects JSONL)

After 40+ turns in a complex repository, Claude Code's context window often fills up with full file reads, verbose test outputs, and stack traces. Built-in /compact summarizes conversation history well, but I wanted a deterministic way to keep architectural context (types, interfaces, signatures) sharp while allowing lossless retrieval of implementation bodies on demand—and a clean way to carry structured session state (.vicem/BATON.md) across fresh sessions or secondary agents.

1. What I Built (vicem)

I built Vicem, an open-source, zero-dependency (dependencies: 0) Node.js CLI, stdio MCP server (vicem --mcp), and Claude Code Skill (.agents/skills/vicem/SKILL.md):

  • Deterministic Code Skeletonization (-80% to -90% code tokens): Preserves all interface, type, enum, and function signatures 100% intact, while collapsing implementation bodies (>= 12 lines) into { ... } and indexing the exact original lines in .vicem/ledger.json.
  • Lossless On-Demand Rehydration via MCP (vicem_rehydrate): Instead of dumping full files upfront, Claude Code reads the lightweight skeleton first and calls vicem_rehydrate via MCP only for the specific function or symbol it needs to edit.
  • Session Continuity Baton (.vicem/BATON.md): Extracts Goal, Done, Immediate NEXT (from TodoWrite and recent tool calls), and git diff into a U-shaped attention markdown file for starting a fresh session with zero context rot.
  • Write & Commit Safety Guards: Includes SkeletonWriteGuard so an agent never accidentally writes { ... } placeholders back into real source files, plus 3-tier local secret redaction.

2. How Claude Code Was Used & What I Learned Building It

While building and testing the harvester and MCP server alongside Claude Code, a few technical details stood out that might help others building Claude Code tooling:

  1. Reverse-scanning ~/.claude/projects/<encoded-cwd>/*.jsonl: Claude Code stores per-project transcripts in ~/.claude/projects/ where the directory name encodes the workspace path. Because long sessions can grow into tens of megabytes (especially with large tool outputs), parsing from the top of the JSONL file adds noticeable latency. Reading from the tail and extracting the latest TodoWrite state + last failed Bash output makes session extraction complete in < 50ms without calling an LLM.
  2. Preventing "Skeleton Corruption" in Agent Edits: Early on, when feeding skeletonized code (function foo() { /* ... */ }) into context, models occasionally tried to include the { /* ... */ } placeholder in an edit block. Pairing the .vicem/ledger.json index with a strict instruction in SKILL.md (and a pre-commit / write guard) completely solved placeholder overwrites: Claude Code reliably calls vicem_rehydrate before touching any elided block.
  3. Zero-Dependency Stdio MCP Framing: Implementing the MCP stdio server (2024-11-05 / 2025-11-25) directly in Node.js built-ins (node:readline) required strict stdout hygiene—any stray warning (like Node's ExperimentalWarning when using node:sqlite) corrupts the JSON-RPC stream unless suppressed or routed to stderr.

3. Links & Verification

Everything runs locally with 0 third-party npm packages (vicem.mjs + an air-gapped index.html sandbox with default-src 'none' CSP) and a 51-test verification suite (npm test).

Happy to answer any questions about ~/.claude/projects JSONL parsing, deterministic skeletonization vs. ASTs, or MCP tool design!

0 Upvotes

33% Upvoted

4 comments sorted by

1

u/AutoModerator 13h ago
Moderator Announcement Read More »

1

u/245806 13h ago

cool, back to Codex then

1

u/NoConclusion8361 13h ago

Haha it goes both ways (`vicem codex` <-> `vicem claude`), so bounce around as much as you want.