Algorithmic VCC Compaction for oh-my-pi

Fast, deterministic, lossless compaction. No LLM calls. Port of sting8k/[email protected] into oh-my-pi. Paper arxiv:2603.29678 (Zhang & Agrawala).

Quick start

omp plugin link /Users/zhu/code/projects/omp-vcc        # local
omp plugin install omp-vcc                               # npmjs, no auth
omp plugin install @zhulinchng/omp-vcc                   # GitHub Packages, needs PAT
omp plugin install github:zhulinchng/omp-vcc             # git, latest main
omp plugin list --json | jq '.[] | select(.name|contains("omp-vcc"))'

New here → docs/setup.md.

What you get

• Manual /omp-vcc [keep:N] [focus] (/pi-vcc alias) — compact only, single-line toast 90k→22k — e.g. /omp-vcc keep:2 fix auth (detailed savings via /vcc-stats).
• Recall vcc_recall({query, scope, page, mode, expand}) + /vcc-recall — regex → TF-IDF OR, 5/page, mode:'touched', #N:path drill-down.
• Savings toast 90k→22k (76% saved) single line (inline Last compaction detail removed; use /vcc-stats), divider, /vcc-stats + vcc_stats tool (50-capped history, per-pi), details.savings persisted, /tmp/omp-vcc-debug.json.

Commands

| Command | What it does | Defaults (bare invocation) | | --- | --- | --- | | /omp-vcc [keep:N] [focus] | Compact only. Toast single line; detail via /vcc-stats. | keep:1 — smart-keep grows it while the tail stays ≤5k (cap 25k). keep:0 summarizes everything. No focus = no follow-up prompt. Explicit keep:N is never boosted. | | /pi-vcc | Legacy alias for /omp-vcc | Same as above. | | /vcc-recall [query] [scope:all] [page:N] | Search compacted history, 5 results per page. | No query = last 25 entries of the active branch. Scope defaults to the active lineage; scope:all searches the whole session. page:1. | | /pi-vcc-recall | Legacy alias for /vcc-recall | Same as above. | | /vcc-stats [history\|all] | Last-compaction savings + history table (single, no alias). | Bare = last-compaction detail (history table appended once >1 compaction exists). history/all = full table first, then the last detail. | | /vcc-config | Effective config with per-key source (file / host overlay / default) plus resolved file path. | Args ignored — always the merged result. |

+Search mode (hybrid regex→TF-IDF search default, touched = touched-files list) is a vcc_recall tool parameter only — the slash command always searches hybrid. + +Tools: vcc_recall, vcc_stats (approval read). Extension-only — no commands/*.md file slash commands (avoids duplicate /omp-vcc).

Configuration

File ~/.omp/omp-vcc/config.json — XDG: $OMP_VCC_CONFIG_PATH > $PI_VCC_CONFIG_PATH > $OMP_DIR/$PI_CODING_AGENT_DIR > ~/.omp/omp-vcc/config.json (migrates ~/.pi/agent/pi-vcc-config.json once).

{
  "vccEnabled": true,
  "overrideDefaultCompaction": true,
  "smartKeepTail": true,
  "continueAfterThresholdCompact": true,
  "debug": false
}

| Flag | Default | Effect | | --- | --- | --- | | vccEnabled | true | Master switch. false = no interception. | | overrideDefaultCompaction | true | true = VCC handles threshold/overflow. false = host methodOrder handles them; /omp-vcc still works. | | smartKeepTail | true | Grow keep:1 when tail <5k (cap 25k). Explicit keep:N never boosted. | | continueAfterThresholdCompact | true | Invisible-continue (omp-vcc-auto-continue) after threshold compact. | | debug | false | Write /tmp/omp-vcc-debug.json per compaction. |

Toggle live: omp config set plugins."@zhulinchng/omp-vcc".debug true or /settings → @zhulinchng/omp-vcc. File is source of truth; ctx.settings overlays at runtime. /vcc-config shows the merged result — use it to confirm a toggle took effect.

How it works

VCC compiles JSONL trace via lex → parse IR → monotonic line assignment → view lowering into V_full (identity), V_ui (5 sections + ranked brief), V_adapt(b,ρ) (recall). Pointer invariant V_ui → V_full[s:e] via (#N) refs.

Calibrate cpt → SmartKeep → BuildOwnCut → Normalize → FilterNoise → BuildSections → Brief (1100→2000 tok, 120 lines) → Merge

See docs/harness.md for host impact and docs/architecture.md for pipeline.

Combining with shake and snapcompact

VCC summarizes history; shake elides artifact:// blocks in kept tail (disjoint); snapcompact is an alternative history archiver (vision bitmaps, needs model.input includes "image"). One CompactionEntry per trigger — combos are additive or sequential, never double-summarization.

| Trigger | override | Result | | --- | --- | --- | | threshold, override:true (default) | VCC handles; host auto-shakes if still over band (#rescueCompactionDeadEnd) | VCC + shake if dead-end | | threshold, override:false | Host walks methodOrder (remote→snapcompact→handoff→shake→soft) | VCC → snapcompact/shake fallback | | /omp-vcc keep:2 | Always VCC (sentinel __omp_vcc__) | VCC | | /omp-vcc then /compact snapcompact | Sequential | VCC entry, then snapcompact entry |

Additive VCC+shake is automatic: the host's dead-end rescue runs shake elide when VCC made no headroom, and the retained-tool-output budget (retainedToolOutputMaxTokens) elides consumed tail output deterministically. Explicit mode (snapcompact/shake/soft/…) bypasses VCC even when override:true (hook.ts:733). Full table: docs/setup.md + docs/harness.md §8.

Development

bunx tsc --noEmit
bun test                  # 870 tests, 66 files, 2907 expects, 0 fail
bun test tests/e2e --timeout 120000  # 124 E2E
bun run smoke             # 13 checks: 3 hooks + 6 cmds + 2 tools + dedup (+ pipeline)
omp plugin link . && omp plugin doctor

type:module, allowImportingTsExtensions, // @ts-nocheck on vendored extensions/vcc-core/**, zero dist/. prepublishOnly runs tsc && test && smoke.

Verification

bunx tsc --noEmit && bun test && bun run smoke
omp -e @zhulinchng/omp-vcc
/omp-vcc keep:1   # expect [Session Goal] + toast omp-vcc: kept 1/2 turns
/vcc-stats        # table + history
/vcc-config      # effective config card with per-key source
cat /tmp/omp-vcc-debug.json  # when debug:true

Full matrix: docs/verification.md. Harness map: docs/harness.md §9.

Docs

setup · configuration · architecture · harness · verification · omp-compaction · omp-snapcompact · paper-notes · PUBLISHING

Publishing: npm publish --access public (unscoped omp-vcc), gh release create vX.Y.Z → GPR (@zhulinchng/omp-vcc). Consumer GPR auth: @zhulinchng:registry=https://npm.pkg.github.com.

License

MIT