codexoverlay

CodexOverlay is a small always-on-top Windows overlay that shows your current Codex chat activity, elapsed prompt time, and codexctrl status while you work in other apps. Move or resize it with Ctrl+Shift; it stays out of screenshots and returns focus to the chat when a prompt finishes successfully.

Demo preview rendered by the application with synthetic activity; no real chat content is shown.

Quick install over HTTPS (Windows CMD)

codexctrl is required for the overlay to work, including restoring the tracked chat. Install it first from sascha/codexctrl.

Prerequisites: Windows x64, Git for Windows, .NET 8 SDK, and internet access for the source repositories and .NET packages. Run the command in normal CMD; it uses the Windows PowerShell 5.1 included with Windows internally, so PowerShell 7 is not required. The command reuses an existing checkout or creates it when missing; local changes are not discarded. No GitHub access is used.

Public availability: both codexoverlay and codexctrl must be public before third parties can use these HTTPS commands without an account or SSH key. While either repository is private, the corresponding clone still requires authorized HTTPS credentials; changing the URL does not grant access. Until publication, recipients without access should use the offline package.

1. Install codexctrl

Install the required controller by following the instructions in sascha/codexctrl.

2. Install the overlay

if exist "%USERPROFILE%\codexoverlay-install\.git" (git -C "%USERPROFILE%\codexoverlay-install" pull --ff-only https://git.prov.one/sascha/codexoverlay.git codex/overlay-prototype && call "%USERPROFILE%\codexoverlay-install\scripts\install-online.cmd") else (git clone --branch codex/overlay-prototype --single-branch https://git.prov.one/sascha/codexoverlay.git "%USERPROFILE%\codexoverlay-install" && call "%USERPROFILE%\codexoverlay-install\scripts\install-online.cmd")

The online installer detects the installed codexctrl 0.2.x executable from step 1 and installs programs per user; no controller source checkout is required. It does not edit global AGENTS.md. Its package includes a matching controller/runtime so the overlay's files stay together.

3. Enable the global overlay rule separately (optional)

Only this explicit command backs up global instructions and adds the managed overlay startup block:

"%LOCALAPPDATA%\Programs\CodexOverlay\app\codexoverlay-bootstrap.exe" --configure

Then open a new local Windows Codex chat. Program installation alone never enables global chat integration. See the Quick installation guide for custom paths, updates, removal, and installation without repository access.

---

Status: October 24, 2026 — online/offline installation with separate global setup.

Installing on another PC? Start with the Quick installation guide.

No repository access? Obtain CodexOverlay-Setup-win-x64.exe directly from the sender and follow Offline installation. The one-file package includes codexctrl and .NET and installs the programs without Git, downloads, or PowerShell 7. Global setup is a separate command:

"%USERPROFILE%\Downloads\CodexOverlay-Setup-win-x64.exe" /quiet

The overlay sits at the screen's upper-right edge and can grow to approximately half the selected screen's height. Status entries move upward as new entries appear at the bottom. It must be absent from screenshots, including codexctrl captures. Once the tracked prompt completes successfully, the corresponding chat regains focus and the overlay fades out.

The feed follows the chat's dark appearance: light message text with basic inline Markdown, compact gray command/tool rows, and underlined file-change rows with addition/deletion counts. Brief published summaries appear muted when the source provides them. Raw or encrypted reasoning is never reconstructed.

The rounded surface has a compact timer header and a live codexctrl badge. It shows aktiv during observed controller work and briefly gerade genutzt afterward, then disappears. An idle controller daemon does not count as active use.

For global use across local Windows projects, call scripts/ensure-overlay.ps1 at the beginning of each main-chat user turn. It resolves the current thread and indexed title, starts the overlay if needed, or hands the selection to the existing instance. See global setup. The last requested main chat owns the single display; background agents must not change it.

                         Screen top-right edge
                 +--------------------------------+
                 | Codex · current chat     02:14 |
                 | Earlier activity               |
                 | Repository inspected           |
                 | Plan updated                   |
                 | Latest status at the bottom    |
                 +--------------------------------+
                 Maximum height: ~50% of screen

• Product plan and acceptance criteria
• Architecture and integration constraints
• Prioritized backlog
• Decision log
• Build, run, and controls
• Feasibility findings and test results

The prototype reads the selected desktop session's local JSONL rollout without modifying Codex configuration. On the development PC, the live feed, codexctrl screenshot exclusion, exact-chat/composer focus, and completion fade have passed desktop checks. Other capture tools and mixed-DPI monitors remain unverified; see the validation report.

Build and test on Windows with the .NET 8 SDK:

./scripts/build.ps1

For a source installation, start .local/bin/codexoverlay.exe and select the session JSONL, exact chat title, and codexctrl executable in the tray Settings menu. Alternatively use scripts/start.ps1; see the running guide. Keep the complete build output together. No additional NuGet packages or API key are required. The offline package instead uses a bundled native bootstrap and includes its runtime.

Display observable activity only. Do not invent progress percentages, remaining time, or internal reasoning. Keep transcripts, personal settings, and local diagnostics out of the repository. All published project text is in English.