docs(codex): warn that mutating CLI commands reformat config.toml

[latreon]

Summary

.codex/config.toml kept showing up as locally modified with no intentional edit behind it: running a mutating Codex CLI subcommand (e.g. codex mcp add chrome-devtools ...) rewrites the file in place, stripping every comment and reflowing the TOML formatting — pure tool-driven drift on whoever's machine ran the command, not a real change.

• Added a caution note in the header directing personal MCP servers and local overrides to the user's own ~/.codex/config.toml instead of editing this project-local template with mutating CLI commands.
• Added chrome-devtools as a new commented-out optional entry alongside the existing supabase/firecrawl/fal-ai/cloudflare examples — it's a genuinely useful MCP server worth documenting the same way as its siblings.

Diff is a comment-only addition — 9 lines, no functional config changes.

Test plan

• node tests/codex-config.test.js — 5/5 pass
• Parsed the file with @iarna/toml to confirm it's still valid TOML and chrome-devtools stays inert (commented out, not a parsed table)
• node tests/run-all.js — 3110/3110 pass

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 389b5258-dd3d-4102-9857-812b7baa73f3

📥 Commits

Reviewing files that changed from the base of the PR and between 754b8dd and 7052d65.

📒 Files selected for processing (1)

• .codex/config.toml

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Greptile Review

🔇 Additional comments (2)

.codex/config.toml (2)

11-15: LGTM!

---

94-97: LGTM!

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added guidance about protecting local configuration overrides from CLI rewrites.
  • Added a commented template for configuring the Chrome DevTools MCP server.

Walkthrough

The Codex configuration template now warns that MCP-related CLI commands can rewrite the file and directs personal overrides to ~/.codex/config.toml. It also adds a commented Chrome DevTools MCP server example.

Changes

Codex configuration template

Layer / File(s)	Summary
Configuration guidance and MCP example .codex/config.toml	Adds comments about in-place rewriting and user-level overrides, plus a commented [mcp_servers.chrome-devtools] configuration using chrome-devtools-mcp@latest.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Suggested reviewers: affaan-m, affaan-m

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: documenting that mutating Codex CLI commands can rewrite config.toml.
Description check	✅ Passed	The description matches the diff and objectives, describing the warning note, local override guidance, and commented chrome-devtools example.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds 9 comment-only lines to .codex/config.toml with no functional configuration changes. It documents a known developer pain-point (mutating Codex CLI subcommands rewriting and de-formatting the file) and adds chrome-devtools-mcp as a new commented-out optional MCP server example alongside the existing supabase/firecrawl/fal-ai/cloudflare entries.

• Caution note (lines 12–15): Warns contributors that codex mcp add and similar mutating commands rewrite the file in place, stripping comments and reformatting TOML; redirects personal overrides to ~/.codex/config.toml.
• New optional entry (lines 95–97): Adds chrome-devtools-mcp@latest as a commented-out example; the package is maintained by Google LLC under the ChromeDevTools GitHub org (2.2M weekly downloads), consistent with the repo's supply-chain policy.

Confidence Score: 5/5

Safe to merge — the change is comment-only with no active configuration altered.

Every line added is either a TOML comment or part of a commented-out table block. The caution note is accurate, and the chrome-devtools-mcp package is an officially maintained Google LLC project under the ChromeDevTools GitHub org, consistent with the repo's supply-chain stance. No runtime behaviour changes at all.

No files require special attention.

Important Files Changed

Filename	Overview
.codex/config.toml	Comment-only additions: a caution header about CLI-driven file rewrites, and a new commented-out chrome-devtools-mcp entry. No active configuration changed.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer runs mutating CLI\ne.g. codex mcp add] --> B{Which config file?}
    B -->|Project-local .codex/config.toml| C[File rewritten in place\nComments stripped\nFormatting lost]
    B -->|User-level ~/.codex/config.toml| D[Only personal config affected\nProject template stays intact]
    C --> E[Unintended diff appears in repo]
    D --> F[Project template unchanged]
    style C fill:#ffcccc
    style E fill:#ffcccc
    style D fill:#ccffcc
    style F fill:#ccffcc

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Developer runs mutating CLI\ne.g. codex mcp add] --> B{Which config file?}
    B -->|Project-local .codex/config.toml| C[File rewritten in place\nComments stripped\nFormatting lost]
    B -->|User-level ~/.codex/config.toml| D[Only personal config affected\nProject template stays intact]
    C --> E[Unintended diff appears in repo]
    D --> F[Project template unchanged]
    style C fill:#ffcccc
    style E fill:#ffcccc
    style D fill:#ccffcc
    style F fill:#ccffcc

Loading

_{Reviews (1): Last reviewed commit: "docs(codex): warn that mutating CLI comm..." | Re-trigger Greptile}

[daltino]

This PR adds a helpful warning to the config.toml file, explaining that mutating Codex CLI commands rewrite the file and strip comments/formatting. The note also provides practical guidance to use ~/.codex/config.toml for personal MCP servers or overrides, which is a thoughtful addition. The change is clear and aligns with the repo's focus on improving user documentation.