codex-token-guard AGENTS.md

Build codex-token-guard, a plug-and-play Codex plugin that reduces token usage during Codex sessions without reducing output quality.

The plugin should use Codex lifecycle hooks where possible, especially:

• PreToolUse
• PostToolUse
• PreCompact
• PostCompact
• UserPromptSubmit
• Stop

The plugin must be measurable. It should track token savings, blocked commands, compressed outputs, session summaries, and quality impact.

Product Requirements

Main goal

Reduce unnecessary context and tool-output tokens in Codex sessions.

Non-goals

• Do not rewrite Codex internals.
• Do not depend on unsupported Codex APIs.
• Do not aggressively remove information required for task success.
• Do not make Codex worse at coding.

Architecture

Create this structure:

codex-token-guard/
  .codex-plugin/
    plugin.json
  hooks/
    hooks.json
    pre-tool-use.ts
    post-tool-use.ts
    pre-compact.ts
    post-compact.ts
    user-prompt-submit.ts
    stop.ts
  src/
    cli.ts
    config.ts
    token-estimator.ts
    command-policy.ts
    output-compressor.ts
    session-memory.ts
    metrics.ts
    benchmark.ts
    quality.ts
  skills/
    token-guard/
      SKILL.md
  benchmarks/
    fixtures/
    tasks/
  .codex-token-guard/
    metrics.jsonl
    session.md
    decisions.md
    files-touched.json
    errors.md

Plugin behavior
1. PreToolUse

Before Bash commands run, inspect the command and classify it:
safe
expensive
dangerous
needs_confirmation

Block or warn on:
cat large files
tree
find .
grep -r
npm test
pnpm test
yarn test
bun test
large log dumps
recursive ls
printing lockfiles
printing generated files
printing node_modules
printing dist/build/.next

Suggest cheaper alternatives:
cat file.ts -> sed -n '1,160p' file.ts
find . -> rg --files | head -200
grep -r "x" . -> rg "x"
npm test -> pnpm test path/to/specific.test.ts
tree -> rg --files | sed -n '1,200p'

2. PostToolUse
Compress noisy outputs.

keep:
errors
stack traces
file paths
line numbers
failed assertions
test names
compiler errors
diff summaries
important warnings

Remove:
repeated lines
progress bars
install noise
ANSI colors
huge successful logs
dependency tree spam
duplicated stack frames

3. PreCompact
Generate a clean session summary:
# Session State

## Goal

## Current Status

## Key Decisions

## Files Touched

## Bugs / Errors

## Important Context To Preserve

## Next Steps

4. Stop
Persist durable session memory:
.codex-token-guard/session.md
.codex-token-guard/decisions.md
.codex-token-guard/files-touched.json
.codex-token-guard/errors.md
.codex-token-guard/metrics.jsonl

Metrics
Track:
estimated_raw_tokens
estimated_sent_tokens
estimated_saved_tokens
savings_percentage
commands_blocked
commands_rewritten
outputs_compressed
raw_output_tokens
compressed_output_tokens
compression_ratio
session_duration
quality_flags

Expose CLI commands:
codex-token-guard init
codex-token-guard install
codex-token-guard mode safe
codex-token-guard mode balanced
codex-token-guard mode aggressive
codex-token-guard stats
codex-token-guard snapshot
codex-token-guard restore
codex-token-guard benchmark

Modes

safe

Only block obvious waste.

balanced

Default mode. Compress noisy output and suggest targeted commands.

aggressive

Strict budgets, strong output compression, more blocking.

Quality protection

Never remove:
actual error messages
file paths
line numbers
API names
function names
test names
user instructions
recent edits
architecture decisions

If uncertain, preserve the content.

Benchmarking

Add a benchmark runner that compares:
vanilla Codex
vs
Codex + Token Guard

Metrics:
token savings %
task success
latency
number of retries
number of failed attempts

Generate:
benchmarks/results/report.md

Implementation Requirements

Use TypeScript.

Use fast local token estimation. If exact tokenizer is unavailable, use a configurable approximation:
1 token ≈ 4 characters

Store metrics as JSONL so they are easy to inspect.

Keep hook scripts fast. Any hook should fail open unless in aggressive mode.

Important product rule: **default to quality over savings**.

The MVP should prove this:

```txt
20–40% fewer wasted tokens
near-zero quality loss
easy install
visible savings dashboard