pi-codex-env-run

English | 简体中文

Reuse and manage Codex project environment actions (.codex/environments/*.toml) inside pi — one config file, both tools.

If you use Codex's app action bar (the Run button), your repo already has a .codex/environments/environment.toml with [[actions]] entries. This extension parses the same files and gives pi both sides of the workflow:

Run (execute project actions)

• /run <action> slash command with action-name completion
• run_env_action tool callable by the model ("run the simulator" → the agent executes the project's own script)

Manage (maintain the action config)

• manage_env_action tool with list / validate / add / update / remove operations — the agent can inspect, statically validate, add, update or remove actions in .codex/environments/*.toml for you, e.g. "add a 'Build' action that runs ./gradlew assembleDebug".

pi install npm:pi-codex-env-run

Then /run (or /run sim to complete to simulator).

Long-running actions stay visible: run_env_action streams the latest command output (plus a ⏱ elapsed timer) live into the tool row, and /run shows a live status every second (⏱ name: running for 1m 23s · <last output line>) in a fixed widget above the editor (interactive TUI) instead of spamming the transcript; non-TUI modes fall back to 10s notify heartbeats. The completion notice includes the total duration.

How it works

• Scans .codex/environments/*.toml (all .toml files in the directory, not just environment.toml) by walking up from the current directory to the project root — same resolution Codex uses.
• Parses the official Codex format with a lightweight dependency-free TOML subset parser:

version = 1
name = "web-app"

[setup]
script = ""

[[actions]]
name = "Run"
icon = "run"
command = "npm run dev"

[[actions]]
name = "Test"
icon = "test"
command = '''
cd frontend
bun test
'''

• Multi-line ''' commands, [setup]/[cleanup] tables, trailing comments and string escapes are handled. Unrecognized keys/tables are ignored, corrupt files are skipped.
• Actions are deduplicated by name (first file wins, files processed in alphabetical order).
• Commands run with bash -lc in the project root (the directory containing .codex/).

Managing actions

manage_env_action supports five operations (parameters: operation, name, command, icon, file):

Operation	Description
list	Show all actions across .codex/environments/*.toml with source file, icon and command
validate	Static validation: TOML parse errors, missing name/command, duplicate names (within and across files), unknown icon warnings. Never executes commands.
add	Append a new [[actions]] block (rejects duplicate names; icon optional, defaults to none)
update	Replace the command/icon of an existing action by name (case-insensitive; original name casing preserved)
remove	Delete an action block by name (case-insensitive)

Editing is block-precise: only the target [[actions]] block is rewritten — comments, ordering and formatting elsewhere in the file are preserved. Writes target environment.toml by default; pass file to target another .toml in the same directory. Always run validate after mutations to confirm the file is still valid.

Requirements

• pi with extension support (the @earendil-works/pi-coding-agent runtime)
• A project with .codex/environments/*.toml (generated by Codex or hand-written)

Development

node --test tests/parser.test.mjs   # parser unit tests

License

MIT