codex-environment - SKILL.md Agent Skill

name: codex-environment description: Create, inspect, or repair Codex app Local Environment configuration for worktrees, including .codex/environments/environment.toml, setup and cleanup scripts, worktree up/down scripts, copied env files, isolated databases, and reusable app actions. disable-model-invocation: true allow_implicit_invocation: false

Codex Environment

Use this skill when the user asks about Codex Local Environments, worktree setup scripts, cleanup scripts, Codex actions, .codex/environments/environment.toml, CODEX_WORKTREE_PATH, CODEX_SOURCE_TREE_PATH, or making a worktree ready to run.

What We Learned

Codex app Local Environments are project config, not one-off terminal commands.
The shareable config lives at .codex/environments/environment.toml at the project root.
Setup scripts run when Codex creates a new worktree for a new thread.
Cleanup scripts run before Codex cleans up the worktree.
Actions appear in the Codex app top bar and run in the integrated terminal.
Worktrees only contain checked-in files, so ignored files like .env must be copied or recreated by setup.
Prefer short setup/cleanup entries that call versioned project scripts instead of long inline shell.
Keep executable entrypoints in scripts/, for example scripts/worktree-up and scripts/worktree-down.
Keep .codex focused on Codex config; keep operational logic in scripts/.
Do not commit secrets. It is fine for setup to copy ignored env files locally.
For projects with local databases, setup should create a worktree-specific DB name and rewrite the copied .env to point to it.
Cleanup should drop only the worktree-specific databases and remove copied local env files.
Use CODEX_SOURCE_TREE_PATH for the original project checkout and CODEX_WORKTREE_PATH for the new worktree when available.

Preferred Shape

Create or update:

.codex/
└── environments/
    └── environment.toml
scripts/
├── worktree-up
├── worktree-down
├── codex-dev.sh
└── project-specific helpers...

Use this environment.toml pattern:

# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
version = 1
name = "Project Worktree"

[setup]
script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-up"

[cleanup]
script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-down"

[[actions]]
name = "Dev"
icon = "tool"
command = "scripts/codex-dev.sh"

[[actions]]
name = "Typecheck"
icon = "tool"
command = "pnpm ts"

[[actions]]
name = "Unit tests"
icon = "tool"
command = "pnpm test:ci"

[[actions]]
name = "Lint"
icon = "tool"
command = "pnpm lint:ci"

Keep setup script content small:

#!/usr/bin/env bash
set -euo pipefail

cd "${CODEX_WORKTREE_PATH:-$(pwd)}"
scripts/make-worktree-ready.sh

Keep cleanup script content small:

#!/usr/bin/env bash
set -euo pipefail

cd "${CODEX_WORKTREE_PATH:-$(pwd)}"
scripts/worktree-db-down.sh

Setup Script Rules

When writing scripts/worktree-up or its helper:

Start with set -euo pipefail.
cd "${CODEX_WORKTREE_PATH:-$(pwd)}" before touching files.
Locate the source checkout with CODEX_SOURCE_TREE_PATH, then a project-specific fallback like $HOME/Developer/saas/<repo>.
Copy ignored env files from source to worktree, usually .env, .env.local, and .env.development.local.
Prefer project package manager conventions, for example pnpm install, never npm install in a pnpm repo.
Create a deterministic worktree DB name from the branch or target worktree, replacing / with -.
Rewrite only DB-related env values in the copied .env.
Run project generation steps needed after env setup, for example pnpm prisma:generate.
Make reruns idempotent. If the DB already exists, skip import unless a reset env var is set.
Add an explicit reset escape hatch such as LUMAIL_RESET_DB=1.

Cleanup Script Rules

When writing scripts/worktree-down or its helper:

Read DB names from the worktree .env, not from guessed branch names.
Drop only the DBs referenced by the worktree env.
Use dropdb --if-exists and a maintenance database.
Remove copied local env files from the worktree after DB cleanup.
If env files or PostgreSQL tools are missing, exit cleanly with a short message.

Actions

Use actions for commands the user will run often:

Dev: start the app, ideally via a script that finds a free port.
Typecheck: pnpm ts, npm run typecheck, or equivalent.
Unit tests: the project unit test command.
Lint: the CI lint command.
E2E: optional, only if it is not too expensive/noisy for a quick action.

For dev servers, prefer a script like:

#!/usr/bin/env bash
set -euo pipefail

cd "${CODEX_WORKTREE_PATH:-$(pwd)}"

port="${CODEX_DEV_PORT_START:-3910}"
while lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; do
  port=$((port + 1))
done

echo "Starting app on http://localhost:$port"
exec pnpm dev -p "$port"

Verification

After editing a Codex environment:

bash -n scripts/worktree-up scripts/worktree-down
sed -n '1,220p' .codex/environments/environment.toml
git status --short

If Python 3.11+ is available, validate TOML:

python3 - <<'PY'
import tomllib
with open(".codex/environments/environment.toml", "rb") as f:
    tomllib.load(f)
PY

Guardrails

Do not read or write .conductor directories.
Do not print full env values or secrets in logs; print only DB names or redacted hosts.
Do not create duplicate environments when the user already has one; update the existing .codex/environments/environment.toml.
Do not put large fragile shell programs directly in TOML strings.
Do not hardcode a dev port unless the user asks; pick a free port or allow PORT.
Do not drop databases unless their names come from the worktree env or from an explicit user-provided target.
If the environment is meant for future worktrees, ensure the .codex config and scripts are present in the source checkout/main branch, not only the current Codex worktree.

Online References

OpenAI Codex Local Environments: https://developers.openai.com/codex/app/local-environments
OpenAI Codex Worktrees: https://developers.openai.com/codex/app/worktrees
CODEX_SOURCE_TREE_PATH / CODEX_WORKTREE_PATH community note: https://zenn.dev/route06/articles/c1f686b4479957
Codex app environment TOML practice note: https://zenn.dev/devneko/articles/8a5f6f44adf606