@estebanforge/pi-ask-codex

A Pi extension that exposes the AskCodex tool: delegate a self-contained sub-task to OpenAI's Codex CLI and stream its structured progress back into the Pi session.

It is the AskClaude-style delegation pattern (from pi-claude-bridge), pointed at GPT via codex exec. The tool answers to three names the CLI is known by — codex, openai, and gpt — surfaced in its description so the model maps any of them to this single tool.

Install

pi install npm:@estebanforge/pi-ask-codex

Requires the Codex CLI installed and authenticated:

npm install -g @openai/codex
codex login

The extension resolves codex on $PATH, or via the CODEX_BIN environment variable if you want to point at a specific binary.

Two modes: one-shot vs continued conversation

One tool, two ways to use it — you (or the agent) decide per call:

• One-shot (isolated): omit sessionId. Codex starts fresh with no memory of prior calls. Use for independent questions.
• Continued conversation: pass the sessionId returned in a prior call's result (details.sessionId, also shown in the result footer). Codex resumes that session with full context intact — use for follow-ups, multi-turn refinement, or "now do X based on what you just did".

How it works under the hood: codex exec --json prints a thread.started event carrying the session id directly (no snapshot/diff hack — cleaner than the agy route). On a continued call, codex exec resume <id> reuses it natively. Codex holds all session state on disk; this extension is otherwise stateless.

How it works

Pi (orchestrator)
  └─ AskCodex tool
       └─ spawn: codex exec --json [--model <m>] [-c model_reasoning_effort=...] [-C <cwd>] [-s <sandbox>] "<prompt>"
            └─ codex runs its OWN tool loop (read / write / edit / exec) inside <cwd>
            └─ stdout is a JSONL event stream; we parse it for status + the final agent message
       └─ returns codex's final answer text + sessionId (for follow-ups) + token usage

No ACP adapter, no app-server daemon, no acpx, no third-party binary. codex exec --json is a clean JSONL stream we parse directly. The extension is self-contained.

Structured progress

Unlike plain stdout capture, the extension parses the JSONL event stream and renders human-readable status lines while codex runs:

• running: npm test / verifying: pytest (verification commands labeled distinctly)
• editing: src/foo.ts, src/bar.ts (file changes, as they happen)
• searched: <query> (web searches)
• thinking: <reasoning summary> (when reasoning summaries are emitted)
• command completed: ... (exit 0) (per-tool results)

Transient error events (e.g. "Reconnecting... 1/5" during a dropped stream) are treated as non-fatal progress, not failure. Only turn.failed or a non-zero process exit surfaces as an error.

Model aliases

| User says | Resolves to | | --- | --- | | default | omit --model (Codex's own default, currently gpt-5.5) | | mini | gpt-5.4-mini (fast, cheap) | | full | gpt-5.5 | | gpt | gpt-5.5 | | gpt-5.4-mini / gpt-5.5 | exact passthrough |

Note: when authenticated with a ChatGPT account (the common case, including the free tier), only some models are available — others return 400: model is not supported when using Codex with a ChatGPT account. The alias set is intentionally small and points only at known-good names for that auth path. Use API-key auth (CODEX_API_KEY) to target other models, and pass the exact id.

Configuration

~/.pi/agent/ask-codex.json (global) merged over .pi/ask-codex.json (project):

{
  "defaultModel": "default",
  "defaultReasoning": "medium",
  "defaultSandbox": "workspace-write"
}

| Key | Default | Description | | --- | --- | --- | | defaultModel | default | Alias or exact id used when the tool call omits model. | | defaultReasoning | medium | Reasoning effort (minimal / low / medium / high) passed via -c model_reasoning_effort. Lower = faster and cheaper. | | defaultSandbox | workspace-write | Sandbox policy: read-only, workspace-write (default, needed for Codex to be useful), or danger-full-access. |

/codex command

Interactive picker for the default model, reasoning effort, and sandbox. If the project config (.pi/ask-codex.json) already defines a key, the change is written there so it actually takes effect; otherwise it writes to the global config. Outside TUI (RPC/headless), prints a read-only status snapshot.

Tool parameters

| Param | Required | Description | | --- | --- | --- | | prompt | yes | Self-contained task. Codex cannot see this conversation. | | model | no | Alias or exact id (see table above). Omit for the configured default. | | reasoningEffort | no | minimal / low / medium / high. Overrides the configured default. | | sandbox | no | read-only / workspace-write / danger-full-access. Overrides the configured default. | | sessionId | no | Omit for one-shot. Pass a prior call's details.sessionId to continue that conversation. | | cwd | no | Workspace path. Defaults to the current project root. | | timeoutMinutes | no | Hard cap in minutes. Default 10. |

Sandbox note (containers / restricted kernels)

Codex's default sandbox uses bubblewrap, which needs permission to create user namespaces. In some containers and hardened kernels you'll see:

bwrap: No permissions to create new namespace, likely because the kernel does not allow non-privileged user namespaces.

When that happens, Codex's own tool calls (file reads/writes, command execution) are blocked even though the run itself succeeds. Fixes:

• Run Pi in an environment that allows user namespaces, or
• Pass sandbox: "danger-full-access" per call (or set defaultSandbox to it) — appropriate when the outer environment is already sandboxed (a container, CI runner).

The extension's own process management (spawn, timeout, abort, JSONL parsing) is unaffected.

Environment variables

| Var | Default | Description | | --- | --- | --- | | CODEX_BIN | codex | Path to the codex binary. | | CODEX_EXTRA_ARGS | (empty) | Extra args appended to every codex exec invocation. Parsed with a shell-like splitter, so quoted values with spaces are preserved. |

License

MIT