Codex Hygiene

A small Codex skill for auditing and tuning Codex Desktop context and tool surfaces.

Use it to measure recent Codex Desktop telemetry, review MCP/app/skill availability, and keep long-running goal workflows scoped to the current work.

Community skill for local Codex setup hygiene.

What It Does

• Measures recent Codex Desktop tool-list and per-thread token telemetry with read-only SQLite queries.
• Helps identify whether elevated usage correlates with app surface size, MCP/plugin state, snapshot reuse, stale project stanzas, long-thread replay, or background fan-out.
• Distinguishes actual tool calls from tool availability, enabled state from cached inventory, and thread-local token changes from mixed-thread totals.
• Suggests reversible hygiene steps instead of deleting logs, caches, or projects.
• Keeps long-running goal work quality-aware: narrow replay and tool scope without blindly lowering reasoning, banning subagents, or avoiding real source evidence.

Install

Clone this repo into the current user-level Codex skills folder:

mkdir -p "$HOME/.agents/skills"
git clone https://github.com/sunflower-of-parchman/codex-hygiene.git \
  "$HOME/.agents/skills/codex-hygiene"

Then invoke $codex-hygiene. Codex normally detects newly installed skills automatically; restart Codex only if it does not appear.

Quick Measurement

From a shell:

SKILL_DIR="$HOME/.agents/skills/codex-hygiene"
"$SKILL_DIR/scripts/measure_codex_context.sh"

Use a specific window or thread id:

"$SKILL_DIR/scripts/measure_codex_context.sh" 5
"$SKILL_DIR/scripts/measure_codex_context.sh" 30
"$SKILL_DIR/scripts/measure_codex_context.sh" 5 <thread_id>

The script prints compact counts only. It does not dump full logs, configs, tool schemas, secrets, or environment values.

Compatibility

• Designed for macOS and Unix-like Codex Desktop environments with Bash, sqlite3, Perl, awk, and sort.
• Uses jq and the codex CLI when available for app-cache and plugin state summaries.
• Treats local telemetry databases and cache layouts as version-dependent diagnostic inputs, not stable APIs or billing records.
• Supports custom Codex data locations through CODEX_HOME; use the skill's actual install path when it is not under $HOME/.agents/skills.

Safety Defaults

• Starts read-only.
• Uses sqlite3 -readonly.
• Avoids printing full config, full logs, app schemas, MCP schemas, or .env values.
• Recommends backing up ~/.codex/config.toml before any config edit.
• Treats delete/restart/disable actions as explicit-user-approval work.

Contents

SKILL.md
agents/openai.yaml
scripts/measure_codex_context.sh
tests/measure_codex_context_test.sh
references/remediation.md
references/long-thread-replay.md

Codex References

• Agent Skills
• Configuration reference
• MCP configuration

License

MIT