Design and implementation plan

September 18, 2026 ยท View on GitHub

Product decision

Deliver an ordinary, self-contained Codex plugin that prepares an explicit context handoff. Codex's internal history and compaction hooks are outside this plugin's contract. The useful entry points are a natural-language skill, a discoverable MCP tool, and a file-oriented CLI. No background monitor or kernel change is required.

Data flow

  1. A user or Codex supplies exact source blocks and a current goal.
  2. Deterministic rules pin narrative instructions, recent blocks, path-bearing evidence, explicitly open work and unfinished markers. Only complete one-call/one-result pairs with a known read-only tool name and an explicitly verified read can qualify.
  3. Jev receives the entire provided goal and blocks, without shortened tool results. Each noul question asks whether one eligible pair should stay. A probability below 0.2 permits removal; everything else stays.
  4. The program validates every answer and then applies all decisions together. Failure in any batch abandons all deletion proposals.
  5. JSON contains exact retained blocks, source ids, decision reasons and measurements. Markdown quotes retained text with fences longer than any source backtick run. Both formats are handoff artifacts, not executable session history.

Deliberate limits

  • The caller must supply truthful provenance, operation metadata and all relevant instructions. Neither Jev nor regex patterns prove an action safe.
  • Typical paths and common file extensions are pinned. Arbitrary filenames and every human-language expression of unfinished work cannot be recognized automatically; pin and status: open are the explicit contract.
  • The complete state has a conservative 24,000 UTF-8-byte budget; state plus the longest question is bounded to 28,000 bytes, and each serialized request to 56,000 bytes. Bytes are used as conservative token budgeting, not as measured model token counts. Oversize evidence returns unchanged, with no hidden truncation.
  • Requests run sequentially under a 15-second total deadline. There are no automatic retries, cost multipliers or alternate endpoints.
  • Only TypeSafe's fixed HTTPS System One endpoint is used by production code. Tests inject an in-process fetch implementation; users cannot redirect credentials with an endpoint option.
  • contentReduction measures source content bytes only. The decision log and metadata add output overhead, so benchmark reports also include serialized JSON and Markdown bytes. No current-session token saving is claimed.

Implementation and verification sequence

  1. Scaffold with the locally installed official plugin-creator helper and initialize an independent repository.
  2. Write preservation, API protocol and rollback tests; observe failure before implementation.
  3. Implement the selector, then write CLI and MCP protocol tests before their entry points.
  4. Validate manifests and skill; install with a temporary CODEX_HOME, discover the skill and invoke the MCP tool through actual Codex app-server methods.
  5. Run an offline, fixed-probability fixture benchmark and publish its measurement boundaries.
  6. Commit source, package committed HEAD, and publish only after the complete local checks pass.

Local host discovery established that this Codex manifest uses cwd: "." resolved against the installed plugin root. Claude-style path variables are not used. The checked-in smoke script reproduces installation, skill loading, tool discovery, direct tool invocation and removal without a model turn.

Sources

  • User-selected upstream: tamaratran/fast-jev-compaction, commit e3f262a7f4d42bd8dd32ced30d26176f7cb545b0.
  • User-supplied local Jev research notes dated 2026-09-18; no additional social/web research was performed for this implementation.
  • Locally installed Codex CLI 0.153.4 help and generated app-server schemas; official bundled plugin-creator manifest specification and validators.