https://github.com/krablante/codez
Codex-compatible runtime fork for local agents, plugin hooks, and practical context control.
https://github.com/krablante/codez
ai-agents cli codex codez plugin-hooks rust
Last synced: 13 days ago
JSON representation
Codex-compatible runtime fork for local agents, plugin hooks, and practical context control.
- Host: GitHub
- URL: https://github.com/krablante/codez
- Owner: Krablante
- License: apache-2.0
- Created: 2026-05-15T12:02:30.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2026-05-16T00:48:55.000Z (15 days ago)
- Last Synced: 2026-05-16T01:57:43.633Z (15 days ago)
- Topics: ai-agents, cli, codex, codez, plugin-hooks, rust
- Language: Rust
- Size: 7.03 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
- Security: SECURITY.md
- Notice: NOTICE
- Cla: docs/CLA.md
Awesome Lists containing this project
README
Codez
A Codex-compatible runtime fork for local agents, token-aware context control, App Server v2, and plugin hooks.
Codez keeps upstream Codex compatibility where it matters, then layers focused runtime experiments on top.
Compatibility
·
Stack
·
RTK Plugin
·
Pitlane Plugin
·
Getting Started
·
Config
Codez is a fork of [OpenAI Codex](https://github.com/openai/codex). The goal is
not to hide that lineage: upstream Codex remains the base CLI, protocol, package
shape, and user-facing mental model. Codez is the fork layer for local-agent
runtime work that benefits from moving faster than upstream.
## Why Codez Exists
- keep a Codex-compatible CLI/runtime while experimenting with local-agent needs
- reduce wasted tokens from stale tool, reasoning, and context history
- support plugin and hook workflows that can harden shell usage
- expose App Server v2 surfaces for local clients and future gateways
- make context-pressure and prompt-history behavior easier to evolve
- provide a clear core layer for future gateway projects without baking a
specific gateway into the runtime
## Core Additions
Codez is not only a renamed README around upstream Codex. The fork carries
runtime work aimed at long local-agent sessions:
- prompt-history pruning before model sampling: stale context messages, older
reasoning items, tool calls, and tool outputs can be removed before the next
request while preserving the active turn and image-output dependencies
- goal-continuation pruning: automatic goal follow-up turns are treated as
fresh prompt boundaries, so previous tool-heavy work can be trimmed while the
active goal objective remains visible
- live-steer prompt boundary safety: tiny steering updates during a run can
stay adjacent to the active turn without disabling broader stale-history
pruning for later requests
- compaction-aware pruning: the remote/autocompact path can apply the same
pruning and trim function-call history before compaction, reducing context
pressure before a summarization turn
- App Server v2: a local app/server protocol surface for richer clients,
gateway experiments, thread operations, goal RPC, hook/catalog inspection,
and command event flows
- plugin hook compatibility: Codez keeps plugin-loaded hook paths usable for
`PreToolUse` workflows, so optional plugins such as RTK and Pitlane can run
as normal runtime extensions
## Part of the Codez stack
The Codez stack is modular. Each layer can be used on its own unless a higher
layer explicitly opts into it.
| Layer | Public surface | Responsibility | Dependency |
| ------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [Codez](https://github.com/Krablante/codez) | Codex-compatible runtime | App Server v2, goal RPC, long-session hardening, prompt pruning, and plugin hooks | Does not require Teledex |
| [RTK Codex Plugin](https://github.com/Krablante/rtk-codex-plugin) | Optional Codex plugin | Shell/token safety through `rtk rewrite` and bounded output guarding | Requires a Codex-compatible plugin-hook runtime; does not require Teledex |
| [Pitlane Codex Plugin](https://github.com/Krablante/pitlane-codex-plugin) | Optional Codex plugin | Code-navigation/token-saving rewrites through a host-local `pitlane` CLI | Requires a Codex-compatible plugin-hook runtime and local `pitlane`; does not require Teledex |
| [Teledex](https://github.com/Krablante/teledex) | Telegram gateway/session layer | Topics, queues, live steer, `/goal` UX, and delivery/recovery around durable agent sessions | Full mode is optimized for Codez App Server v2; upstream `codex exec --json` is legacy compatibility only |
## What Is Different
Codez keeps upstream names such as `codex`, `@openai/codex`, and Codex protocol
terms where compatibility matters. Fork-specific docs use the Codez name when
describing additions, release projections, or stack positioning.
RTK and Pitlane are published separately:
https://github.com/Krablante/rtk-codex-plugin
https://github.com/Krablante/pitlane-codex-plugin
The Telegram gateway layer is public at:
https://github.com/Krablante/teledex
Teledex is a Codez-first gateway. Its full mode is built around Codez App Server
v2; upstream `codex exec --json` is documented there as a legacy compatibility
fallback, not the strategic gateway backend.
## Quick Start
Download Linux and Windows x64 archives from the
[Codez releases page](https://github.com/Krablante/codez/releases). Each
archive includes a short README and installer script.
The full setup is in [Installing and Building Codez](./docs/install.md). If you
prefer to build from source, the shortest path is:
```bash
git clone https://github.com/Krablante/codez
cd codez/codex-rs
cargo build
cargo run --bin codex -- --help
```
Gateway integrations should use the App Server v2 runtime surface:
```bash
cargo run --bin codex -- app-server --listen stdio://
```
For upstream Codex usage, package names and official setup are still documented
by OpenAI:
- [Codex documentation](https://developers.openai.com/codex)
- [Upstream repository](https://github.com/openai/codex)
## Read Next
- [Compatibility matrix](./docs/compatibility.md)
- [Codez stack](./docs/stack.md)
- [Optional RTK plugin integration](./docs/rtk-plugin.md)
- [Optional Pitlane plugin integration](./docs/pitlane-plugin.md)
- [Installing and building](./docs/install.md)
- [Configuration](./docs/config.md)
- [Contributing](./docs/contributing.md)
## License and Attribution
Codez is distributed under the same [Apache-2.0 license](./LICENSE) as upstream
Codex. OpenAI Codex remains the upstream project; Codez is an independent fork
projection and is not presented as an official OpenAI release.