codex-environment-creator

Codex Environment Creator

Philosophy

• Treat Codex environment setup as a repo contract, not a one-off shell note.
• Prefer the target repo's existing wrappers, package manager, and validators.
• Fix path and spelling drift before changing behavior.

When To Use

• The user asks to create, repair, audit, or update a Codex environment file.
• A project needs .codex/environments/environment.toml to bootstrap dependencies or expose Codex actions.
• A Codex runtime needs $CODEX_HOME/environments.toml triaged for local, remote, or disabled execution environment selection.
• A Codex exec-server provider needs URL or stdio transport entries validated.
• There is drift between .codex/environments/environment.toml, misspelled .codex/environmentals/* paths, repo docs, or setup scripts.
• Codex environment cache behavior, setup script churn, or action names need triage.

Avoid

• Editing cloud-only Codex environment settings when no repo file is involved.
• Replacing project-owned setup wrappers with generic install commands.
• Running broad installs or network-heavy commands before the target repo contract is known.

Inputs

• target project path
• requested mode: create, triage, or update
• existing environment files or misspelled aliases
• repo setup, maintenance, and validation commands
• desired actions and icons
• current Codex docs, live fork, or codex-repo evidence when schema behavior is uncertain
• evidence source for whether the request is project bootstrap/actions or runtime exec-server provider selection

Outputs

• environment file changes or triage findings
• canonical path decision
• setup and action contract
• validation evidence
• cache or rollout notes
• Schema-bound outputs include schema_version.

Execution Boundaries

• Edit only canonical repo-owned environment files unless the user explicitly asks for a migration or external target.
• The agent may create .codex/environments/ and .codex/environments/environment.toml inside the target project.
• $CODEX_HOME/environments.toml is a user/runtime exec-server provider file, not a project bootstrap/action file; inspect or edit it only when the user asks about runtime environment selection, remote exec servers, or disabled shell/filesystem access.
• The agent may inspect package and tooling files, but should run install or setup commands only when they are the smallest safe validation step.
• The user owns cloud environment administration, cache resets, secret updates, and destructive cleanup decisions unless they explicitly delegate them.