compressoor

compressoor

Compressoor is a concise runtime policy for Codex and Claude Code.

Its main job is to cut token overhead without making the agent sound unnatural. The style target is tool-first execution with no pre-tool chatter, no mid-loop chatter, no plan/thinking preambles before the first tool call, and short professional output after the loop. It also includes a small set of tools for compressing durable context such as handoffs, review notes, constraint summaries, and benchmark prompts.

Install • Benchmarks • Runtime Behavior • Context Tools • Main Files

What it is

• A Codex skill and plugin plus a Claude Code plugin for concise runtime behavior
• A small set of scripts for prompt compaction, rendering short live context, and benchmarking token savings
• Session bootstrap hooks and an optional launcher for Codex

Style target

• tool-first
• no pre-tool or mid-loop status text
• no initial plans or thinking summaries before the first tool call
• brief and professional
• no acknowledgements or filler
• no step-by-step narration unless it changes the plan
• short final answers with verification, blockers, and risks only when they matter

This is closer to "do the work first, then say less and keep it normal" than to character-role compression. The goal is lower token use without caveman speech.

Install

Fast Install From GitHub

If an agent or user only has the GitHub URL, this is the shortest Codex-friendly install path:

git clone https://github.com/M4cs/compressoor.git
cd compressoor
python3 skills/compressoor/scripts/install_codex_compressoor.py --force

If the repo is already cloned somewhere else, run the installer from that checkout.

Suggested prompt for an agent:

Clone https://github.com/M4cs/compressoor if it is not already present, change into that checkout, then run python3 skills/compressoor/scripts/install_codex_compressoor.py --force. After that, confirm that ~/.codex/AGENTS.md, ~/.codex/hooks.json, ~/.agents/plugins/marketplace.json, and ~/plugins/compressoor exist.

Codex Plugin

Install the plugin from plugins/compressoor/.codex-plugin/plugin.json.

Claude Code Plugin

Add this repository as a Claude marketplace, then install compressoor:

claude plugin marketplace add M4cs/compressoor
claude plugin install compressoor@compressoor

The Claude plugin ships:

• .claude-plugin/marketplace.json
• .claude-plugin/plugin.json
• .claude/agents/compressoor.md
• .claude/commands/compressoor.md

Standalone runtime policy

python3 skills/compressoor/scripts/install_codex_compressoor.py --force

This writes:

• ~/.codex/AGENTS.md with compressoor runtime guidance
• ~/.codex/hooks.json with SessionStart and SessionResume runtime-policy hooks
• ~/.agents/plugins/marketplace.json with a home-local compressoor marketplace entry
• ~/plugins/compressoor as a symlink to this repo's plugin directory

The installed hooks inject a mandatory compressoor session directive automatically on session start and resume. That directive is meant to reduce token use by:

• preferring tools before any outward text
• forbidding initial plans, thinking summaries, and intent statements before the first tool call
• suppressing acknowledgements and routine narration before and during tool loops
• suppressing explanations of intent before tool calls
• keeping outward answers short and professional
• using compaction tools only when reusable context actually needs shortening

If you update compressoor rules, rerun the installer so ~/.codex/hooks.json still points at the current hook scripts:

python3 skills/compressoor/scripts/install_codex_compressoor.py --force

This also makes compressoor discoverable outside this repo, because Codex can resolve it from the home-local marketplace at ~/.agents/plugins/marketplace.json.

If you also want the same note in a project AGENTS.md:

python3 skills/compressoor/scripts/install_codex_compressoor.py --force \
  --project-agents /path/to/repo/AGENTS.md

If a target AGENTS.md already exists, the installer appends the compressoor directive instead of replacing the file.

Launch Codex With Compressoor

Use the launcher if you want a Codex session bootstrapped with the compressoor runtime policy:

python3 skills/compressoor/scripts/launch_codex_compressoor.py -- -C /path/to/repo

Useful variants:

python3 skills/compressoor/scripts/launch_codex_compressoor.py --print-bootstrap
python3 skills/compressoor/scripts/launch_codex_compressoor.py --prompt "Review this repo for regressions." -- -C /path/to/repo