environments-manager

Environments Manager

Set up per-worktree environments so a fresh worktree is ready to run: env files copied, dependencies installed, optional data services isolated or seeded, generated code refreshed, and common commands exposed through the selected IDE. Supports Claude Code, Cursor, and Codex. The shared scripts are the same on every IDE; only the config file that points at them differs.

Keep this skill database-agnostic. The main flow decides what needs to happen; database-specific implementation details live in references and should be loaded only when that backend is relevant.

Interactive Flow

This skill is interactive. Ask the user the questions below before writing anything. Use whichever interactive question mechanism the host harness provides. Do not assume answers.

Step 1: What should happen in a fresh worktree?

Ask the user what the setup script should do, as a multi-select. The first option is the default-on baseline; the rest are additive opt-ins:

If the user has project-specific steps such as seed data, S3/R2 sync, local services, webhook tunnels, fixture generation, or env cloning, ask one follow-up free-form question to capture them.

Step 2: Which data backend, if any?

Ask which backend needs worktree isolation or seeding. Use the answer to decide which reference to load:

For unknown backends, do not guess commands, reset behavior, file formats, import/export semantics, or production-safety flags. Ask researcher agents to find the official docs and at least one in-repo example or closely matching project pattern. Summarize the discovered approach before editing scripts.

Step 3: Which IDEs should be wired up?

Ask a multi-select with options: Claude Code, Cursor, Codex. The user can pick any combination. Generate the shared scripts/ directory once.

Step 4: Apply each selected IDE

For each selected IDE, read the matching reference file and apply only its linking config. Do not duplicate script logic in IDE config; the IDE config points at scripts/worktree-up.sh, scripts/worktree-down.sh, and scripts/dev.sh.

• Claude Code -> load references/claude.md
• Cursor -> load references/cursor.md
• Codex -> load references/codex.md

Shared Shape

Every project that uses this skill ends up with:

scripts/
├── worktree-up.sh        # idempotent setup
├── worktree-down.sh      # cleanup before worktree teardown
├── dev.sh                # start dev server on a free port
└── (project-specific helpers, all *.sh)

Plus one or more IDE config files. The IDE config is thin; all logic lives in scripts/.

Naming convention: every generated script MUST end in .sh. No bare worktree-up, no dev. IDE configs reference scripts by full filename (scripts/worktree-up.sh, not scripts/worktree-up). This is enforced in every reference file and example.

Environment Variable Cascade

Each IDE exposes different variables. The shared scripts accept all of them, in this priority:

WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-}}"

Important about Claude Code: do not use SessionStart for setup; it fires every session. Use the WorktreeCreate hook, which fires once when claude --worktree creates the worktree. The Claude wrapper script (scripts/claude-worktree-create.sh) is responsible for calling git worktree add itself, then handing off to scripts/worktree-up.sh inside the new worktree with ROOT_WORKTREE_PATH set. See references/claude.md.

If no env var yields a source checkout, fall back to a project-specific absolute path only when you can infer it confidently. Otherwise ask the user during Step 1.

scripts/worktree-up.sh

Setup must be idempotent: reruns are safe. Build the script from the user's Step 1 selections and any backend reference loaded in Step 2. Required behavior in order:

1. set -euo pipefail.
2. Resolve WORKTREE_PATH and SOURCE_PATH.
3. cd "$WORKTREE_PATH".
4. If env copying was selected, copy .env, .env.local, .env.development.local only when the source has them and the worktree does not.
5. If dependency install was selected, detect the lockfile and run the matching install.
6. If backend isolation/seeding was selected, apply the backend reference or the researched project-specific approach.
7. If codegen was selected, run the project's codegen command.
8. Append any free-form project-specific steps from Step 1.

Base template, before backend-specific additions:

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

WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-$HOME/Developer/saas/<repo>}}"

cd "$WORKTREE_PATH"

# Copy ignored env files.
# NOTE for Claude Code users: .worktreeinclude handles this natively. Prefer it
# over the cp loop when the project uses Claude's --worktree.
for f in .env .env.local .env.development.local; do
  if [[ -f "$SOURCE_PATH/$f" && ! -f "$WORKTREE_PATH/$f" ]]; then
    cp "$SOURCE_PATH/$f" "$WORKTREE_PATH/$f"
    echo "copied $f"
  fi
done

# Install deps.
if   [[ -f pnpm-lock.yaml ]]; then pnpm install
elif [[ -f bun.lock || -f bun.lockb ]]; then bun install
elif [[ -f yarn.lock ]]; then yarn install
elif [[ -f package-lock.json ]]; then npm install
fi

# Backend isolation/seeding and codegen go here.

scripts/worktree-down.sh

Cleanup runs before the IDE destroys the worktree. Keep cleanup scoped to resources that the setup script created or selected explicitly.

1. set -euo pipefail.
2. Resolve WORKTREE_PATH.
3. cd "$WORKTREE_PATH".
4. Run backend-specific cleanup only when the loaded backend reference requires it.
5. Remove copied local env files only if that is appropriate for the project.
6. If required tools or env files are missing, print one short message and exit 0.

Never guess resource names from branch names. Read names from the worktree's env/config files or from deterministic setup metadata created by worktree-up.sh.

scripts/dev.sh

Pick a free port so multiple worktrees can run in parallel.

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

WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
cd "$WORKTREE_PATH"

port="${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"  # adjust for the project package manager

Standard Actions

Every project should expose these four actions through the IDE's own mechanism:

Add E2E as an action only if the suite is cheap enough to run interactively.

Universal Guardrails

• Never commit secrets. Copying ignored env files into a local worktree is fine; logging them is not.
• Never put fragile multi-line shell programs inside an IDE config file. Keep all logic in scripts/; the IDE config just calls those scripts.
• Never hardcode a dev port. Pick a free one starting from ${DEV_PORT_START:-3910}.
• Setup must be idempotent. Provide a reset escape hatch for stateful resources via env var (<PROJECT>_RESET_<RESOURCE>=1).
• Print resource names and redacted hosts only.
• The scripts and IDE config must live on the source checkout / main branch, not only the current worktree, or future worktrees will have nothing to copy.
• Never destroy or import from production data by default. Any setup step that exports from a shared source and replays into a worktree must reject production-looking refs unless the user explicitly approved an override env var.
• Hook wrappers must survive a missing /dev/tty, a wrong default Node version, and CLI prompts. See references/claude.md -> "Hook Robustness" for the concrete fixes.

Use this production-source guard in backend references or project-specific helpers:

assert_non_prod_ref() {
  case "$1" in
    prod|prod:*|prod/*|production|production:*|production/*)
      echo "refusing prod source: $1" >&2; exit 1 ;;
    *prod*|*production*)
      [ "${ALLOW_PROD_SOURCE:-0}" = "1" ] || { echo "looks like prod: $1" >&2; exit 1; } ;;
  esac
}

Verification

After generating files:

bash -n scripts/worktree-up.sh scripts/worktree-down.sh scripts/dev.sh
git status --short

If Python 3.11+ is available, validate generated TOML:

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

For JSON configs:

python3 -c "import json; json.load(open('.cursor/worktrees.json'))"
python3 -c "import json; json.load(open('.claude/settings.json'))"

References

Load only the references relevant to the selected backend and IDE:

• references/postgresql.md - PostgreSQL isolation, reset, and cleanup.
• references/convex.md - Convex local/cloud deployments, allowlisted seeding, env cloning, and cleanup.
• references/claude.md - Claude Code WorktreeCreate/WorktreeRemove wiring.
• references/cursor.md - Cursor worktree setup wiring.
• references/codex.md - Codex local environment TOML.

Examples

Working examples live under examples/. Read the relevant example before writing files into a real project, but do not copy verbatim. The user's selections, backend reference, and project conventions determine which sections survive.

examples/
├── scripts/
│   ├── worktree-up.sh
│   ├── worktree-down.sh
│   ├── dev.sh
│   ├── convex-selective-seed.sh
│   ├── claude-worktree-create.sh
│   └── claude-worktree-remove.sh
├── claude/
│   ├── .worktreeinclude
│   ├── settings.json
│   └── commands/
├── cursor/
│   └── worktrees.json
└── codex/
    └── environments/
        └── environment.toml