@pi-switch/pi-codex-app-server0.2.1

Pi Codex App Server

Use the same Pi session from the Pi terminal and Codex clients. Pi executes the work; this bridge exposes history, live events, models, and host operations through the Codex app-server protocol.

This is the AdamsGH fork of Lqm1/pi-codex-app-server. Its npm package is @pi-switch/pi-codex-app-server. The executable remains pi-codex-app-server. The unscoped npm package belongs to upstream and does not install this fork.

Pi remembers a code, Codex CLI resumes the same session and recalls it, and a final reply from Pi appears in both clients. Recorded with Pi 1.2.0 and Codex CLI 0.162.1. See the recording instructions to reproduce it.

Differences from upstream

The comparison below uses upstream commit 81f9d1b as the fork baseline.

The stdio/WebSocket transports, ChatGPT Remote Control, Pi-owned authentication, model catalog, and history projection originate in upstream. This fork extends those foundations.

The native desktop adapter uses a private, version-sensitive host-tools interface. Automatic sidebar membership and ordering passed a live acceptance check. Visible streaming, failed-tool rendering, and final spinner behavior still require visual acceptance; passing protocol tests does not certify them.

Capabilities and limits

• Codex CLI and desktop attach to a native Pi TUI session. Input, replies, reasoning, and tool events share one writer and one history.
• The footer shows codex: connected when the session bridge is attached and the daemon is running. Connection details remain available through /codex-server status.
• If a native Pi window cannot acquire the session lease, it stays usable without app-server attachment. The footer shows codex: disconnected (session in use) or codex: disconnected (bridge unavailable). Run /reload to retry attachment. Disconnected windows use native Pi behavior; the app-server does not coordinate their history writes with the attached owner.
• The daemon survives client disconnects and Pi extension reloads. Reconnecting clients recover history and active-turn items.
• ChatGPT Remote Control uses Pi's OpenAI OAuth credentials.
• Publication settings control exposed history. Repository roots become projects; unassigned sessions use the Pi section.
• A separate desktop adapter adds newly published unassigned chats through native host tools, preserving explicit section and pinned placements.
• Requests use a pinned protocol snapshot. Unsupported operations fail explicitly.

Pi's execution permissions apply. Codex sandbox and approval settings do not create a sandbox around Pi. Archiving preserves history; thread/delete permanently deletes the Pi JSONL file. No skill collection is installed by this package.

Compatibility

Windows is the verified desktop target. Linux CI checks core protocol and packaging, not desktop or Remote Control UI. Other desktop platforms require an explicit native endpoint and have not passed live acceptance here. Native host tools are a private, version-sensitive interface. Visible streaming and completed-turn rendering remain separate acceptance checks.

Install and connect

The scoped npm command becomes available after the first fork release:

pi install npm:@pi-switch/pi-codex-app-server

Until then, build a checkout and install it as a local Pi package:

bun install --frozen-lockfile
bun run build
pi install /absolute/path/to/pi-codex-app-server

Use Bun 1.4.3 for installation. If system Bun cannot read bun.lock, use npm exec --yes --package=bun@1.4.3 -- bun install --frozen-lockfile. Do not regenerate the lockfile with an older Bun.

Open Pi. After updating an existing installation, run /reload when idle. Then run /codex-server status and copy its codex --remote <URL> resume <Pi-session-ID> command into another pane. Resume the same session ID; a fork is a different conversation.

For desktop or ChatGPT connected-host access, follow the user guide. The live desktop adapter and offline project importer serve different purposes. The importer requires desktop to be closed.

Documentation

• User guide: installation, connections, configuration, updates, troubleshooting, and removal.
• Architecture: processes, ownership, authentication, storage, and recovery.
• Development: setup, checks, migrations, protocol updates, package verification, and release preparation.
• Session publication: history visibility settings.
• Sidebar integration: native synchronization and offline import.
• Architecture decisions: retained decisions and their current status.

Repository layout

drizzle/ is required at runtime. vendor/ is intentionally committed and updated with bun run protocol:sync; it is not continuously mirrored. UPSTREAM.md describes the update contract.

The project uses Apache-2.0. See NOTICE for provenance and CHANGELOG.md for fork changes and retained upstream history.