---
name: codex-environments
description: 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.
---

# Codex Environments

Bundled commands use `$PLUGIN_ROOT` (`$env:PLUGIN_ROOT` in PowerShell; same path suffix) for the plugin root. Set it once: the host's plugin-root variable when defined (Claude Code: `PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"`), otherwise this plugin's absolute root path.

Manages 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 `$PLUGIN_ROOT/references/environment-actions.md`.

## Decide Whether To Create Or Edit

Create or edit a Codex environment when the user wants a repeatable Codex app action — 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:

- the command must run from a specific project root;
- the workflow needs stable env vars, ports, simulators, devices, URLs, or log paths;
- the user repeatedly pastes the same long command;
- Codex Run should start an app or local service without manual shell assembly.

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.

## File Shape

Use this structure:

```toml
version = 1
name = "project-name"

[setup]
script = ""

[[actions]]
name = "Run"
icon = "run"
command = '''
cd /absolute/project/root
./scripts/run-local.sh
'''
```

Existing files may contain optional action fields 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. Do not commit personal paths into shared templates
or plugin source.

## Command Design

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:

- multi-step server startup;
- port cleanup and readiness polling;
- simulator/device launch logic;
- log redirection;
- fragile shell quoting;
- commands users might otherwise paste incorrectly.

In scripts:

- use `#!/usr/bin/env bash` and `set -euo pipefail`;
- parameterize safe knobs with env vars, for example `PORT="${APP_PORT:-3000}"`;
- keep secrets out of files and logs;
- write long-running service logs to a known local path such as `/tmp/project-name.log`;
- check prerequisites before doing work and print actionable errors.

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.

## Editing Rules

Before editing:

- inspect the existing environment file;
- inspect any script the action currently calls;
- identify whether the file says it is autogenerated.

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.

## Verification

After edits, validate at the right depth:

- TOML syntax: parse with an available TOML parser, or inspect carefully when none is available.
- Script syntax: run `bash -n scripts/name.sh`.
- Executability: run `chmod +x scripts/name.sh` for direct scripts.
- Smoke: run the action command or script long enough to prove startup, readiness, and expected UI/browser/simulator behavior.
- Cleanup: stop any process started during verification unless the user asked to leave it running.

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.

## Common Failure Modes

- `suspended (tty output)`: background process wrote to TTY.
- `event not found` in zsh: pasted command contains `!`.
- Dev client cannot load from `127.0.0.1`: server exited after launch.
- Port says it is running another app: clear only the intended listener.
- Action works in shell but not Codex app: replace relative paths and prompts.