Skip to content

docs: plan Codex GUI restart utility#65

Merged
gaelic-ghost merged 2 commits into
mainfrom
docs/codex-gui-restart-plan
Jun 6, 2026
Merged

docs: plan Codex GUI restart utility#65
gaelic-ghost merged 2 commits into
mainfrom
docs/codex-gui-restart-plan

Conversation

@gaelic-ghost
Copy link
Copy Markdown
Owner

@gaelic-ghost gaelic-ghost commented Jun 6, 2026

Summary:

  • Add the Codex GUI restart utility plan to ROADMAP.md.
  • Record the codex-utilities desktop bridge planning surface.

Verification:

  • uv run scripts/validate_socket_metadata.py

Summary by CodeRabbit

  • Documentation
    • Updated planning documentation to reflect upcoming Codex GUI restart coordination capabilities.
    • Clarified the division of responsibilities between components for managing system restarts.
    • Documented three new tools enabling restart requests, cancellations, and status checks.
    • Added detailed specifications covering restart coordination behavior, error handling, and runtime contract requirements for the new functionality.

@gaelic-ghost gaelic-ghost added the documentation Improvements or additions to documentation label Jun 6, 2026
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 6, 2026

Review Change Stack

Warning

Review limit reached

@gaelic-ghost, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 55 minutes and 12 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 74cd9437-7c03-41bb-a81a-a72a9370e310

📥 Commits

Reviewing files that changed from the base of the PR and between 3fe0d53 and 6831bd7.

📒 Files selected for processing (3)
  • ROADMAP.md
  • plugins/codex-utilities/AGENTS.md
  • plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md
📝 Walkthrough

Walkthrough

This PR updates planning documentation for Codex GUI restart coordination. It adds Milestone 11 roadmap items for restart tools and a narrow skill, clarifies operational responsibility split between the installed app and utilities plugin, specifies MCP API surface and agent skill rules, and defines runtime contracts and implementation tracking.

Changes

Codex GUI Restart Coordination Planning

Layer / File(s) Summary
Milestone 11 Roadmap and Operational Boundaries
ROADMAP.md, plugins/codex-utilities/AGENTS.md
ROADMAP.md establishes Milestone 11 items for restart request/cancel/status tools and a narrow delegation skill, specifies if-idle vs when-idle ordering, and records the planning decision. AGENTS.md clarifies that the installed app owns restart waiting/execution while this plugin owns MCP tools and skill policy, and prohibits when-idle implementation via process polling.
MCP API and Agent Skill Definition
plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md
The desktop bridge MCP surface gains three restart coordinator tools (request_codex_gui_restart, cancel_codex_gui_restart, get_codex_gui_restart_status), and a new codex-gui-restart agent skill specifies when to invoke those tools, how to handle if-idle vs when-idle semantics, and explicit blocking behavior when app-side thread-status support is unavailable.
Runtime Contract and Implementation Plan
plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md
The MCP shim runtime contract is extended with restart-specific messaging ("Restart blocked …", "Restart scheduled …"), a full "Codex GUI Restart Plan" describes the responsibility split and required thread-state parameters, open questions clarify app capability uncertainties, and implementation slice 6 registers the restart tools/skill alongside the current decision affirming that when-idle requires an app-side thread-status source.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A restart shall bloom in the Codex GUI,
Where if-idle first, then when-idle will fly,
MCP tools dance with skill and care,
Thread-status awaits from the app's corner there,
Coordination split: we ask, they execute with flair! 🔄

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: plan Codex GUI restart utility' accurately and specifically summarizes the main change—adding planning documentation for a Codex GUI restart utility to roadmap and agent guidance files.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/codex-gui-restart-plan

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

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3fe0d53b3e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md Outdated
@gaelic-ghost gaelic-ghost force-pushed the docs/codex-gui-restart-plan branch from 3fe0d53 to 6831bd7 Compare June 6, 2026 18:54
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md (1)

147-149: 💤 Low value

Consider minor rewording to reduce repetition.

The three consecutive bullets starting with "Whether" create slight stylistic repetition. This is a very minor point, but you could rephrase one or two for variety if desired:

  • "Whether a supported Codex App Server or GUI endpoint can report thread status outside the current assistant turn."
  • "Should when-idle use persistent app state or remain memory-only until the coordinator is proven?"
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md` around lines
147 - 149, Reword the repeated bullets for variety: change the first sentence
"Whether a supported Codex App Server or GUI endpoint can report thread status
outside the current assistant turn." to an active question or alternative
phrasing (e.g., "Can a supported Codex App Server or GUI endpoint report thread
status outside the current assistant turn?") and rephrase the second bullet
about when-idle to match the suggested form ("Should `when-idle` use persistent
app state or remain memory-only until the coordinator is proven?"), keeping
references to `when-idle` and "Codex App Server/GUI endpoint" so the meaning and
identifiers remain clear.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md`:
- Around line 147-149: Reword the repeated bullets for variety: change the first
sentence "Whether a supported Codex App Server or GUI endpoint can report thread
status outside the current assistant turn." to an active question or alternative
phrasing (e.g., "Can a supported Codex App Server or GUI endpoint report thread
status outside the current assistant turn?") and rephrase the second bullet
about when-idle to match the suggested form ("Should `when-idle` use persistent
app state or remain memory-only until the coordinator is proven?"), keeping
references to `when-idle` and "Codex App Server/GUI endpoint" so the meaning and
identifiers remain clear.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b038dc3d-71e3-4a75-b7bb-e3f1e2ab140b

📥 Commits

Reviewing files that changed from the base of the PR and between d57c40b and 3fe0d53.

📒 Files selected for processing (3)
  • ROADMAP.md
  • plugins/codex-utilities/AGENTS.md
  • plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md

@gaelic-ghost gaelic-ghost merged commit 35a805a into main Jun 6, 2026
2 checks passed
@gaelic-ghost gaelic-ghost deleted the docs/codex-gui-restart-plan branch June 6, 2026 18:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant