Content
# Codex Cue for Windows
[English](README.en.md)
A lightweight Windows desktop questioning wizard. Codex opens a question-by-question interface through the native MCP tool, allowing users to directly click on single-choice, multiple-choice, or answer open-ended questions. Plugins can automatically route questions that require user input to the desktop window through lifecycle hooks and provide 2-3 clickable next tasks upon task completion, eliminating the need for copying and pasting answers.
## Interface Preview
<p align="center">
<img src="docs/images/single-select.png" alt="Codex Cue single-select question interface" width="680">
</p>
<p align="center"><em>Single-select question: Click options directly or input custom answers.</em></p>
<table>
<tr>
<td width="50%"><img src="docs/images/multi-select.png" alt="Codex Cue multi-select and free input interface"></td>
<td width="50%"><img src="docs/images/review.png" alt="Codex Cue answer review interface"></td>
</tr>
<tr>
<td align="center">Multi-select and free input</td>
<td align="center">Review and return modifications before submission</td>
</tr>
</table>
## Installation Guide
System requirements: Windows 10 22H2 (19045) or later, x64, .NET Framework 4.8. Windows 10/11 typically include the required runtime.
### Method 1: Using the Installer (Recommended)
1. Open the repository's [Releases](https://github.com/binaryaoucstics-lang/codex-cue/releases) page and download:
- `CodexCue-Setup-x64.exe`
- `SHA256SUMS.txt`
2. In the download directory, open PowerShell and verify the installer (optional):
```powershell
Get-FileHash .\CodexCue-Setup-x64.exe -Algorithm SHA256
Get-Content .\SHA256SUMS.txt
```
The SHA-256 hashes should match exactly.
3. Double-click to run `CodexCue-Setup-x64.exe`. The installer will install the application for the current user, register the personal marketplace, enable plugins, and back up the previous version with the same name.
4. After installation, in Codex CLI, input `/hooks` and find `codex-cue` provided `SessionStart`, `UserPromptSubmit`, and `Stop`, check that the commands point to `CodexCue.exe` within the plugin, then trust and enable the three hooks.
If using the codex/chatgpt desktop application, click the bottom left corner to enter settings, on the coding-hook page click trust and enable two hooks
5. Close any Codex tasks that were open before installation, then create a new task. Open tasks will not reload Skills, MCPs, or hooks while running.
6. Verify the installation with the following commands:
```powershell
codex plugin list
codex mcp list
Get-CimInstance Win32_Process -Filter "Name='CodexCue.exe'" |
Select-Object ProcessId, ExecutablePath, CommandLine
```
Expected results:
- `codex-cue@personal` displays as `installed, enabled`;
- `codex_cue` MCP displays as `enabled`;
- At least one `CodexCue.exe --host` resident process is running.
7. Try in a new task: “Let me choose to use the stable version or the preview version, don’t decide for me.” The desktop wizard should appear on top.
The installer launches an independent desktop host and registers the current user's login startup item. Codex questions and option texts are transmitted through MCP stdio JSON and named pipes, without using PowerShell, temporary files, or clipboard intermediaries.
The installer is not signed; when first distributed to other computers, Windows SmartScreen may display “Unknown Publisher.” Please verify `SHA256SUMS.txt` first, then select “More information → Run anyway.” For formal public release, consider using Authenticode code signing.
### Method 2: Using the Portable Package
`CodexCue-portable-x64.zip` contains the program, complete plugin, license, and attribution files, but not tests, PDBs, Node.js, or Python runtimes.
1. Download ZIP and `SHA256SUMS.txt` from [Releases](https://github.com/binaryaoucstics-lang/codex-cue/releases) and verify the hash.
2. Unzip ZIP, then run in the unzipped directory:
```powershell
.\CodexCue.exe --install-plugin
```
3. Follow steps 4–7 from the installer tutorial to trust hooks, create a new task, and verify.
This command installs the program and plugin into the current user's directory. For protocol integration only, use `plugins\codex-cue\bin\CodexCue.exe --mcp` directly, without a background HTTP service.
### Upgrade and Uninstallation
- Upgrade: Download the new version installer and run directly. The installer creates a timestamped and SHA-256 listed backup of the old version before replacing hosted files.
- Uninstall: Uninstall **Codex Cue** from Windows “Settings → Apps → Installed apps”. The uninstaller removes the login startup item and restores the pre-installation backup under safe conditions.
- If the new version modifies hook definitions, Codex requires re-audit and trust in `/hooks`, which is Codex’s security mechanism.
## Tool Interface
### Tray Settings and Completion Suggestions
Right-click the Codex Cue checkmark icon in the Windows taskbar notification area and select “Settings…” to enable or disable task completion suggestions and configure the number of suggestions to 1–6. Selecting “Skip next completion suggestion” skips only once, then automatically resumes; the “Skip” button in the next step popup also ends this suggestion directly without repeated questioning.
`ask_options` accepts a dynamic number of questions and options; each question supports `single`, `multiple`, and `allowOther`. Example:
```json
{
"questions": [
{
"id": "publish",
"prompt": "Select a release method",
"mode": "single",
"required": true,
"allowOther": true,
"options": [
{ "id": "installer", "label": "Installer", "recommended": true },
{ "id": "portable", "label": "Portable" }
]
},
{
"id": "targets",
"prompt": "Select included content",
"mode": "multiple",
"options": [
{ "id": "windows", "label": "Windows program" },
{ "id": "docs", "label": "Documentation" }
]
}
],
"reviewMode": "auto",
"maxWaitMs": 900000
}
```
Result statuses are `submitted`, `skipped`, `cancelled`, or `timed_out`. `skipped` indicates the user clicked the explicit skip button; `cancelled` indicates the user cancelled or closed the window; successful results return `answers` in the original order of questions. `option_prompt_status` reports only version and queue counts, without exposing questions or answer content.
## Upgrade, Backup, and Uninstallation
- The program is installed in `%LOCALAPPDATA%\Programs\CodexCue`.
- The plugin is installed in `%USERPROFILE%\plugins\codex-cue`.
- A timestamped and SHA-256 listed backup is created in `%LOCALAPPDATA%\CodexCue\backups` before each replacement.
- Installation failure rolls back the old plugin and marketplace; during uninstallation, unmodified hosted files are removed and the pre-installation backup is restored.
- If a Skill is manually modified after installation, the uninstaller preserves it to avoid deleting user content.
## Build and Verification
The development machine requires PowerShell 5.1, Python, Git, and MSBuild. The build script downloads .NET 4.8 reference assemblies; packaging uses Inno Setup 6.7.3.
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\package.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\e2e.ps1 -ArtifactRoot .\artifacts\staging
powershell -ExecutionPolicy Bypass -File .\tests\PackageTests.ps1
```
`package.ps1` outputs Setup, portable ZIP, and `SHA256SUMS.txt`, enforcing that the two distribution packages are each under 5,000,000 bytes. The current runtime depends only on Windows/.NET Framework; Inno Setup, reference assemblies, and test files are excluded from distribution packages.
Perform a complete upgrade acceptance on the current machine:
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-local.ps1
```
## Troubleshooting
- No option window appears: Create a new Codex task, then check `codex_cue` with `codex mcp list` and confirm the existence of `CodexCue.exe` with `--host` in Task Manager.
- Plugin not enabled: Run `codex plugin add codex-cue@personal`, then create a new task.
- Host unresponsive: End `CodexCue.exe` in Task Manager; the tool will restart the host on the next invocation.
- Installation issues: Check `%LOCALAPPDATA%\CodexCue\install-status.json`; old files are preserved in the same directory’s `backups`.
## Open-source License
This project is open-sourced under the [Apache License 2.0](LICENSE) and provides a [NOTICE](NOTICE) attribution file. Use, modification, or redistribution must comply with license requirements, retain applicable copyrights, licenses, and attribution statements, and note changes in modified files.
