pi-codex-app-server

A Pi package that implements a Codex app-server compatible JSON-RPC backend without requiring the OpenAI codex binary.

The package provides:

• pi-codex-app-server, a standalone app-server process.
• codex, a compatibility shim that supports codex app-server ....
• Pi package resources: extension commands, a skill, and a prompt template.
• Persistent threads/turns backed by local JSON files.
• turn/start execution through pi --print --no-session --mode text.

Install

pi install ./pi-codex-app-server-c

For CLI shims through npm-style linking:

npm install
npm link

Drop-In Usage

There are two ways to run the backend.

Direct Binary

Use this when you do not want a codex shim at all:

pi-codex-app-server --listen stdio://

Workflow form:

command: pi-codex-app-server
args:
  - --listen
  - stdio://

One-line workflow form:

command: pi-codex-app-server --listen stdio://

Codex-Compatible Shim

Use this only when an existing client insists on invoking codex app-server:

codex app-server --listen stdio://

The shim also accepts Codex-style global flags before app-server, so this existing workflow command works:

command: codex --config shell_environment_policy.inherit=all app-server

That --config shell_environment_policy.inherit=all flag is ignored by this Pi backend. Child commands and Pi turns inherit the app-server process environment by default.

Supported listeners:

• stdio://
• ws://IP:PORT
• unix://PATH
• off

Migrating Existing Workflows

If your workflow currently says:

command: codex --config shell_environment_policy.inherit=all app-server

Prefer changing it to the direct backend:

command: pi-codex-app-server
args:
  - --listen
  - stdio://

If the workflow cannot be changed and must call codex, install/link this package so its codex binary appears earlier in PATH than any OpenAI Codex CLI:

npm install
npm link

Verify resolution:

where codex
codex --config shell_environment_policy.inherit=all app-server --help

On Unix-like shells, use which codex instead of where codex.

Pi Backend

turn/start runs Pi directly:

pi --print --no-session --mode text "<prompt>"

Model routing:

set PI_CODEX_APP_SERVER_MODEL=openai/gpt-4o
pi-codex-app-server --listen stdio://

Extra Pi arguments:

set PI_CODEX_APP_SERVER_ARGS=["--provider","openai"]

Workflow env example:

env:
  PI_CODEX_APP_SERVER_MODEL: openai/gpt-4o
  PI_CODEX_APP_SERVER_ARGS: '["--provider","openai"]'

Advanced test/custom runner:

set PI_CODEX_APP_SERVER_RUNNER=node
set PI_CODEX_APP_SERVER_RUNNER_ARGS=["D:\\path\\to\\runner.js"]

When PI_CODEX_APP_SERVER_RUNNER is set, turn/start calls that executable instead of pi. The prompt is appended as the last argument.

Implemented Protocol Surface

Implemented directly:

• initialize, initialized
• thread lifecycle: start, resume/read, fork, list, archive, unarchive, name, goal, turns, rollback
• turns: start, steer, interrupt, review start
• command and process execution
• filesystem read/write/list/metadata/copy/remove/watch
• model list, config read/write stubs
• common skills, hooks, app, plugin, marketplace, MCP, account, remote-control, and feature-list compatibility responses

Unsupported Codex-specific cloud or marketplace actions return empty compatible responses where practical. Unknown methods return JSON-RPC -32601.

Storage

Thread data is stored at:

%USERPROFILE%\.pi\codex-app-server

Override it with:

set PI_CODEX_APP_SERVER_HOME=D:\path\to\state

Workflow env example:

env:
  PI_CODEX_APP_SERVER_HOME: D:\path\to\pi-codex-state

Ephemeral threads are kept in memory for the lifetime of the server process and are not written to this directory.

Environment Variables

Variable	Purpose
PI_CODEX_APP_SERVER_HOME	Thread/config storage directory. Defaults to ~/.pi/codex-app-server.
PI_CODEX_APP_SERVER_PI	Pi executable used for turn/start. Defaults to pi.
PI_CODEX_APP_SERVER_MODEL	Model passed to pi --model and listed as the default model.
PI_CODEX_APP_SERVER_MODELS	Comma-separated model catalog returned by model/list.
PI_CODEX_APP_SERVER_ARGS	JSON array of extra args passed to pi before the prompt.
PI_CODEX_APP_SERVER_RUNNER	Replace pi with a custom executable for turn/start.
PI_CODEX_APP_SERVER_RUNNER_ARGS	JSON array of args passed to the custom runner before the prompt.

Verification

npm test
npm run smoke