Skip to content

compatibility.md

Latest commit

 

History

History
69 lines (54 loc) · 5.44 KB

compatibility.md

File metadata and controls

69 lines (54 loc) · 5.44 KB
Raw

Codez Compatibility

Codez is intentionally close to upstream Codex where compatibility matters. Fork-specific behavior should be explicit and optional where possible.

Surface Upstream Codex Codez Notes
CLI command codex codex Kept compatible so scripts and habits transfer.
NPM package shape @openai/codex publication decision Public package naming is not finalized in this projection.
License Apache-2.0 Apache-2.0 Keep upstream attribution intact.
Core Rust runtime upstream baseline forked runtime Codez changes should stay bounded and documented.
Prompt-history pruning upstream behavior Codez token-control path Prunes stale context, older reasoning, tool calls, and tool outputs before model sampling when safe.
Goal-continuation pruning upstream behavior Codez token-control path Treats automatic goal follow-up prompts as fresh prompt boundaries while preserving live-steering safety.
Live-steer pruning safety upstream behavior Codez token-control path Keeps small steering updates adjacent to the active turn without letting them disable stale-history pruning across later requests.
Remote/autocompact pruning upstream behavior Codez compaction path Applies pruning before remote compaction and can trim function-call history to reduce context pressure.
App Server v2 upstream-compatible where present active fork surface Local client/gateway protocol surface for thread operations, command events, hook/catalog inspection, and richer integrations.
Plugin loading upstream-compatible where present active fork surface Used for local plugin workflows and hook experiments.
Plugin hooks optional feature supported Codez use case Enable via config when a runtime supports plugin hooks; Codez keeps plugin-loaded hook paths usable for RTK/Pitlane-style workflows.
RTK Codex Plugin external optional external plugin Adds shell rewrite and bounded-output guard behavior.
Pitlane Codex Plugin external optional external plugin Adds indexed code-navigation rewrites through host-local Pitlane CLI.
Gateway layer not required not required Gateway projects can use Codez, but Codez should not depend on them.

Token-Control Shape

Codez includes runtime paths for reducing token waste in long sessions:

  • before normal model sampling, stale context and older tool/reasoning history can be pruned while keeping the active turn intact
  • automatic goal follow-up turns can prune stale tool-heavy work from the previous goal turn while keeping the active goal objective visible
  • before remote/autocompact summarization, the same pruning can be applied so the compaction request is not forced to carry avoidable historical tool noise
  • function-call history can be trimmed before remote compaction when the context window is already under pressure

This is separate from hook-level shell changes. Prompt-history pruning reduces what Codez sends to the model; RTK reduces risky shell output before it enters the conversation, and Pitlane can replace safe source-navigation reads with bounded indexed CLI calls.

Plugin Hook Shape

A Codex-compatible plugin hook runtime needs:

  • plugin manifests under .codex-plugin/plugin.json
  • hook declarations under hooks/hooks.json
  • PreToolUse support for shell/Bash calls
  • ${PLUGIN_ROOT} expansion in hook commands

Example feature flags:

[features]
plugins = true
plugin_hooks = true

Optional public companion plugins:

Boundaries

Codez should not include private host registries, gateway state, local operator paths, or deployment assumptions in the public projection. Those belong in separate private docs or future gateway projects.