llms.txt

## Last-checked: 2026-10-08

# safe-start-for-codex - Startup surge prevention for Codex Desktop automations

Canonical repository: https://github.com/dev-bricks/safe-start-for-codex

> safe-start-for-codex is a Python-based Windows startup gate utility for managing local Codex Desktop automations. It temporarily pauses active automations upon startup, starts Codex Desktop, and then gradually restores the automations in a controlled, rate-limited sequence to avoid CPU/API spikes and startup congestion.

It includes optional background tray execution, startup cleanup of stale processes/lockfiles, conservative read-only catch-up planning for rare schedules that missed runs, atomic JSON state writes for config and catch-up report files, Windows and cross-platform multi-OS CI with concurrency guards, pip caching, and ruff linting, and source-platform smoke tests for macOS/Linux parsing and configuration logic. Enforces 10 Governance & Runtime Invariants (`INV-LOCAL-01` through `INV-SLA-10`), 18-point reciprocal dual-anchor navigation parity across English and German documentation, Section 2 Visual Four-View Architectural Topology, Level 1 SBOM Third-Party Invariant Matrix, and § 521 BGB German statutory liability limitation.

Part of the dev-bricks family. Python, MIT.

Verification: 186+ pytest tests passed on 2026-10-08. Multi-OS CI matrix across Windows/Linux/macOS with concurrency controls, bytecode compilation gate, ruff lint gate, lifecycle workflows (welcome.yml, stale.yml, auto-assign.yml, label-sync.yml), and timeout-minutes guards verified. Compileall passed. Ruff lint passed. Version 1.1.6 verified.


## Docs

- [README.md](https://github.com/dev-bricks/safe-start-for-codex/blob/main/README.md): Primary documentation, installation guide, foreground/tray usage, 18-point dual-anchor navigation, and invariants matrix.
- [README_de.md](https://github.com/dev-bricks/safe-start-for-codex/blob/main/README_de.md): German localization with full bidirectional reciprocal dual-anchor parity.
- [CONTRIBUTING.md](https://github.com/dev-bricks/safe-start-for-codex/blob/main/CONTRIBUTING.md): Comprehensive bilingual guidelines, 10 invariants, unprivileged RunAsInvoker mode, Plan D workflow, and 48h SLA.
- [NOTICE](https://github.com/dev-bricks/safe-start-for-codex/blob/main/NOTICE): Canonical copyright attribution notice (Lukas Geiger, dev-bricks, open-bricks).
- [THIRD_PARTY_LICENSES.md](https://github.com/dev-bricks/safe-start-for-codex/blob/main/THIRD_PARTY_LICENSES.md): Audited dependency license inventory and Level 1 SBOM Invariant Matrix (100% permissive open source stack).
- [THIRD_PARTY_LICENSES.txt](https://github.com/dev-bricks/safe-start-for-codex/blob/main/THIRD_PARTY_LICENSES.txt): Plain-text Level 1 SBOM companion and direct dependency inventory.
- [MARKETING-LOG.txt](https://github.com/dev-bricks/safe-start-for-codex/blob/main/MARKETING-LOG.txt): Marketing strategy, target personas, search queries, and competitive matrix.
- [docs/SOLUTION_CONCEPT.md](https://github.com/dev-bricks/safe-start-for-codex/blob/main/docs/SOLUTION_CONCEPT.md): Technical outline of the gating solution.
- [docs/UPSTREAM_ISSUE_PROPOSAL.md](https://github.com/dev-bricks/safe-start-for-codex/blob/main/docs/UPSTREAM_ISSUE_PROPOSAL.md): Draft proposal for implementing native startup pacing directly inside Codex Desktop.
- [LICENSE](https://github.com/dev-bricks/safe-start-for-codex/blob/main/LICENSE): MIT license text.

## Commands

- `safe-start-for-codex dry-run`: Simulates scanning and gating without modifying TOML files.
- `safe-start-for-codex backup`: Creates a snapshot of all active automation configurations.
- `safe-start-for-codex start`: Launches Codex Desktop and gates automations in the foreground.
- `safe-start-for-codex tray`: Launches as a background Windows tray application.
- `safe-start-for-codex status`: Prints current state of gated automations.
- `safe-start-for-codex config-init`: Generates a default `config.json` file.
- `safe-start-for-codex config-show`: Displays the active configuration.
- `safe-start-for-codex catchup-plan`: Lists missed runs for rare automations.
- `safe-start-for-codex restore-latest`: Forces restoration of the latest paused automations.

## Audience

- Codex Desktop users on Windows who run many local automations.
- Developers who need a predictable automation startup sequence after opening Codex.
- Operators who want read-only catch-up visibility without triggering manual "Run now" actions.
- LLM agents and code assistants looking for the canonical Safe Start documentation.

## Search Phrases

```text
safe-start-for-codex
Safe Start for Codex
Codex Desktop automation startup gate
Codex Desktop automation surge prevention
Windows Codex automation scheduler guard
local Codex automation catch-up planner
Codex Desktop recurring automation startup control
```

## Disambiguation

The canonical repository is `dev-bricks/safe-start-for-codex`. It is not OpenAI Codex itself, not a Codex fork, and not a general-purpose scheduler. Broad web searches for Codex startup behavior often surface OpenAI documentation, tutorials, sandboxing articles, or unrelated Codex GitHub projects before this utility.

## Related Projects (dev-bricks & open-bricks family)

- [CareCenter-for-Codex](https://github.com/dev-bricks/CareCenter-for-Codex): Maintenance database and log viewer for Codex CLI and Desktop runs.
- [CodeBox](https://github.com/dev-bricks/CodeBox): Isolated Python execution box.
- [companion-for-agy](https://github.com/dev-bricks/companion-for-agy): Node.js wrapper & UI helper for the Antigravity TUI.
- [automation-master](https://github.com/dev-bricks/automation-master): Multi-agent credit budgeting, governance ledger & execution orchestration.
- [WikiStub-Seed](https://github.com/dev-bricks/WikiStub-Seed): Seed documentation & static site generator.
- [MethodenAnalyser](https://github.com/dev-bricks/MethodenAnalyser): Method and structural analysis toolkit for multi-agent workflows.
- [lock-master](https://github.com/ellmos-ai/lock-master): Fail-closed distributed concurrency control preventing multi-agent write collisions.
- [ticket-master](https://github.com/ellmos-ai/ticket-master): Queue and ticket management for cross-agent work distribution and triage.
- [ellmos-filecommander-mcp](https://github.com/ellmos-ai/ellmos-filecommander-mcp): Filesystem and process orchestration MCP server.
- [ellmos-codecommander-mcp](https://github.com/ellmos-ai/ellmos-codecommander-mcp): Code analysis and AST processing.
- [ellmos-controlcenter-mcp](https://github.com/ellmos-ai/ellmos-controlcenter-mcp): MCP stack control plane.
- [open-bricks](https://github.com/open-bricks): Root umbrella organization coordinating open-source developer tooling and standards.