codex-runner-creator

name

codex-runner-creator

description

Create, repair, or refine Codex local environment action files at `.codex/environments/environment.toml`. Use when the user asks to add Codex environment actions, create a run button, configure project startup commands, fix environment.toml, make a repo runnable from the Codex app environment panel, or generate local setup/run actions such as `运行`, `dev`, `start`, `preview`, or project-specific development commands.

Codex Runner Creator

Create a local Codex environment action file that lets the user start the project from the Codex app with the fewest reliable actions.

Workflow

1. Inspect the project before writing.
2. Reuse existing run commands and documented local workflows.
3. Choose a Codex App-stable command shape.
4. Write the smallest useful .codex/environments/environment.toml.
5. Make multi-process commands reliable enough for repeated clicks.
6. Validate TOML syntax, required fields, runtime behavior, and local-only git hygiene.

First Moves

Before writing or editing .codex/environments/environment.toml, inspect the project for startup truth:

• Read an existing .codex/environments/environment.toml if present.
• Check README.md, AGENTS.md, package manager files, package.json, Makefile, justfile, Taskfile.yml, docker-compose.yml, compose.yaml, and scripts/.
• Prefer existing project scripts and documented commands over newly invented shell.
• If several valid commands exist, choose the one that starts the main developer workflow.
• If the user asked for a specific action, preserve that intent even when other scripts exist.

File Contract

Write this file:

.codex/environments/environment.toml

Use this base shape:

# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
version = 1
name = "project-name"

[setup]
script = ""

[[actions]]
name = "运行"
icon = "run"
command = "command here"

Rules:

• Keep version = 1.
• Set name to the project or repo name.
• Keep [setup].script as "" unless there is a real one-time setup step.
• Add one default action named 运行 with icon = "run" unless the user asks for another name.
• Use TOML literal strings '''...''' for multiline shell commands.
• Ensure every action has name, icon, and command.

Command Design

• Prefer one existing project script when it already starts the desired workflow.
• Use multiline TOML shell only for simple cd plus one foreground command.
• For complex commands with shell functions, traps, loops, health checks, background processes, Kubernetes port-forwarding, process substitution, or repeated quoting, create a local wrapper script under .codex/environments/*.sh and make environment.toml call it with a single absolute command such as /bin/bash /abs/path/.codex/environments/run-dev.sh.
• Codex App environment actions may run in a non-login, non-interactive shell and may not load ~/.zshrc, ~/.bashrc, nvm, pnpm home, Homebrew paths, or other user shell customizations. Wrapper scripts should explicitly export the required PATH or use absolute tool paths before calling pnpm, bun, node, kubectl, go, etc.
• If a user reports that clicking an action briefly opens a command and the terminal closes/crashes, suspect the action command shape first: convert complex multiline TOML into a one-line wrapper script, add durable logging, and keep failures visible instead of silently exiting.
• Use absolute project paths when the command changes directories across subprojects or may run from an uncertain working directory.
• Use bash -lc, set -e, cleanup traps, and health checks when background services must be stopped together or one process depends on another.
• Prefer wrapper-script cleanup traps over deeply quoted bash -lc '...' blocks once the command grows past a few lines.
• Install dependencies only when the project's normal dev workflow requires it, and prefer idempotent checks such as [ -d node_modules ] || pnpm install.
• Keep command output interactive: run the foreground server last so logs remain visible.
• For fragile local app actions, write logs to a temp file such as ${TMPDIR:-/tmp}/<project>-codex-run.log and print that path on failure.

Action Design

• Default to one action named 运行.
• Add multiple actions only when they represent genuinely different workflows.
• Use short Chinese action names when the surrounding environment uses Chinese, such as 运行, 运行前端, 运行后端, or 运行 ui/server 开发热重载.
• Avoid exposing every package script. Add only workflows a user would actually click.
• Preserve existing useful actions when repairing a file; remove broken or duplicate actions only when the reason is clear.

Safety Rules

• Do not add destructive setup, database writes, migrations, cluster mutations, production deploys, or cleanup commands to a default 运行 action unless the user explicitly asks.
• Do not put secrets in the file unless they are already local development placeholders or explicitly required by the existing local workflow.
• Prefer local development ports and test kubeconfig paths over production targets.
• Treat .codex/environments/ as a local Codex artifact. Do not add it to repo .gitignore by default; prefer the user's global git ignore policy when cleanup is needed.
• If adding wrapper scripts under .codex/environments/, keep them local-only with the environment file unless the user explicitly wants project-owned run scripts.

Validation

After editing:

1. Run the bundled validator when available:

   python /path/to/codex-runner-creator/scripts/validate_environment_toml.py .codex/environments/environment.toml
   

2. If the file is in a git repo, verify it is ignored or intentionally untracked:

   git check-ignore -v .codex/environments/environment.toml .codex/environments/*.sh
   

3. For wrapper scripts, validate them from a minimal non-login environment so missing PATH assumptions are caught before the user clicks the Codex App action:

   env -i HOME="$HOME" PATH="/usr/bin:/bin:/usr/sbin:/sbin" SHELL=/bin/sh /bin/bash .codex/environments/run-dev.sh
   

4. If the user asked for runtime proof, run the command or the safest narrower smoke test. Avoid leaving long-running servers active unless the user wants the environment started.

References

Read references/environment-format.md when exact examples are needed for simple projects, multi-process projects, Kubernetes port-forward workflows, or quoting patterns.