Codex PhaseRing

简体中文

Codex PhaseRing is a Windows-first VS Code extension for customizable, project-owned Codex phases. It includes five editable Markdown templates—Free, Discussion, Planning, Implementation, and Verification—or you can add your own. PhaseRing automatically discovers the phase files, lets you switch from the status bar, and reinjects the selected phase on every UserPromptSubmit without starting a new chat.

Codex PhaseRing is an independent, unofficial open-source project. It is not affiliated with, endorsed by, or sponsored by OpenAI.

Why PhaseRing

Long coding conversations move repeatedly between discussion, planning, implementation, and verification. PhaseRing keeps that transition explicit and controlled by the user:

five ready-to-use phase templates, treated as starting points rather than a prescribed workflow;
edit the included Markdown or add your own phase files—PhaseRing discovers them automatically;
one project-level phase shared by every Codex chat in that project;
no automatic phase progression;
no new chat when switching phases;
complete phase instructions reinjected on every user message;
visible Review required, Pending, Active, and Error states backed by real Hook receipts;
editable project-owned Markdown instead of a fixed workflow engine.

AGENTS.md and PhaseRing

AGENTS.md is the right place for stable, repository-wide instructions such as coding conventions, build commands, and review rules. Codex discovers that instruction chain when a session starts. PhaseRing uses the same approachable customization model—plain Markdown owned by your project—for a different job: dynamic working phases.

Use AGENTS.md for durable project policy and .phasering/modes/ for the temporary goals, responsibilities, and boundaries of the current phase. Start with the five included templates, reshape them to match your workflow, or add entirely new phases. PhaseRing scans the directory and adds valid phase documents to the status-bar picker automatically; the selected document is then reinjected on every UserPromptSubmit.

When a phase switch succeeds but does not take effect

PhaseRing started from a simple workflow: keep discussion, planning, implementation, and verification instructions in separate Markdown files, reference the current file from AGENTS.md, and change that reference whenever the work moves to another phase. The first prototype automated phase discovery and switched the AGENTS.md reference from VS Code. That made selection fast, but it did not guarantee that an existing Codex chat would observe the new phase immediately: AGENTS.md is designed for stable repository instructions discovered with the session instruction chain, not as a per-prompt phase switch.

The current design leaves AGENTS.md stable and uses a UserPromptSubmit Hook for the dynamic layer. Once the Hook is trusted and Active, a status-bar switch takes effect on the next user message, and the selected phase is reinjected on every later message, including in an existing long-running chat. This solves several closely related problems:

switch Codex phases without manually editing AGENTS.md or starting a new chat;
make a selected discussion, planning, implementation, or verification phase take effect on the next prompt;
keep temporary agent goals, responsibilities, and boundaries persistent across long conversations;
customize phase instructions as project-owned Markdown and switch them quickly from the VS Code status bar;
use PhaseRing together with AGENTS.md: stable global policy from AGENTS.md, dynamic per-prompt phase instructions from PhaseRing.

Screenshots

Choose an editable, project-wide phase from the status bar:

Selecting a PhaseRing phase from the VS Code status bar

The selected phase is visible in the Codex reply while a real Hook receipt marks it as Active:

Planning Phase injected into a Codex conversation with Active status

Install from a VSIX

Download the latest VSIX from GitHub Releases.
In VS Code, run Extensions: Install from VSIX....
Open exactly one project folder.
Run PhaseRing: Initialize Project.
Review and trust the project Hook when Codex asks. If the Hook has not loaded, run Developer: Reload Window.
Select the PhaseRing status bar item, choose a phase, and send the next Codex message.

Windows Hook trust workaround

Known Codex/VS Code issue: On our Windows test machine, a single Hook approval could remain effective only for some existing or newly opened chats. VS Code and Codex CLI sometimes recorded the same project path separately, including variants that differed only by drive-letter case such as C:\... and c:\.... This is an observed client trust/loading issue, not a PhaseRing Hook requirement, and has not been reproduced across multiple machines.

If the next message does not change PhaseRing to Active, use this workaround:

In VS Code, open the Codex Hook review screen when prompted and trust the PhaseRing project Hook.
Open a terminal in the same project, start Codex CLI, run /hooks, and review and trust the same project Hook there as well.
If /hooks lists two project-path variants, make sure both are trusted. Only trust definitions whose command points to this project's .codex/hooks/phasering.ps1.
In VS Code, run Developer: Reload Window.
Return to the chat or open a new chat, send one message, and confirm that the status becomes Active.

If one approval already produces Active, no duplicate trust entry is required. OpenAI's documented behavior is to trust the exact current Hook definition by hash; the two-entry procedure above is only a temporary compatibility workaround for the observed Windows client issue.

Default project files

First initialization creates:

.phasering/
  README.md
  modes/
    00-free.md
    10-discussion.md
    20-planning.md
    30-implementation.md
    40-verification.md
  runtime/
    current.json
    health.json  # after the first Hook run
.codex/
  hooks.json
  hooks/
    phasering.ps1

The generated project guide is bilingual. Free, Discussion, Planning, Implementation, and Verification are editable starter templates, not a required workflow. Default phase documents and all extension UI are English, but users may rewrite the templates in any language or add new UTF-8 Markdown files under .phasering/modes/. Valid files are discovered automatically and appear in the status-bar picker.

Existing files are never overwritten, and reinitialization does not restore optional phases that the user deleted.

Runtime state under .phasering/runtime/ is local and added to .gitignore. Phase documents under .phasering/modes/ may be committed when a team wants to share them.

Phase document format

UTF-8 Markdown;
first non-empty line must be an H1;
first body paragraph becomes the picker description;
files are scanned non-recursively from .phasering/modes/*.md;
numeric filename prefixes control ordering;
maximum size is 32 KiB.

The complete raw Markdown file is injected into Codex. Markdown comments are therefore also model-visible and should not contain hidden translations or instructions.

Status model

Initialize: the project has not been initialized.
Review required: the Hook definition needs review or no real receipt exists yet.
Pending: the phase selection, phase content, or Hook version changed after the last matching receipt.
Active: the latest successful receipt matches the current selection, content hash, and Hook version.
Error: the latest attempt or project state is invalid.

Active is not based on a timer. It records the latest real matching injection.

Privacy and security

User prompts and chat transcripts are not stored by PhaseRing.
health.json stores only minimal phase, version, hash, timestamp, turn ID, and error information.
The project Hook must be reviewed and trusted through Codex.
Existing .codex/hooks.json content is preserved; PhaseRing only merges its own handler and creates a backup before changes.
Phase files are validated for UTF-8, size, H1 structure, path containment, and symbolic-link escapes before injection.

Current support

Windows and Windows PowerShell 5.1;
VS Code single-root workspaces;
project-local UserPromptSubmit Hooks.

Not currently supported:

macOS or Linux;
multi-root VS Code workspaces;
automatic phase progression;
mechanical tool permissions or PreToolUse policies.

The PowerShell Hook uses BOM-less UTF-8 for Codex JSON input and structured output. Its generated command contains an absolute project path, so moving or renaming the project requires running initialization again and reviewing the updated Hook.

Development

npm install
npm test
npm run package:vsix

The VSIX is written to artifacts/codex-phasering-0.1.4.vsix.

License

MIT