codex-jev-compaction

Keep the evidence. Carry less context.

Jev-powered context handoffs for Codex — original text, visible decisions, conservative fallbacks.

Quick start · How it works · Measured results · 简体中文 · Pi edition

A real Codex plugin containing a skill, a stdio MCP tool, and a zero-dependency CLI. Give it explicit context blocks; it returns a traceable JSON or Markdown packet for the next task or session.

This release prepares explicit handoffs. It does not replace Codex native automatic compaction, reclaim tokens in the current conversation, or modify Codex session files.

What and why

Long tasks accumulate tool output that is no longer useful. A generated summary can lose an exact constraint, path, or error. This plugin asks Jev a narrower question: should this old, verified read-only tool pair remain in the handoff?

Jev returns classification probabilities. Code decides which evidence is eligible, validates every answer, preserves protected content, and builds the packet. Retained source text stays verbatim and in order. Selection itself is lossy: removed evidence is absent, and a classifier can be wrong. Keep the original input as the authoritative archive.

This is an independent Codex implementation inspired by tamaratran/fast-jev-compaction, with a different host integration and explicit preservation rules.

Related MCP server: cic-mcp-gateway

Quick start

Requirements: Node.js 22+ on PATH, a Codex CLI with codex plugin, and a TypeSafe API key for live selection. Local host acceptance used Codex CLI 0.153.4 on Windows. The source has no runtime npm dependencies or build step.

codex plugin marketplace add Wang-auspicious/codex-jev-compaction
codex plugin add codex-jev-compaction@codex-jev-compaction

To pin a release, add --ref v0.1.0 to the marketplace command. The marketplace name and plugin name are both codex-jev-compaction.

Set the key in the environment that launches Codex. Keep it out of plugin manifests, source files and shell-history literals. For PowerShell 7:

$env:TYPESAFE_API_KEY = Read-Host 'TypeSafe API key' -MaskInput
codex

For Bash:

read -rsp 'TypeSafe API key: ' TYPESAFE_API_KEY
export TYPESAFE_API_KEY
codex

Open a new Codex task after installing or changing the launch environment. Desktop apps must inherit the same environment; installing a plugin cannot inject a key into an already running process.

Then ask:

Use the jev-handoff skill to prepare a context handoff from these source blocks. Keep my instructions, paths, unresolved work and unverified actions. Show what was removed and why.

The skill calls curate_context. It uses exact visible evidence or a source artifact you provide; it cannot retrieve hidden or missing history. Missing keys are supported: the tool returns the original blocks with an explicit reason and sends nothing.

Install from a checkout or release ZIP

Clone the repository or extract the source ZIP, then run:

codex plugin marketplace add /absolute/path/to/codex-jev-compaction
codex plugin add codex-jev-compaction@codex-jev-compaction

Point Codex at the repository root containing .agents/plugins/marketplace.json. No npm install is needed to use the plugin.

Use the MCP tool

The server is named jev_context; its tool is curate_context. This minimal input is also a safe installation check:

{
  "goal": "Finish the parser fix and keep generated files unchanged.",
  "blocks": [
    {
      "id": "request-1",
      "role": "user",
      "content": "Finish the parser fix and keep generated files unchanged."
    },
    {
      "id": "next-1",
      "role": "context",
      "content": "TODO: run the parser regression test.",
      "status": "open"
    }
  ]
}

Expected result: status: "unchanged", reason: "nothing_eligible", stats.requests: 0. Both blocks are protected; this check does not test Jev connectivity.

For selection, supply actual tool evidence with matching callId values:

{
  "goal": "Investigate the current warning.",
  "preserveRecent": 1,
  "blocks": [
    { "id": "u1", "role": "user", "content": "Investigate the warning. Do not publish." },
    {
      "id": "c1", "role": "tool_call", "callId": "read-1",
      "toolName": "read", "readOnly": true, "verified": true,
      "content": "Read the previous console output."
    },
    {
      "id": "r1", "role": "tool_result", "callId": "read-1",
      "content": "Previous run: completed successfully; no warning was present."
    },
    { "id": "a1", "role": "assistant", "content": "The current warning still needs investigation." }
  ]
}

This small example demonstrates the contract; metadata overhead may make its handoff larger than its input. Use truthful metadata. verified: true on the call means the read completed and its result was observed and verified. An explicit verified: false on either member protects the pair. Never relabel shell commands, edits, sends or deletes as read-only reads.

Use the CLI

From the repository root:

# Offline, no key or service required
node plugins/codex-jev-compaction/scripts/cli.mjs --input fixtures/minimal.json --offline

# Live selection when the environment contains TYPESAFE_API_KEY
node plugins/codex-jev-compaction/scripts/cli.mjs --input context.json --format markdown > handoff.md

# Markdown source: preserve the whole document as one protected block
node plugins/codex-jev-compaction/scripts/cli.mjs --input notes.md --goal "Continue the parser fix" --format markdown

JSON can also arrive on stdin. --format json is the default. The CLI writes only to stdout and never overwrites source files itself. When redirecting output, use a different filename. Plain Markdown is treated as protected source text; it is not silently parsed into invented tool pairs or advertised as semantically pruned.

Attach the resulting packet to a new task, or explicitly reference it next session. The receiving agent should read it as historical evidence, inspect current files, and verify incomplete external actions before continuing.

How it works

1. Pin before inference. Preserve all narrative and instruction blocks, recent evidence, explicit pins, ordinary path-bearing text and known unfinished markers. A tool pair is indivisible.

2. Restrict the candidates. Only a complete, unambiguous one-call/one-result pair from a known read-only operation with a verified result can qualify. Unknown tools, writes and incomplete pairs stay.

3. Show Jev the evidence. Send the complete supplied goal and blocks as state to https://api.typesafe.ai/v1/systemone, using model: "jev-latest". Each noul question asks whether an eligible pair should be kept. Tool results are not omitted or abridged.

4. Keep uncertainty. Drop a candidate pair only when its validated keep probability is below 0.2. Values at or above 0.2 retain it. A probability is not a proof of irrelevance.

5. Apply atomically. Every batch must return every requested probability as a finite number in [0, 1]. Any failure abandons all proposed removals.

6. Make the decision inspectable. Return retained source blocks, per-id decisions and content-size measurements. Markdown uses literal fenced blocks, not a generated summary.

The API key travels only in the authorization header. When selection runs, all supplied evidence, including protected blocks, is sent to TypeSafe so the classifier can see the constraints. Do not include credentials or material you are not authorized to share. The plugin does not log keys, provider error bodies or transcript text.

Limits and fallback behavior

Each serialized request is bounded to 56,000 bytes; state plus the longest question is bounded to 28,000 bytes. UTF-8 bytes are a conservative budgeting proxy, not measured model tokens. At most 24 questions are sent per batch. Batches run sequentially under one deadline, without retries.

This conservative first release works on bounded evidence packets. Large raw sessions may exceed the limit and remain unchanged. Path recognition covers slash/backslash paths and common filenames; arbitrary filenames and every language's unfinished-work phrasing cannot be inferred reliably. Use pin: true and status: "open" when those facts matter.

Measured results

The bundled fixture has a repeated, obsolete console output, a relevant warning, a protected unverified send, user constraints and open work. Its fake transport returns fixed, predetermined probabilities. It tests integration and preservation mechanics, not Jev's judgment.

One local run on Windows with Node.js 24.13.1, 50 measured iterations after one warm-up:

These are offline fixture measurements, not live Jev latency, semantic quality, cost savings, task success, or Codex token reductions. contentReduction excludes packet metadata; short inputs can produce larger full packets. No TypeSafe API key was available for a live evaluation at release preparation.

Reproduce:

npm run check
npm test
npm run benchmark
npm run smoke:codex

The host smoke creates a temporary CODEX_HOME, installs the actual marketplace plugin, discovers its skill, starts an ephemeral Codex task, lists the MCP tool, invokes it through Codex's app-server, and uninstalls it. It performs no model turn and no Jev request. Temporary diagnostic evidence is retained at the printed path; your usual Codex configuration and sessions are unchanged. CODEX_BIN can select a specific Codex executable.

The release-preparation checks passed 37 automated tests, 10 JavaScript syntax checks, JSON and manifest consistency checks, the official local plugin and skill validators, and the Codex 0.153.4 host smoke. The project is plain JavaScript; check is a syntax/contract check, not a TypeScript type-check. CI covers Node 22/24 on Windows/Linux; published CI results are shown by the badge above.

After publication, verify the remote release through the same host acceptance path with npm run smoke:codex -- Wang-auspicious/codex-jev-compaction v0.1.0.

Disable, remove, and update

Nothing runs automatically on compaction. Stop invoking the skill or tool to stop selection. Unset TYPESAFE_API_KEY before a new Codex process to disable network selection while retaining offline handoffs. Use the Codex plugin settings to disable the plugin, or remove it with:

codex plugin remove codex-jev-compaction@codex-jev-compaction
# Optional: also remove the marketplace source
codex plugin marketplace remove codex-jev-compaction

Your handoff files and original source artifacts remain yours. To update, remove the plugin and marketplace, re-add the desired Git ref, and install again. Start a new task afterward.

Support and future work

Read the design and plan, release changes, and verification notes. To produce a source ZIP from a clean committed checkout, run npm run pack.

Attribution and license

Inspired by Tamara Tran's fast-jev-compaction, version 0.2.0 at commit e3f262a7f4d42bd8dd32ced30d26176f7cb545b0. Its core idea is to classify evidence instead of generating a new summary. This repository independently implements Codex integration and its own packet, eligibility and failure contracts; it does not rebrand or ship the original Claude Code hook.

MIT © 2026 Wang-auspicious. Project license · Upstream attribution and retained MIT notice.

An independent community project, not an official OpenAI, TypeSafe, or upstream-author product.