CareCenter for Codex

Unofficial Windows tray & CLI utility that keeps the OpenAI Codex desktop app healthy — repairs failed starts, removes hung leftovers, and safely maintains the local SQLite log database. Fully offline, no telemetry.

English · Deutsch

Note

Machine-readable architecture, CLI entry points, and safety rules are indexed for AI agents in llms.txt.

Local audit notes such as BEFUNDE.md and temporary TASKPLAN*.md status files are intentionally kept out of Git and are not part of the public release contract.

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.

---

🧭 Quick Navigation

• 1. Why & Problem Statement
• 2. Architecture & System Flow
• 3. Complete Lifecycle Sequence
• 4. Key Capabilities & Safety Invariants
• 5. Sibling Ecosystem & Partner Tools
• 6. Features
• 7. Screenshot
• 8. Requirements
• 9. Install and Run
• 10. CLI Usage
• 11. Configuration
• 12. Safety Model & Invariants
• 13. Windows Store Materials
• 14. Development & License

---

Why & Problem Statement

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.

Architecture & System Flow

flowchart TD
    subgraph UI["User Interfaces & CLI"]
        TRAY["PySide6 System Tray\n(start.bat / debug.bat)"]
        WIN["Tray Status Window\n(Live Progress & Controls)"]
        CLI["CLI Command Router\n(codex-logwartung)"]
    end

    subgraph DAEMON["Watcher & Scheduler Engine"]
        WATCH["Background Watcher\n(60s Evaluation Loop)"]
        SCHED["Loop Mode Engine\n(2h - 24h Intervals)"]
        TH_HYG["Thread Inbox Hygiene\n(Mark Read / Auto-Archive)"]
        CFG_AUD["Config Audit\n(MCP / Plugins / Empty Threads)"]
    end

    subgraph GUARDS["Process Inspection & Safety Guards"]
        SCAN["Process Tree Scanner\n(Codex.exe & ChatGPT.exe)"]
        GHOST["Fail-closed Ghost Reaper\n(Inactive Desktop Leftovers)"]
        MCP_REAP["Runtime MCP Reaper\n(Duplicate Launcher Trees)"]
        ORPHAN["Runtime Orphan Reaper\n(Dead Parent + 30m Grace)"]
        SAFE_START["Safe Start Coordinator\n(Burst & Storm Mitigation)"]
    end

    subgraph STORAGE["SQLite Log & Thread Store"]
        DB["Codex State Database\n(state_5.sqlite)"]
        BAK["Pre-Mutation Backup\n(DB + WAL + SHM Snapshot)"]
        CHECK["Integrity Verification\n(PRAGMA integrity_check)"]
        VAC["Database Optimization\n(WAL Checkpoint & VACUUM)"]
    end

    subgraph STORE_OS["Windows OS & Store Bridge"]
        APPX["Microsoft Store AppX Resolver\n(Package Reset & Reinstall PDP)"]
        PROV["Build Provenance & Manifest\n(AppxManifest.xml & store_assets/)"]
    end

    TRAY --> WATCH
    TRAY --> WIN
    CLI --> SCHED
    WATCH --> SCAN
    SCAN -->|Start Blocker Detected| GHOST
    SCAN -->|Duplicate Launcher Cohort| MCP_REAP
    SCAN -->|Dead Parent + CPU Idle| ORPHAN
    SCHED -->|Fast / Safe Trigger| DB
    DB --> BAK --> CHECK --> VAC
    DAEMON --> TH_HYG
    DAEMON --> CFG_AUD
    TRAY --> SAFE_START
    CLI --> APPX

Loading

Complete Lifecycle Sequence

sequenceDiagram
    autonumber
    actor User as User / Scheduler / CLI
    participant Tray as CareCenter Tray / Engine
    participant Scanner as Process Tree Scanner
    participant Guard as Safety & Activity Guard
    participant Codex as Codex Desktop (Store App)
    participant DB as SQLite Storage (state_5.sqlite)
    participant SafeStart as Safe Start Bridge

    User->>Tray: Trigger Maintenance (Fast / Safe / Scheduled Loop)
    Tray->>Scanner: Probe Process Tree & Active Handles
    Scanner-->>Tray: Return Running Trees (Codex / CLI / MCP)

    alt Safe Mode: Waiting Phase
        Tray->>Guard: Verify Process Tree CPU Idle State
        Guard-->>Tray: Process Busy (Wait or Allow User Cancellation)
        Note over Tray,Guard: Safe Mode waits until complete process tree is idle
    end

    Tray->>SafeStart: Pause Active Codex Automations (Prevent Storms)
    Tray->>Codex: Request Clean Graceful Shutdown (Retry up to 3x)
    Codex-->>Tray: Shutdown Confirmed (All Windows & App-Server Closed)

    rect rgb(240, 248, 255)
        Note over Tray,DB: Isolated Maintenance Transaction
        Tray->>DB: Create Snapshot Backup (Including WAL & SHM)
        Tray->>DB: Run PRAGMA integrity_check on Backup Copy
        DB-->>Tray: Integrity Verified (OK)
        Tray->>DB: Execute WAL Checkpoint & VACUUM Optimization
        DB-->>Tray: Database Compacted & Optimized
    end

    rect rgb(255, 250, 240)
        Note over Tray,Codex: Thread Inbox Hygiene & Config Audit
        Tray->>DB: Apply Age-Based Thread Rules (Mark Read / Archive)
        Tray->>DB: Clean Empty Threads (Enforcing 300s Grace Window)
        Tray->>DB: Resolve Duplicate MCP & Incompatible Plugin Configs
    end

    Tray->>Codex: Relaunch Verified Clean Codex Session
    Codex-->>Tray: Codex Main Window Confirmed Active
    Tray->>SafeStart: Staggered Restore of Paused Automations (60s Windows)
    Tray-->>User: Maintenance Cycle Complete (Progress & Log Updated)

Loading

Key Capabilities & Safety Invariants

Invariant / Capability	Architectural Guarantee	Enforcement Mechanism	Safety Boundary
1. 100% Local-First	Zero external telemetry, no background data transmission, no cloud sync reliance	Fully offline runtime loop; all paths reside on local filesystem	Network egress strictly prohibited; opt-in manual check (--live-pages) isolated
2. Unprivileged User-Mode	Normal execution runs in user space without administrator elevation	Standard non-elevated user permissions for watcher, tray, and DB tasks	Elevated repair actions (Store AppX register/reset) require explicit user confirmation
3. Fail-Closed Process Protection	Active processes and productive work are never terminated	Multi-point CPU delta sampling and parent-PID tree inspection	Any detected CPU advancement or missing criteria immediately aborts kill
4. CLI Session Immunity	Node-based Codex CLI and detached codex exec sessions are protected	Explicit CLI filter and rollout timestamp checks	Active CLI execution acts as global mutation lock for thread store
5. Pre-Mutation DB Snapshot	SQLite database is never mutated in-place without verified backup	Complete snapshot of database file plus WAL and SHM journal files	Any backup failure immediately halts maintenance before VACUUM
6. Cryptographic Integrity Gate	Database corruption is detected before applying maintenance	Execution of PRAGMA integrity_check on the backup copy	Non-zero or corrupted check blocks all downstream write/checkpoint operations
7. Mandatory Safety Grace Windows	New processes and empty threads are given time to complete initialization	30-minute hard floor for runtime orphans; 300s floor for empty threads	Temporary initialization spikes are never mistaken for dead leftovers
8. Staggered Automation Unpausing	Recovery does not flood Codex with simultaneous automation starts	Configurable stagger delay (default: 60s windows) via Safe Start coordinator	Avoids API rate-limit spikes and host CPU saturation
9. Non-Destructive AppX Resolution	Microsoft Store package troubleshooting preserves user data	Bounded escalation: no-admin cleanup -> admin suggestion -> Store reinstall PDP	Automatic destructive resets or package purges are strictly forbidden
10. Strict Verification Parity	100% green test suite, clean linters, and synchronized contracts	Automated CI matrix, Pytest suite (381 passed), Ruff, and compileall	Code changes require complete verification before release deployment

Sibling Ecosystem & Partner Tools

Partner Tool	Organization	Role & Capability	Integration with CareCenter
safe-start-for-codex	dev-bricks	Process startup gating, burst protection, and automation pauses	Core dependency; bundled and invoked for launch storms and automation management
MethodenAnalyser	dev-bricks	Static AST analysis, class/method extraction, and cyclomatic complexity	Validates code health, refactoring scopes, and Python codebase architecture
companion-for-agy	ellmos-ai	Windows ConPTY bridge, pseudo-terminal daemon, and session supervisor	Shares process-isolation invariants and protects agent background executions
lock-master	dev-bricks	Multi-agent concurrency control, lock caches, and file reservation	Enforces zero-collision file access across autonomous coding agents
bach	ellmos-ai	Brain Architecture Orchestrator and task decomposition runtime	Coordinates multi-agent workflows and high-level autonomous task distribution
usmc	ellmos-ai	Unified System Mission Control and desktop operations dashboard	Aggregates health metrics, service statuses, and operational alerts across tools
clutch	ellmos-ai	Tool hook manager, git hooks, and semantic execution dispatching	Manages developer environment hooks and pre-commit governance validation
open-compute	ellmos-ai	Autonomous computer-use agent and cross-platform OS task executor	Leverages clean process environments ensured by CareCenter's ghost reapers
system-auditor	ellmos-ai	Multi-host diagnostic engine, environment drift and gap detector	Monitors host-wide registry state, disk hygiene, and process integrity
CloudLockFixer	file-bricks	Cloud synchronization unlocker and conflict copy manager	Unlocks stuck cloud synchronization files without corrupting local data
SoftwareCenter	file-bricks	Central PySide6 software catalog and desktop application dashboard	Lists and manages desktop utilities including CareCenter and companion tools
DokuZen	doc-bricks	Document processing, OCR, automated redaction, and PDF cleanup	Complements local-first desktop workflows with zero-network document security

Features

• Background watcher: checks every 60 seconds for old start blockers, detached runtime orphans, and duplicate runtime MCP process generations. Runtime-orphan cleanup requires a dead parent, a hard 30-minute grace period, and two CPU snapshots. Detached codex exec runs remain protected while CPU advances, a session rollout is newer than two minutes, or their --output-last-message target is still missing; inactive language_server* orphans remain eligible. Every successful orphan kill records PID, command line, and criterion in app.log. Runtime MCP cleanup still targets only idle launcher trees repeated under the same Store desktop app-server and always keeps the newest launch cohort.
• 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.
• Tray automation controls: pause all currently active Codex automations, restore only automations disabled by CCC, or turn automations back on immediately or gradually. The spacing is configurable via automation_stagger_delay_seconds (default: 60 seconds).
• Thread inbox hygiene: mark every result as read, mark only unread threads older than a configurable number of days, and automatically archive threads older than a separate configurable age. Empty-thread auto-fix waits at least 300 seconds so new CLI/Desktop threads can finish their first write. Current Codex thread ages and archive flags come from state_5.sqlite; unread IDs come from .codex-global-state.json. Changes are blocked by either Desktop or npm Codex CLI activity, rechecked immediately before backup/move, and use database/state backups, atomic JSON writes, and transactional archive updates.
• Config audit cleanup has three independent off / notify / auto controls for duplicate MCP configuration entries, Windows-incompatible plugins, and empty threads. The manual audit additionally runs the conservative runtime MCP reaper even while the desktop renderer is present; configuration and thread mutations remain deferred until Codex is closed.
• Loop mode: choose 2, 3, 5, 7, 10, 12, or 24 hours. Each regular due cycle starts with Fast maintenance and retries Codex close failures up to three times by default. If closing still fails, Safe becomes an extended catch-up attempt and the normal loop timer starts over; if Safe finishes before that timer expires, the timer starts again from the successful maintenance plus verified Codex restart. If the timer expires while Safe is still waiting, Safe is cancelled and the next regular Fast cycle starts. Automations are paused only after maintenance has succeeded, and only those paused automations are restored in 60-second windows.
• Direct tray starts: "Codex safe starten" launches Safe Start for Codex in its own tray and reuses its config.json; if that config is missing, CareCenter uses a 1-minute interval for that launch. If Safe Start is already gating, the second safe-start click is a no-op. "Codex starten" starts Codex normally without the Safe Start gate; while Safe Start is active, CareCenter only restores the automations paused by Safe Start and does not open another Codex window.
• 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.
• Current Store-process compatibility: recognizes both legacy Codex.exe Electron trees and newer ChatGPT.exe-named Codex Store trees, including their embedded app-server, without confusing CareCenter itself with Codex.
• 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, tray, 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, Loop mode, Store actions, Safe Start actions, automation controls, 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

For the normal tray start from a checkout, use start.bat. It launches the tray windowlessly through pythonw.exe and writes startup failures to %LOCALAPPDATA%\CareCenterForCodex\logs\app.log. Use debug.bat when you want the console to stay visible for troubleshooting.

Build a standalone EXE:

build_exe.bat

For a controlled non-production build, override both local output roots:

$env:CARECENTER_DIST_DIR = "C:\_Local_DEV\codex_build\artifacts\carecenter"
$env:CARECENTER_BUILD_ROOT = "C:\_Local_DEV\codex_build\work\carecenter"
build_exe.bat

The build refuses tracked uncommitted source changes. It embeds the project version, Git commit, and UTC build time in the EXE and writes CareCenterForCodex.provenance.json next to it with the artifact size and SHA-256. status, doctor, and the tray startup log report the embedded build identity.

By default, the build uses the public Safe Start GitHub source pinned to an exact commit in pyproject.toml. This keeps the build reproducible without silently bundling a dirty local sibling checkout. Only use a local Safe Start source on purpose:

$env:CARECENTER_SAFE_START_SOURCE = "C:\path\to\REL-PUB_safe-start-for-codex"
build_exe.bat

CLI Usage

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 fast-loop-cycle --execute
python -m codex_logdatenbank_wartung.cli mark-runs-read --dry-run
python -m codex_logdatenbank_wartung.cli mark-runs-read --older-than-days 2
python -m codex_logdatenbank_wartung.cli mark-runs-read --older-than-days 2 --archive-older-than-days 10
python -m codex_logdatenbank_wartung.cli startup-receipt C:\path\rollout.jsonl --boot-file GPT=C:\path\GPT.md --format json
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.

startup-receipt reads only through the first assistant boundary of the explicitly named rollout. It emits metadata, character/byte counts, and SHA-256 values—not prompt content. External --boot-file LABEL=PATH inputs are reported as injection_claim=false snapshots and never presented as proof that Codex injected them.

In the tray settings, 0 disables an age rule. Set auto_mark_threads_read_days and auto_archive_threads_days to independent values such as 2 and 10. CareCenter applies the rules during background watcher ticks as soon as Codex is fully closed.

Configuration

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

config:   %LOCALAPPDATA%\CareCenterForCodex\config.json
logs:     %LOCALAPPDATA%\CareCenterForCodex\logs\
backups:  %LOCALAPPDATA%\CareCenterForCodex\backups\
database: %USERPROFILE%\.codex\logs_2.sqlite

Codex paths are detected from %LOCALAPPDATA%, %APPDATA%, and CODEX_HOME. New installs also place CareCenter data under %LOCALAPPDATA%\CareCenterForCodex by default. Existing local setups under C:\_Local_DEV\codex-maintenance\ are reused automatically as a legacy fallback. You can override every path in config.json.

Runtime MCP cleanup is enabled by default through reap_runtime_mcp_duplicates. Its conservative defaults are a configurable 3600-second (one-hour) minimum age for every candidate root, a 90-second launch-cohort gap, a 30-second launcher window, at least two distinct repeated MCP signatures, and a 1-second CPU activity sample. Each threshold can be overridden in config.json.

Runtime-orphan cleanup keeps the compatible reap_companion_orphans configuration prefix. companion_orphan_min_age_seconds has a hard 1800-second safety floor; the default CPU sample is 5 seconds and the session-rollout freshness window is 120 seconds. Configured CPU windows cannot reduce the two-snapshot interval below 2 seconds, and the rollout window cannot be shortened below 120 seconds.

audit_empty_thread_min_age_seconds defaults to 300 seconds. Values below 300 are clamped to that conservative initialization grace; larger values extend it.

To use a different data root (useful in tests or alternative installations), set CCC_DATA_ROOT before launching:

$env:CCC_DATA_ROOT = "D:\my-codex-maintenance"
python -m codex_logdatenbank_wartung.cli tray

When set, config.json, logs\, and backups\ are placed under that path instead of the default %LOCALAPPDATA%\CareCenterForCodex\.

Safety Model & Invariants

• Normal CareCenter runtime and the default CLI commands are local-only: they do not send telemetry, upload data, call external APIs, or use cloud sync.
• 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 inactive ghosts without a renderer only after the configured age threshold.
• Duplicate runtime MCP cleanup always keeps the newest launch cohort and skips candidate trees whose CPU counters still advance.
• Runtime-orphan cleanup requires a dead parent plus age and CPU-idle evidence. A detached codex exec is additionally excluded while any CPU, recent rollout, or pending-output signal remains; a run without an --output-last-message contract is excluded fail-closed. Idle dead-parent language_server* processes remain cleanup targets.
• The Codex desktop app-server, unrelated child processes, active Codex CLI work, and active desktop work are excluded from process termination. The broad read-only detector still treats Desktop and npm CLI activity as a blocker for thread-store mutation.
• 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:

• store_package.json
• STORE_LISTING.md
• PRIVACY_POLICY.md
• SUPPORT.md
• docs/privacy.md
• docs/support.md
• AppxManifest.xml with four canonical package-logo sources in store_assets/

Public Store pages:

• Privacy: https://dev-bricks.github.io/CareCenter-for-Codex/privacy
• Support: https://dev-bricks.github.io/CareCenter-for-Codex/support

Validate them with:

python -m codex_logdatenbank_wartung.cli store-materials
python -m codex_logdatenbank_wartung.cli store-materials --live-pages
python -m codex_logdatenbank_wartung.cli store-materials --exe-path C:\_Local_DEV\codex-maintenance\bin

The command without --live-pages is a local-only material check and does not contact either URL. --live-pages is a separate, explicit manual release preflight: only this opt-in path requests both configured Store URLs over HTTPS and reports unreachable pages as warnings. It is not part of the tray, watcher, maintenance, or normal CLI runtime and is not telemetry. Without --exe-path, the check tries to discover the built EXE automatically from build_exe.bat (DIST_DIR). With --exe-path, you can pass either the exact .exe file or just the build directory.

The local preflight parses AppxManifest.xml, compares its package identity, publisher, version, executable, and display name with store_package.json, and maps its staged icons/ references to the central builder's store_assets/ sources. It fails if a source logo is missing or escapes that source directory.

The Store privacy/support URLs are prepared for GitHub Pages. store-materials also runs a temporary static Pages build and verifies privacy/index.html, support/index.html, index.html, and the build marker. You can still build the artifact explicitly with:

python scripts\build_store_pages.py --output _site

The active workflow .github/workflows/pages.yml publishes the generated /privacy/ and /support/ routes through GitHub Pages.

Development & License

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, automation control, Store material validation, configuration loading, i18n, and tray language persistence.

License

CareCenter for Codex is licensed under MIT. PySide6 is used under the LGPL; the direct-dependency inventory and its update scope are documented in THIRD_PARTY_LICENSES.txt.