melvynx/codex-environment

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