A read-only Codex skill that provides local diagnostics and activity reviews by analyzing telemetry data to help users understand and optimize their Codex usage.

Stars

249

7-day growth

No data

Forks

7

Open issues

0

License

MIT

Last updated

2026-07-19

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It offers a privacy-first, open-source tool for auditing Codex behavior directly on the user's machine, with structured reports that separate evidence from interpretation and recommend reversible hygiene steps.

Who it is for

  • Codex power users seeking to reduce token waste
  • Developers who manage multiple Codex plugins and MCP configurations
  • Privacy-conscious individuals who want local usage analytics without external data sharing

Use cases

  • Review recent Codex activity over a custom 1–90 day window
  • Identify which plugins consume the most tool runtime or serialized output
  • Generate a Markdown or JSON report for team audits or personal optimization
  • Prepare a safe, reversible plan to clean up configuration or disable unused plugins

Strengths

  • Read-only operation with sqlite3 -readonly ensures no data modification
  • Separates observed evidence, interpretation, and unknowns for clarity
  • Supports both quick compact measurements and detailed period reviews with flexible time ranges
  • Maintains full privacy by keeping prompts, responses, paths, and secrets local

Considerations

  • Only compatible with macOS and Unix-like environments; no Windows support
  • Relies on version-dependent telemetry schemas and cache layouts that may break across Codex updates
  • Cannot provide billing attribution or real-time monitoring

README quick start

Codex Hygiene

A compact, read-only Codex skill for current-context diagnostics and private local activity reviews.

The original measurement returns small counts from recent telemetry. An explicit 1-90 day review returns Markdown or JSON that describes how Codex was used, which sources support the report, and where the evidence ends.

What It Does

  • Runs the original compact measurement for recent tool-list and per-thread token telemetry.
  • Builds a period review with source coverage and supported prior-window comparisons.
  • Separates observed evidence, interpretation, and unknowns.
  • Enriches period reviews with task timing, relative output weight, verification commands, explicit compactions, and observed SKILL.md reads.
  • Reviews the current Codex profile, including every installed plugin, MCP state, Apps availability, and project-stanza counts.
  • Suggests scoped, reversible hygiene steps after measurement.

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 usually detects newly installed skills automatically. Restart Codex if the skill has not appeared.

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 

The script prints compact counts. Full logs, configs, tool schemas, secrets, and environment values stay private.

Activity Review

Choose an explicit lookback from 1 to 90 days:

SKILL_DIR="$HOME/.agents/skills/codex-hygiene"
python3 "$SKILL_DIR/scripts/codex_activity_review.py" --days 1

Use any other window or generate machine-readable output:

python3 "$SKILL_DIR/scripts/codex_activity_review.py" --days 14 --format json

The review reads compact SQLite telemetry and enriches it from rollout records inside CODEX_HOME. Enrichment runs by default at every candidate size and reads files backward only to the prior comparison boundary. It adds task timing, relative serialized tool-output weight, verification-command counts

Description

Codex skill for auditing and tuning Codex Desktop context/tool surfaces

Related repositories

Similar projects matched by category, topics, and programming language.

powerycy
Featured
powerycy GitHub avatar

goutoujunshi

An AI relationship coach that provides emotional support, relationship science, and actionable strategies through a multidisciplinary knowledge base.

Python
1,174
Kappaemme-git
Kappaemme-git GitHub avatar

codex-first-customer-finder-skill

A Codex skill that converts a startup URL or product idea into a qualified shortlist of potential first customers by analyzing public pain, demand, and timing signals.

Python
932
0xsline
0xsline GitHub avatar

OpenChatCut

OpenChatCut is an open-source, local-first AI video editor with a real multitrack timeline, conversational agents, and MCP support, enabling AI-assisted editing that remains fully editable.

TypeScript
579