codex-hygiene-skill

Codex Hygiene Skill

Skill by ara.so — Codex Skills collection.

This skill provides expertise in using codex-hygiene, a tool for auditing and tuning Codex Desktop context and tool surfaces. It measures recent telemetry, reviews MCP/app/skill availability, and helps keep long-running goal workflows scoped to current work.

What Codex Hygiene Does

Codex Hygiene is a diagnostic skill that:

• Measures token usage: Queries Codex Desktop SQLite telemetry databases to show recent token consumption per thread and window
• Audits tool availability: Distinguishes actual tool calls from tool availability, enabled state from cached inventory
• Identifies bottlenecks: Helps correlate elevated usage with app surface size, MCP/plugin state, snapshot reuse, stale project stanzas, long-thread replay, or background fan-out
• Suggests reversible hygiene: Recommends cleanup steps without deleting logs, caches, or projects
• Maintains quality: Keeps long-running goal work quality-aware by narrowing replay and tool scope

Installation

Install codex-hygiene into your Codex skills directory:

# Create skills directory if needed
mkdir -p "$HOME/.agents/skills"

# Clone the repository
git clone https://github.com/sunflower-of-parchman/codex-hygiene.git \
  "$HOME/.agents/skills/codex-hygiene"

After installation, invoke the skill with $codex-hygiene. Codex normally detects newly installed skills automatically. Restart Codex Desktop if the skill doesn't appear.

Key Commands

Measure Context Usage

The primary command is measure_codex_context.sh, which queries Codex telemetry:

# Basic measurement (recent activity)
"$HOME/.agents/skills/codex-hygiene/scripts/measure_codex_context.sh"

# Measure specific window (last 5 interactions)
"$HOME/.agents/skills/codex-hygiene/scripts/measure_codex_context.sh" 5

# Measure specific window with more history
"$HOME/.agents/skills/codex-hygiene/scripts/measure_codex_context.sh" 30

# Measure specific thread in window
"$HOME/.agents/skills/codex-hygiene/scripts/measure_codex_context.sh" 5 <thread_id>

Script Parameters

• First argument: Number of recent entries to examine (default: recent activity)
• Second argument: Specific thread ID to analyze (optional)

Environment Variables

# Custom Codex data location
export CODEX_HOME="$HOME/.codex-custom"

# Skill installation directory (if not default)
export SKILL_DIR="$HOME/my-custom-path/codex-hygiene"

Understanding Output

The measurement script provides compact counts covering:

Token Telemetry

• Input tokens by thread
• Output tokens by thread
• Total tokens per interaction
• Window-level aggregates

Tool Availability

• Number of tools reported as available
• Tools actually called
• MCP servers enabled vs. cached
• App integrations active

Context Sources

• Snapshot reuse frequency
• Project stanza count
• Thread replay depth
• Background task count

Safety note: The script does NOT dump full logs, configs, tool schemas, secrets, or environment values.

Configuration

Codex Configuration File

Codex Hygiene reads but does not modify ~/.codex/config.toml. Always back up before manual edits:

# Backup your config
cp ~/.codex/config.toml ~/.codex/config.toml.backup

# View current MCP servers
cat ~/.codex/config.toml | grep -A 10 "\[mcp\]"

Custom Data Locations

If your Codex data lives elsewhere:

export CODEX_HOME="/path/to/codex/data"
"$SKILL_DIR/scripts/measure_codex_context.sh"

Common Patterns

Diagnose High Token Usage

# Measure recent threads
SKILL_DIR="$HOME/.agents/skills/codex-hygiene"
"$SKILL_DIR/scripts/measure_codex_context.sh" 10

# Check if usage correlates with:
# - Many MCP servers enabled
# - Large tool availability surface
# - Deep thread replay
# - Stale project contexts

Audit MCP Server State

# List MCP servers (requires jq and codex CLI)
codex mcp list

# Check server status in config
cat ~/.codex/config.toml | grep -A 5 "\\[mcp.servers"

# Compare enabled vs. actually-called tools in telemetry
"$SKILL_DIR/scripts/measure_codex_context.sh" 5

Optimize Long-Running Threads

For threads with elevated token usage:

# Measure specific thread
"$SKILL_DIR/scripts/measure_codex_context.sh" 20 thread_abc123

# Review recommendations in references/long-thread-replay.md
cat "$SKILL_DIR/references/long-thread-replay.md"

# Consider:
# - Starting fresh thread for new subtask
# - Disabling unused MCP servers temporarily
# - Removing stale project paths from config

Pre-Deploy Hygiene Check

Before starting a large goal or project:

# 1. Measure baseline
"$SKILL_DIR/scripts/measure_codex_context.sh" 5

# 2. Review MCP servers - disable unused
codex mcp list
# Edit config to comment out unused servers

# 3. Clean stale project contexts
# Review ~/.codex/config.toml [projects] section

# 4. Restart Codex Desktop to apply changes

Real Code Examples

Shell Integration

#!/bin/bash
# Add to your .bashrc or .zshrc for quick hygiene checks

codex_measure() {
    local skill_dir="$HOME/.agents/skills/codex-hygiene"
    if [ -d "$skill_dir" ]; then
        "$skill_dir/scripts/measure_codex_context.sh" "${1:-10}"
    else
        echo "codex-hygiene not installed"
    fi
}

# Usage: codex_measure 5

Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-push
# Check Codex hygiene before pushing code

SKILL_DIR="$HOME/.agents/skills/codex-hygiene"
if [ -f "$SKILL_DIR/scripts/measure_codex_context.sh" ]; then
    echo "Running Codex hygiene check..."
    "$SKILL_DIR/scripts/measure_codex_context.sh" 3
fi

Periodic Monitoring Script

#!/bin/bash
# monitor_codex_hygiene.sh
# Run daily to track token usage trends

SKILL_DIR="$HOME/.agents/skills/codex-hygiene"
LOG_FILE="$HOME/.codex-hygiene-history.log"

timestamp=$(date +"%Y-%m-%d %H:%M:%S")
echo "=== $timestamp ===" >> "$LOG_FILE"
"$SKILL_DIR/scripts/measure_codex_context.sh" 5 >> "$LOG_FILE" 2>&1
echo "" >> "$LOG_FILE"

# Review trends
tail -50 "$LOG_FILE"

Troubleshooting

Script Not Found

Problem: command not found: measure_codex_context.sh

Solution:

# Verify installation
ls "$HOME/.agents/skills/codex-hygiene/scripts/"

# Use full path
SKILL_DIR="$HOME/.agents/skills/codex-hygiene"
"$SKILL_DIR/scripts/measure_codex_context.sh"

# Or add to PATH
export PATH="$HOME/.agents/skills/codex-hygiene/scripts:$PATH"

SQLite Database Locked

Problem: database is locked

Solution:

# Close Codex Desktop
# Wait 5 seconds
# Run measurement again
"$SKILL_DIR/scripts/measure_codex_context.sh" 5

# The script uses -readonly flag, but active writes can block

No Telemetry Data

Problem: Script shows no data or zero counts

Solution:

# Check if Codex telemetry database exists
ls -lh ~/.codex/telemetry.db

# Check if CODEX_HOME is set incorrectly
echo $CODEX_HOME

# Verify Codex Desktop has been used recently
# (telemetry is only written during active use)

jq or codex CLI Not Found

Problem: Optional tools missing

Solution:

# Install jq (macOS)
brew install jq

# Install jq (Linux)
sudo apt-get install jq  # Debian/Ubuntu
sudo yum install jq      # RedHat/CentOS

# Verify codex CLI
which codex

# These are optional - core measurement works without them

Permission Denied

Problem: Cannot read telemetry database

Solution:

# Check permissions
ls -l ~/.codex/telemetry.db

# Fix if needed (database should be user-readable)
chmod 644 ~/.codex/telemetry.db

# Verify ownership
ls -l ~/.codex/

Advanced Usage

Custom Telemetry Queries

The measurement script uses read-only SQLite queries. You can run custom queries:

# Interactive SQLite session
sqlite3 -readonly ~/.codex/telemetry.db

# Example: List all tables
.tables

# Example: Show schema
.schema

# Example: Count total interactions
SELECT COUNT(*) FROM interactions;

# Exit
.quit

Combining with Other Tools

# Export measurement to JSON for analysis
"$SKILL_DIR/scripts/measure_codex_context.sh" 20 | \
  awk '/tokens/{print}' | \
  tee codex-usage.txt

# Watch telemetry in real-time
watch -n 5 "$SKILL_DIR/scripts/measure_codex_context.sh" 3

# Compare before/after MCP changes
"$SKILL_DIR/scripts/measure_codex_context.sh" 5 > before.txt
# Make MCP config changes and restart Codex
"$SKILL_DIR/scripts/measure_codex_context.sh" 5 > after.txt
diff before.txt after.txt

References

The skill includes detailed references:

• references/remediation.md: Step-by-step cleanup recommendations
• references/long-thread-replay.md: Managing token usage in long conversations

# View remediation guide
cat "$HOME/.agents/skills/codex-hygiene/references/remediation.md"

# View long-thread guide
cat "$HOME/.agents/skills/codex-hygiene/references/long-thread-replay.md"

Safety & Best Practices

1. Read-only by default: Scripts use sqlite3 -readonly flag
2. No secrets dumped: Output excludes configs, schemas, env vars, API keys
3. Backup configs: Always backup ~/.codex/config.toml before editing
4. Reversible actions: Recommendations focus on disable/restart, not delete
5. Version awareness: Telemetry schemas may change across Codex versions

Testing

Run the included test suite:

cd "$HOME/.agents/skills/codex-hygiene"
bash tests/measure_codex_context_test.sh

Compatibility

• OS: macOS, Linux, Unix-like systems
• Requirements: Bash, sqlite3, Perl, awk, sort
• Optional: jq, codex CLI for enhanced app-cache and plugin summaries
• Codex: Designed for Codex Desktop with local telemetry databases

When to Use This Skill

Use codex-hygiene when:

• Codex Desktop feels slow or unresponsive
• Token usage seems unexpectedly high
• You want to audit which tools are actually being called
• Long-running threads are accumulating context
• You're debugging MCP server configuration
• You need to optimize before a large coding session
• You want visibility into Codex's internal state

---

Project: sunflower-of-parchman/codex-hygiene
License: MIT