Codex Island

Minimal Windows desktop prototype for showing Codex work status.

What it does

• top-centered always-on-top capsule window
• borderless liquid-glass style pill UI
• automatic local Codex activity sensing from .codex file timestamps
• local status bridge over http://127.0.0.1:8765/status
• fallback file state in status.json
• no external dependencies; uses Python standard library only

Run

python app.py

Close with Esc, Ctrl+Q, or right click. Drag the pill with the mouse if you want to reposition it.

By default it watches recent changes under %USERPROFILE%\.codex. The status light follows this table:

• green: executing
• yellow: waiting for your confirmation
• red: error
• gray: idle

The automatic file watcher can infer executing and idle. waiting and error are available through the local status bridge when Codex integration sends those states.

Run manual-only mode if you only want external updates:

python app.py --source manual

Send a status update

python simulate_status.py --detail "Editing files" --state working
python simulate_status.py --detail "Waiting for approval" --state waiting
python simulate_status.py --detail "Tool failed" --state error
python simulate_status.py --detail "Waiting for next message" --state idle

In default auto mode, automatic Codex activity may overwrite manual updates on the next refresh. Use --source manual for demos or external integrations.

Integration shape

Any future Codex bridge only needs to POST JSON to:

{
  "title": "Codex",
  "detail": "Running tests",
  "state": "working"
}

Supported keys today:

• title
• detail
• state

accent and updated_at are generated by the app from state.

Codex MCP autostart

Install from npm

After this package is published as codxline, other users can install and register it with one command:

npx -y codxline install

That command installs codxline globally, checks codex and python, then registers the MCP server with Codex.

Requirements on the target PC:

• Windows
• Node.js/npm
• Python 3 in PATH
• OpenAI Codex CLI in PATH

Useful commands:

codxline status
codxline uninstall

This project includes a stdio MCP server:

python mcp_server.py

It starts or reuses the desktop island as soon as Codex launches the MCP server. When Codex closes the MCP connection, the island is closed too. It also exposes one tool:

• show_codex_island

The server is registered globally with Codex as:

codex mcp add codex-island -- python C:\Users\32676\CodexIsland\mcp_server.py

Check it with:

codex mcp get codex-island

Remove autostart with:

codex mcp remove codex-island