codex-doctor
Skill1 starsChanged 2 months agoMITView on GitHub
Analyze local Codex session telemetry and produce privacy-safe efficiency reports with actionable workflow recommendations. Use when the user asks to run Codex Doctor, inspect Codex productivity, diagnose context bloat, repository exploration, validation or retry patterns, compare recent sessions, or interpret a codex-efficiency-report HTML/JSON file. Default to local telemetry-only analysis; use the optional compact AI diagnosis only when the user explicitly requests AI interpretation.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- zjp1997720/zhijian-skillstheir own version, first seen Jul 17, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- zjp1997720/zhijian-skills★ 787same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use telemetry-only mode by default.
- Very specific: line 13
Use AI mode only when the user explicitly asks for AI diagnosis or a deeper interpretation.
- Very specific: line 14
Never use the openai provider unless the user explicitly requests it and provides the required authorization.
- Distinctive: line 23
If no analyzer directory is available, ask for its path.
- Very specific: line 24
Run from the analyzer directory and write output and, when needed, cache data to dedicated temporary or user-selected directories.
- Very specific: line 51
Do not combine --ai with --telemetry-only.
- Distinctive: line 56
Treat deterministic telemetry as the numeric source of truth.
- Distinctive: line 57
Check sample size, data quality, estimated fields, and trend direction before drawing conclusions.
- Distinctive: line 72
Prefer operational changes over more prompt text:
- Distinctive: line 75
Before broad exploration, name the initial files, commands, and acceptance conditions.
- Distinctive: line 77
After repeated failures, classify the failure and change the command, environment, input, or strategy instead of replaying the same attempt.
- Very specific: line 79
Do not automatically edit AGENTS.md, install Skills, commit changes, open or merge PRs, or change production state from a report.
- Distinctive: line 93
After a workflow change, rerun the telemetry-only report after a meaningful sample of new sessions and compare trends rather than one …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Codex Doctor
Analyze Codex usage from local session data, separate evidence from interpretation, and turn recurring patterns into small workflow changes.
Choose the analysis mode
- Use telemetry-only mode by default. It is local, deterministic, strict-privacy, and does not invoke a model.
- Use AI mode only when the user explicitly asks for AI diagnosis or a deeper interpretation. It makes one compact
codex-clidiagnosis call and may consume Codex usage. - Never use the
openaiprovider unless the user explicitly requests it and provides the required authorization. Do not use paid production APIs, production credentials, or real user data for this analysis.
Locate and run the analyzer
- Resolve the analyzer directory in this order:
- a path supplied by the user;
CODEX_DOCTOR_DIRif set;- the current workspace when it contains
bin/codex-insights.jsand the Codex Doctor package; - a narrowly scoped local path the user has already mentioned.
- If no analyzer directory is available, ask for its path. Do not scan the whole home directory or install dependencies without a reason.
- Run from the analyzer directory and write output and, when needed, cache data to dedicated temporary or user-selected directories. If the default cache location is not writable, pass an explicit
--cache-dir.
Telemetry-only example:
node ./bin/codex-insights.js report \
--telemetry-only \
--days 14 \
--limit 20 \
--no-open \
--cache-dir <report-directory>/cache \
--out-dir <report-directory>AI diagnosis example:
node ./bin/codex-insights.js report \
--ai \
--provider codex-cli \
--days 14 \
--limit 20 \
--no-open \
--cache-dir <report-directory>/cache \
--out-dir <report-directory>Do not combine --ai with --telemetry-only. Preserve the generated JSON and HTML paths in the result. Read JSON for facts and use HTML for the human-readable report; do not treat the HTML layout as the data source.
Interpret the result
- Report the analysis mode, date range, session count, output paths, and whether AI ran.
- Treat deterministic telemetry as the numeric source of truth. Treat AI output as advisory and evidence-bound.
- Check sample size, data quality, estimated fields, and trend direction before drawing conclusions.
- Separate observations, inferences, and recommendations. Do not turn a heuristic score into a claim about exact cost, quality, or time saved.
- Rank no more than three actions by expected benefit and effort. For each action, state the evidence, the smallest behavior change, and how to verify improvement.
- Distinguish recommendations that belong in global rules, project rules, a reusable Skill, or a one-off task handoff. Keep raw metrics and project-specific paths out of global rules.
Pay particular attention to these signals:
- context bloat and long sessions;
- exploration that does not converge on an affected boundary;
- validation repeated beyond the changed risk surface;
- repeated failures and retries without a changed hypothesis;
- trends that worsen in recent sessions rather than isolated outliers.
Convert findings into action
Prefer operational changes over more prompt text:
- At a phase boundary, summarize the current objective, completed evidence, unresolved risks, and next step before starting an independent sub-goal.
- Before broad exploration, name the initial files, commands, and acceptance conditions; expand only when evidence requires it and record why.
- Route validation by the changed boundary and risk. Keep low-risk feedback small and reserve integration, security, build, release, and production checks for the boundaries that require them.
- After repeated failures, classify the failure and change the command, environment, input, or strategy instead of replaying the same attempt.
Do not automatically edit AGENTS.md, install Skills, commit changes, open or merge PRs, or change production state from a report. Present the recommendation first and make those changes only when the user explicitly requests them.
Completion report
Finish with:
- conclusion first;
- analysis mode and scope;
- top findings with supporting evidence;
- up to three concrete next actions;
- what is already covered by existing rules or Skills;
- unverified areas, data-quality limits, and any environment blocker;
- exact report paths.
After a workflow change, rerun the telemetry-only report after a meaningful sample of new sessions and compare trends rather than one absolute score.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

