Codex Token Optimizer

Codex Agent Skill for token optimization with RTK (Rust Token Killer) and Headroom MCP.

This skill helps Codex decide when to route noisy shell commands through RTK, when to compress large context or tool outputs with Headroom, and how to report measured token savings without overstating the scope.

What It Optimizes

• Shell output with RTK: git status, git diff, git log, rg, find, pytest, npm test, cargo test, docker logs, and kubectl logs.
• Context and tool output with Headroom MCP: long logs, stack traces, large file excerpts, RAG chunks, issue threads, and previous-agent handoff notes.
• Measurement: RTK savings via rtk gain; Headroom savings via headroom_stats.

What It Does Not Do

• It does not install RTK, Headroom, MCP servers, Homebrew packages, or Python packages automatically.
• It does not claim whole-session Codex savings from RTK or Headroom alone.
• It does not compress secrets, private keys, tokens, credentials, payment data, or direct personal contact data into model-visible summaries.
• It does not replace reading required evidence. Raw output should be retrieved when correctness depends on exact lines, versions, stack frames, or config values.

Install

Install the skill from this repository path:

install-skill-from-github.py --repo HelloWorld668/codex-token-optimizer --path codex-token-optimizer

Or install from the GitHub tree URL:

install-skill-from-github.py --url https://github.com/HelloWorld668/codex-token-optimizer/tree/main/codex-token-optimizer

Restart Codex after installing so the skill metadata is loaded.

RTK Setup

RTK is a CLI proxy for reducing shell command output before it enters the model context.

brew install rtk
rtk --version
rtk init -g --codex
rtk gain

Use RTK explicitly for noisy commands when the hook is not active:

rtk git status
rtk git diff
rtk rg "pattern" .
rtk test pytest -q
rtk docker logs service-name

Headroom Setup

Headroom is the context compression layer for large tool outputs, logs, files, and RAG chunks.

Configure Headroom as an MCP server when reversible compression and retrieval are needed. A working Codex session should expose:

• headroom_compress
• headroom_retrieve
• headroom_stats

New MCP server configuration usually requires a Codex restart or a new thread before the tools become visible.

Skill Behavior

The skill triggers when the user mentions token budget, context bloat, long logs, large command output, RTK, Rust Token Killer, Headroom, MCP compression, Codex token optimization, or measuring token savings.

It uses RTK for shell command output, Headroom MCP for large context/tool outputs, and bounded normal commands when either tool is unavailable.

Verification

For RTK:

rtk --version
rtk gain

For Headroom, verify that the MCP tools are visible in the current Codex session:

headroom_compress
headroom_retrieve
headroom_stats

If Headroom was just installed but the tools are missing, restart Codex or open a new thread.

Repository Layout

codex-token-optimizer/
  SKILL.md
  agents/
docs/
  environment.md
README.md
LICENSE

Keywords

Codex skill, Agent Skill, RTK, Rust Token Killer, Headroom MCP, context compression, token optimization, LLM tools, shell output compression, measured token savings.

License

MIT