From codex-cli
Create, update, debug, or remove Codex app local project environments and actions, including `.codex/environments/environment.toml`, Run/Test/Preview buttons, startup commands, simulator/browser/dev-server launch actions, environment variables, and repeatable local commands.
How this skill is triggered — by the user, by Claude, or both
Slash command
/codex-cli:codex-environmentsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to manage repo-local Codex app environments: usually
Use this skill to manage repo-local Codex app environments: usually
.codex/environments/environment.toml plus optional project scripts called by
actions.
For long-running action patterns, port cleanup, detailed editing rules, verification depth, and common failure modes, read ../../references/environment-actions.md.
Create or edit a Codex environment when the user wants a repeatable Codex app action, such as Run, Test, Preview, Open Simulator, Start Dev Server, Launch Browser, or a stable local workflow behind a Codex Run button.
Prefer a repo-local environment when:
Do not create an environment for a one-off command, destructive operation, secret setup, or workflow that still needs product decisions. Give the command directly unless repeatability is the point.
If the environment file already exists, update it instead of creating a parallel file. Preserve unrelated actions and setup script content.
Use this structure:
version = 1
name = "project-name"
[setup]
script = ""
[[actions]]
name = "Run"
icon = "run"
command = '''
cd /absolute/project/root
./scripts/run-local.sh
'''
Common optional action fields may appear in existing files, such as
platform = "darwin". Preserve them when still correct.
Use absolute project paths inside actions unless the action is guaranteed to be launched from the repo root. Absolute paths make Codex app actions less sensitive to caller cwd. Do not commit personal paths into shared templates or plugin source.
Keep environment.toml small. If an action needs more than a few lines, create
a repo-local script such as scripts/run-dev.sh and call it from the action.
Use scripts for:
In scripts:
#!/usr/bin/env bash and set -euo pipefail;PORT="${APP_PORT:-3000}";/tmp/project-name.log;Avoid putting secrets, tokens, cookies, auth headers, API keys, passwords, or
signing material into environment.toml. Reference ignored local files or
existing env vars instead.
Before editing:
If a file says THIS IS AUTOGENERATED, still follow the user's direct request,
but keep the patch minimal and be ready for future regeneration. Prefer changing
the script called by the action when possible.
Use apply_patch for manual edits. Preserve unrelated user changes. Add
scripts under the project, usually scripts/, and keep environment.toml as the
small launcher surface.
After edits, validate at the right depth:
bash -n scripts/name.sh.chmod +x scripts/name.sh for direct scripts.For long-running scripts, use a bounded smoke run from Codex, verify readiness in another check, then terminate the process you started. Use the reference for foreground log streaming and port cleanup patterns.
Report exact commands that passed and any commands not run.
suspended (tty output): background process wrote to TTY.event not found in zsh: pasted command contains !.127.0.0.1: server exited after launch.npx claudepluginhub xopoko/plug-n-skills --plugin codex-cliGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.