CareCenter for Codex

CareCenter for Codex is an unofficial local Windows tray and CLI utility for keeping the OpenAI Codex desktop app healthy. It repairs failed starts, removes hung leftovers, and safely maintains Codex's local SQLite log database. Everything runs offline and without telemetry.

German documentation: README.de.md

Important

This is an independent community tool. It is not created by, affiliated with, endorsed by, or sponsored by OpenAI. "OpenAI" and "Codex" are trademarks of OpenAI and are used here only to describe compatibility.

Why

On Windows, closing the Codex desktop window can leave a hung main process behind. That leftover process can hold the app singleton lock, so the next start appears to do nothing. CareCenter removes that first blocker safely: it only touches inactive ghost processes, stale lock files, and explicitly requested maintenance paths.

Features

• Background start-prevention watcher: checks every 60 seconds whether Codex is closed and old start blockers remain. It never touches an active Codex session, the node-based Codex CLI, or a process tree that is still doing CPU work.
• Tray settings with language switching: choose English or German in the Settings area. The choice is saved in config.json and the visible tray UI is relabeled immediately.
• One-click Repair Codex action: runs a bounded escalation that stops as soon as Codex starts again. It begins with no-admin cleanup and only suggests admin restart, Store reinstall, or reboot when needed.
• Safe and Fast maintenance modes:
  • Safe waits until the complete Codex process tree is idle, can be cancelled while waiting, closes Codex cleanly, runs maintenance, and restarts it.
  • Fast closes Codex immediately and then runs maintenance.
• Store tools: repair a stuck Microsoft Store update path and open the Store reinstall page for Codex.
• Conservative database maintenance: backup including WAL/SHM, integrity check on the backup, WAL checkpoint, PRAGMA optimize, VACUUM, and limited backup retention.
• Status window with progress bar, live tray tooltip, and persistent audit logs.
• Safe Start for Codex is shipped as a dependency and can be installed or updated from the CareCenter window or CLI. CareCenter uses it for release bursts, start storms, and catch-up hints.

Screenshot

The tray status window shows current state, removed-leftover count, progress, maintenance controls with Safe cancellation, Store actions, Safe Start actions, and settings.

Regenerate the screenshot from the real PySide6 status window:

$env:PYTHONPATH="src"
python -m codex_logdatenbank_wartung.cli store-screenshot

Requirements

• Windows 10 or Windows 11
• Python 3.12+ when running from source
• PySide6 for the tray UI

Packaged EXE builds do not require a separate Python installation.

Install and Run

From source:

$env:PYTHONPATH="$PWD\src"
pip install -r requirements.txt
python -m codex_logdatenbank_wartung.cli status
python -m codex_logdatenbank_wartung.cli tray

Build a standalone EXE:

build_exe.bat

CLI

python -m codex_logdatenbank_wartung.cli doctor
python -m codex_logdatenbank_wartung.cli repair --dry-run
python -m codex_logdatenbank_wartung.cli repair --execute
python -m codex_logdatenbank_wartung.cli dry-run
python -m codex_logdatenbank_wartung.cli maintain --execute
python -m codex_logdatenbank_wartung.cli auto-maintain --mode safe --execute
python -m codex_logdatenbank_wartung.cli store-repair --level repair --execute
python -m codex_logdatenbank_wartung.cli store-materials
python -m codex_logdatenbank_wartung.cli safe-start-report
python -m codex_logdatenbank_wartung.cli safe-start-install
python -m codex_logdatenbank_wartung.cli schedule install --interval-minutes 180

The CLI reads language from config.json for runtime reports. The tray settings are the intended way to switch the persisted language.

Configuration

Configuration, logs, and backups live outside cloud-synced folders by default:

config:   C:\_Local_DEV\codex-maintenance\config.json
logs:     C:\_Local_DEV\codex-maintenance\logs\
backups:  C:\_Local_DEV\codex-maintenance\backups\
database: %USERPROFILE%\.codex\logs_2.sqlite

Codex paths are detected from %LOCALAPPDATA%, %APPDATA%, and CODEX_HOME. You can override them in config.json.

Safety Model

• Conservative maintenance blocks while Codex is running.
• Scheduled maintenance never closes Codex.
• Safe auto-maintain only closes Codex after the full process tree is idle.
• Safe cancellation stops only the waiting phase before Codex is closed; active database operations are not force-interrupted.
• The watcher kills only inactive ghosts without a renderer and only after the configured age threshold.
• The Codex CLI and active desktop sessions are explicitly excluded.
• Destructive paths such as Store reset, admin repair, reinstall, and reboot are suggestions or explicit user actions, not automatic surprises.

Windows Store Materials

The project includes Windows Store groundwork:

• PORTIERUNGSPLAN.md
• store_package.json
• STORE_LISTING.md
• PRIVACY_POLICY.md
• SUPPORT.md

Validate them with:

python -m codex_logdatenbank_wartung.cli store-materials

Development

$env:PYTHONPATH="src"
python -m pytest
python -m ruff check src tests
python -m compileall src tests

The test suite covers maintenance safety, repair escalation, Safe Start integration, Store material validation, configuration loading, i18n, and tray language persistence.

License

CareCenter for Codex is licensed under MIT. PySide6 is used under the LGPL; see THIRD_PARTY_LICENSES.txt.