https://github.com/krablante/rtk-codex-plugin

Codex-compatible shell rewrite and bounded-output plugin for token-safe command inspection.
https://github.com/krablante/rtk-codex-plugin

codex plugin rtk shell token-safety

Last synced: about 12 hours ago
JSON representation

Codex-compatible shell rewrite and bounded-output plugin for token-safe command inspection.

Host: GitHub
URL: https://github.com/krablante/rtk-codex-plugin
Owner: Krablante
License: mit
Created: 2026-05-15T11:36:09.000Z (about 2 months ago)
Default Branch: main
Last Pushed: 2026-05-15T19:52:37.000Z (about 2 months ago)
Last Synced: 2026-05-15T22:47:49.605Z (about 2 months ago)
Topics: codex, plugin, rtk, shell, token-safety
Language: Python
Size: 18.6 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

rtk-codex-plugin

Keep Codex shell output useful before it burns the context window.

A small Codex-compatible shell plugin for command rewrite, bounded long-line output, and artifact-backed output compaction.

Install
·
Compatibility
·
Stack Fit

`rtk-codex-plugin` adds a shell-focused `PreToolUse` hook for Codex-compatible
runtimes. It has three jobs:

- route eligible Bash/`exec_command` calls through `rtk rewrite` for more
compact output;
- wrap risky long-line inspections with a bounded output guard;
- compact medium/large model-visible tool output after execution while
preserving the full raw output, including `write_stdin` streams, in local
artifacts.

The guard is useful even when `rtk` is not installed. Rewrite mode is optional
and activates only when the `rtk` binary is available in `PATH`.

## 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 |

## Why People Use It

- avoid huge JSONL, log, and prompt-capture lines flooding the model context
- keep simple shell exploration compact without changing test or machine
command semantics
- preserve no-rewrite command semantics for `rg --files`, `git status --short`,
`jq`/JSON modes, counts, lists, direct `rg`/`grep` searches, build/test
commands, Docker commands, and interactive commands while still compacting
oversized model-visible output
- install as a small plugin instead of changing every shell command by hand

## Mental Model

| Piece | Role |
| --- | --- |
| Codex-compatible runtime | executes `PreToolUse` hooks before shell calls |
| `rtk-codex-hook` | decides whether a command should be guarded, rewritten, or left alone |
| `rtk-output-guard` | caps per-line and total stdout for risky inspections |
| `rtk-output-post-hook` | compacts large model-visible shell output with artifact refs |
| optional `rtk` binary | rewrites eligible commands into a compact shell form |

Architecture at a glance:

```text
Codex shell tool call
-> PreToolUse hook
-> risky JSONL/log/prompt inspection? run through rtk-output-guard
-> otherwise eligible simple command? ask rtk rewrite
-> no-rewrite/build/test/Docker/interactive command? pass through unchanged
-> PostToolUse hook
-> medium/large model-visible output? summary + full local artifact
```

## Highlights

- bounds known long-line inspection shapes before execution
- bounds medium/large model-visible output after execution, including large
pass-through command output unless explicitly bypassed
- works without `rtk` for output guarding
- skips rewrite when exact stdout matters
- uses plain Python scripts and a small plugin manifest
- designed to work standalone and to fit the modular Codez stack

## Quick Start

Clone the plugin into the plugin cache used by your Codex-compatible runtime.
One common cache layout looks like this:

```bash
codex_home="${CODEX_HOME:-$HOME/.codex}"
git clone https://github.com/Krablante/rtk-codex-plugin \
"$codex_home/plugins/cache/github/rtk-codex-plugin/local"
```

Enable plugin hooks and the plugin key that matches your install location:

```toml
[features]
plugins = true
plugin_hooks = true

[plugins."rtk-codex-plugin@github"]
enabled = true
```

Run the focused test suite:

```bash
make test
```

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/krablante/rtk-codex-plugin

Awesome Lists containing this project

README

rtk-codex-plugin