Built-in context/config investigator with safe cleanup for AGENTS.md, plugins, skills, and MCP

Summary

Codex needs a built-in context and configuration investigator that can explain everything loaded into a session and safely help users remove stale, duplicated, or conflicting configuration.

In my current setup, the 256k context window pushed me to manually audit and clean up years of agent configuration: AGENTS.md files and their references, plugins, skills, MCP servers, and instructions that had become obsolete, duplicated, or contradictory. The cleanup recovered useful context and made the environment easier to reason about, but doing it by hand was slow and error-prone.

This problem will affect more long-time users as Codex configurations accumulate.

Proposed feature

Add an official command or UI such as:

codex context audit
# or
codex doctor context

It should inspect both global and repository-level configuration and report:

1. Everything loaded into the session

• global and repository AGENTS.md files
• transitive files referenced by those instructions
• active plugins and skills
• configured MCP servers and exposed tools
• other instruction or configuration sources

1. Where context is being spent

• source path and precedence
• estimated token cost for each source
• the total static context cost before the conversation begins
• which MCP/tool definitions contribute the most

1. Potential problems

• stale or missing references
• instructions that are duplicated across scopes
• conflicting rules, with their precedence explained
• plugins, skills, or MCP servers that appear unused or redundant
• legacy configuration keys and superseded formats

1. A safe cleanup plan

• confidence and reasoning for every recommendation
• a dry-run mode
• a clear diff before any change
• explicit confirmation before deleting or rewriting anything
• backups and rollback support
• machine-readable JSON output for automation

Example output

Static context before first prompt: ~48,200 tokens

AGENTS.md and references       18,400
Plugin instructions            9,700
Skills                         7,600
MCP tool definitions          12,500

Findings:
- 3 duplicated instruction blocks
- 2 references point to missing files
- 1 global rule conflicts with a repository rule
- 4 MCP tools overlap with tools from another server
- 6 skills have not been referenced or invoked recently

Run `codex context audit --plan` to preview a cleanup diff.

Why this should be built in

An external cleanup script cannot reliably know Codex's actual loading order, precedence rules, tokenization, plugin state, skill discovery behavior, or final MCP tool schema. Codex already has the information required to produce an authoritative report.

Larger context windows help, but they do not solve configuration debt. A built-in investigator would recover usable context, reduce conflicting instructions, improve startup performance, and make agent behavior easier to trust.

This should be an official Codex capability rather than another one-off community cleanup script.

Related issues

This is broader than requests to disable the AGENTS.md pipeline, such as #5983, and complementary to larger-context requests such as #19464. The goal is to make the full effective configuration visible, measurable, and safely maintainable regardless of the model's context-window size.