codex-environment

What this skill does

# 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:

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

Use this `environment.toml` pattern:

```toml
# 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:

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

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

Keep cleanup script content small:

```bash
#!/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:

```bash
#!/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
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:

```bash
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