@thoth-agents/pi-askcodex

The AskCodex delegation tool for pi, backed by the user's local Codex harness through codex app-server --stdio. This is a tool, not a model provider: it adds no models to /model and works alongside your current Pi provider.

Codex runs its own tool loop with its sandbox, configured MCP servers, skills, plugins, and optional web search. It can use the user's real browser and native Windows apps through Codex Computer Use. This package does not modify ~/.codex/config.toml or Codex Desktop settings and has no codex exec/SDK fallback.

Install

pi install npm:@thoth-agents/pi-askcodex

Requires Pi >=0.99.0, Node >=22.19.0, and Codex Desktop installed with a working Codex login. Install this package manually; the Thoth installer does not manage it. AskCodex is enabled by default; set enabled: false to disable registration.

• Prefer the Desktop-bundled codex.exe, not a standalone CLI install.
• Native-app Computer Use requires Codex Desktop running.
• Browser Computer Use works without Desktop running, with the configured Codex browser extension in the user's Edge/Chrome browser.
• Codex follows its own bundled computer-use skill for Computer Use methods. AskCodex only adds delegation and approval notes to the developer instructions; it does not prescribe how Codex performs Computer Use. App access approvals are handled by the host or the user; if access is denied, Codex is instructed to report it and stop.
• Computer Use still requires the corresponding Codex tools/plugin and browser extension to be available. Installing AskCodex does not install those integrations.

Binary resolution

Resolution uses the first available source, in this order:

1. ASKCODEX_BIN, then the config file's bin: an explicit path to the native executable. An invalid explicit path fails rather than silently falling back.
2. On Windows, %LOCALAPPDATA%/OpenAI/Codex/bin/<hash>/codex.exe, choosing the executable with the newest modification time. If LOCALAPPDATA is absent, the resolver uses ~/AppData/Local.
3. codex.exe on Windows PATH, or codex on macOS/Linux PATH, with a warning about native Computer Use and read-only shell compatibility. Automatic Desktop-bundle discovery is Windows-only.

On Windows, .cmd/.bat shims are rejected: execution uses shell: false. Point ASKCODEX_BIN at a real codex.exe, for example in PowerShell:

$env:ASKCODEX_BIN = "$env:LOCALAPPDATA\OpenAI\Codex\bin\<hash>\codex.exe"

Explicit paths can become stale after Desktop updates; omit the override to use automatic discovery. The tool records the chosen binary and source in result details and performs a best-effort Desktop-running probe (unknown on non-Windows or probe failure).

Configuration

Global file: ~/.pi/agent/askcodex/config.json. There is no project-level config merge. Missing files use defaults; unreadable or malformed files warn and use defaults. Restart or reload the extension after changing configuration.

{
  "enabled": true,
  "defaultMode": "accept-edits",
  "defaultTimeoutMinutes": 15,
  "allowedApps": [],
  "webSearch": "disabled"
}

All supported keys and defaults, cross-checked against src/config.ts:

Only the four environment overrides listed above are supported. Per-call parameters override the corresponding configured defaults. Allowlisting is separate from the Codex shell sandbox; it does not grant command, file, or general permission approvals.

AskCodex tool

AskCodex is registered with model-only exposure; UI sessions also publish its tool definition through pi-core.

Give Codex a self-contained task, including relevant paths and constraints. For example:

{
  "prompt": "Review src/config.ts for validation gaps. Report evidence; do not edit files or operate apps.",
  "mode": "plan"
}

Parameters

Modes and sandbox limits

• plan selects Codex's read-only sandbox.
• accept-edits selects workspace-write and is the default.

Plan/read-only does NOT make MCP tools or Computer Use GUI actions read-only. Developer instructions forbid mutations in plan mode, including through MCP/GUI, but that instruction is not an enforcement boundary for those integrations. App access approval can authorize GUI actions even in plan mode. Use narrowly scoped prompts and approvals; do not treat plan mode as protection for external services or open documents.

Both modes use Codex's on-request approval policy with the user as reviewer. Approvals can authorize additional access; review each request rather than assuming the initial sandbox is the whole boundary.

Approval policy

• allowedApps covers only Computer Use app-access approvals, matching the whole requested tool_params.app identifier, not a display name. Matching is case-insensitive; entries are trimmed and empty entries ignored. * matches any sequence (including empty), ? matches exactly one character, and everything else is literal (no regular-expression syntax). Entries without wildcards remain exact matches: "notepad.exe" does not match notepad.exe.bak.
• For example, "msedge*" matches msedge.exe, not xmsedge.exe; "msedge_*" does not match msedge.exe. "?otepad.exe" matches notepad.exe. "*" matches any app identifier, including packaged-app ids.
• Matching apps are auto-accepted with session scope only, including without Pi UI.
• Other app requests, MCP elicitations, command/file approvals, and permission requests ask through Pi's UI. Without UI they are declined; cancelled, dismissed, or failed prompts also decline. Unknown server requests are rejected and reported.
• Computer Use offers session approval; other prompts offer once/session only as supported by the request. Persistent/"always" approval is never granted. Every decision is recorded in result details.approvals.
• Approval/server-request handling has its own 30-second deadline, independent of the overall timeoutMinutes cap; increasing that cap does not extend approval waits.

When @thoth-agents/pi-questions-user is installed and loaded in a UI session, approval prompts use the Thoth question UI through pi-core's shared question service. Each prompt is single-choice, with no recommended option or free-text answer. The preview shows the full command, working directory and Codex's reason when supplied, or the app display name and exact identifier for Computer Use. The existing allow/decline choices and approval policy are unchanged.

Without a compatible provider, or when its dock is unavailable, prompts fall back to Pi's native select dialog. Cancellation, abort, unexpected answers and prompt failures decline rather than opening another prompt; no-UI requests still decline unless covered by the app allowlist.

For Notepad, "notepad.exe" may not be sufficient: Codex may also request its packaged-app id, such as Microsoft.WindowsNotepad_8wekyb3d8bbwe!App. To allow both, add both observed identifiers or use ["notepad.exe", "Microsoft.WindowsNotepad_*"]. Requested identifiers are visible in details.approvals (the subject for Computer Use decisions). Start with an empty list and inspect them through an interactive Pi call.

Warning: "allowedApps": ["*"] lets unattended/no-UI calls control any app requested through Computer Use. Use narrow patterns unless that is intentional. Wildcard approvals are still session-only, never persistent/"always", and do not cover other approval kinds.

Results, continuation, and cancellation

The result contains the final Codex agent message and a conversationId footer. Details include thread/turn ids, status, model/effort/mode, elapsed time, binary source, desktop.running (true, false, or 'unknown' after the probe), warnings, approval decisions, token usage when reported, errors, and available plan/diff updates. Live cards show elapsed time, current activity, and recent agent text.

Continue the same Codex thread with a self-contained follow-up:

{
  "prompt": "Recheck the validation gap you found; report only new evidence and do not edit.",
  "mode": "plan",
  "conversationId": "<id returned by AskCodex>"
}

Threads are non-ephemeral, stored by Codex under ~/.codex/sessions, and may appear in Codex Desktop history. Continuation survives the app-server process ending; it is not an isolated or disposable conversation. includeContext is opt-in because exporting Pi history shares it with Codex; deleting the temporary file does not remove text already read into the Codex thread.

Pi cancellation or timeout sends turn/interrupt when thread/turn ids are known, waits briefly (up to 1.5 seconds), then closes the client and terminates its owned process tree (on Windows, only the leader if the Job Object launcher is unavailable). The result reports interruption and whether it timed out or was aborted. Cancellation does not roll back completed file edits or GUI actions.

Compatibility and risks

• codex app-server is experimental. The implementation targets the verified Desktop-bundled 0.162.0-alpha.17.2 protocol, not a guarantee of future compatibility.
• Desktop-bundled binaries are version-volatile/alpha and may change with Desktop updates. Automatic discovery follows the newest executable, not a pinned version.
• Failed handshakes, RPC errors, and process failures fail the call. Malformed or oversized output lines are discarded; unknown server requests are rejected rather than auto-approved. There is no CLI/SDK fallback.
• On Windows, the standalone PATH codex has produced blank native-app screenshots, missing typing, and read-only shell sandbox errors (helper_unknown_error: setup refresh had errors, including ACL errors). Prefer the Desktop bundle; having Desktop running alone does not fix an incompatible CLI binary.
• Codex loads the user's existing MCP/skills/plugins configuration. Delegated actions can affect real services, browser sessions, and documents; review that configuration and keep app approvals narrow.

Troubleshooting

Development

From the repository root:

pnpm --filter @thoth-agents/pi-askcodex typecheck
pnpm --filter @thoth-agents/pi-askcodex test
pnpm --filter @thoth-agents/pi-askcodex build

Offline tests use a fake app-server; they do not launch Codex Desktop or perform real Computer Use.