# pi-codex-env-run

**English** | [简体中文](README.zh-CN.md)

Reuse and manage [Codex](https://github.com/openai/codex) project environment
actions (`.codex/environments/*.toml`) inside [pi](https://pi.dev) — 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:

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

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

## License

MIT