Simplify Pi Codex to lightweight skills only

[yousecjoe]

Summary

Simplify pi-codex by removing the external Codex CLI/app-server runtime solution and keeping only lightweight Pi-native skills/guidance that use the active Pi model. The package should no longer spawn codex, manage broker sockets, track background Codex jobs, or require separate Codex CLI authentication.

Context

The current package was built around an out-of-band Codex CLI companion runtime. That made sense as a porting strategy, but it now overlaps with running Codex directly inside the Pi harness with gpt-5.5.

Observed problems with the current architecture:

• It creates a second Codex stack inside Pi: Pi model/tooling plus a separate codex CLI/app-server process.
• It requires separate Codex CLI auth even when the Pi harness itself is authenticated and working.
• A /codex:review run failed with a Codex CLI 401 Unauthorized because the external runtime had no bearer/basic auth, despite Pi itself being active.
• It ships substantial runtime machinery for broker sockets, lifecycle hooks, state files, background jobs, job result rendering, cancellation, and stop-gate behavior.
• The user intent is now simpler: keep lightweight skills/guidance and rely on the active Pi model instead of delegating to an external CLI process.

Current runtime-heavy surfaces to remove or replace include:

• extension/index.ts commands and codex_ask tool registration when they only support external CLI orchestration.
• scripts/codex-companion.mjs.
• scripts/app-server-broker.mjs.
• scripts/session-lifecycle-hook.mjs.
• scripts/stop-review-gate-hook.mjs.
• scripts/lib/app-server*.mjs / .d.ts.
• scripts/lib/broker-*.mjs.
• scripts/lib/codex.mjs.
• Runtime state/job-control/rendering code that exists only for external Codex jobs.
• Prompt templates that shell out to node "${PI_CODEX_ROOT}/scripts/codex-companion.mjs" ....
• Skills such as codex-cli-runtime that instruct the model to invoke the external runtime.

Decisions

• Treat this as a product simplification/refactor, not a bug fix.
• The maintained package should become Pi-native and lightweight.
• Do not require a local codex binary for normal package use.
• Do not require separate codex login, device auth, API-key auth, app-server readiness, or broker state.
• Prefer skills/guidance that help the active Pi model do review, adversarial review, prompt shaping, and delegation planning directly.
• Remove background-job and stop-gate features unless they can be reimplemented without the external Codex CLI runtime.
• Preserve useful review/delegation instructions where possible, but remove code paths whose primary job is to shell out to the external Codex companion.

Implementation Plan

1. Define the new lightweight surface

   • Decide which package assets remain after the simplification.
   • Expected retained assets are lightweight skills/guidance only, for example:
     • review guidance for the active Pi model,
     • adversarial review guidance,
     • rescue/delegation prompt-shaping guidance,
     • GPT/Codex prompting references that do not invoke external commands.
   • Remove or rewrite any skill that says to call node "${PI_CODEX_ROOT}/scripts/codex-companion.mjs" or the codex CLI.
   • Remove slash-command compatibility if it depends on the external runtime; document the replacement workflow clearly.

2. Remove the external runtime package surface

   • Delete scripts/codex-companion.mjs.
   • Delete scripts/app-server-broker.mjs.
   • Delete scripts/session-lifecycle-hook.mjs and scripts/stop-review-gate-hook.mjs if no extension runtime remains.
   • Delete runtime-only libraries under scripts/lib/ that exist for app-server/broker/job orchestration.
   • Delete tests that only validate external runtime behavior, or replace them with tests for the new lightweight skill/prompt content.

3. Simplify or remove the extension

   • If no runtime commands/tools remain, remove extension/index.ts and the pi.extensions entry from package.json.
   • Remove codex_ask if wait-vs-background prompting is no longer needed.
   • Remove /codex:setup, /codex:status, /codex:result, /codex:cancel, and /codex:gate if their purpose was external runtime management.
   • If any slash prompts remain, make them model-only instructions and ensure they do not shell out to Node scripts or Codex CLI.

4. Update package metadata and dependencies

   • Remove typebox if no extension tool schemas remain.
   • Remove @earendil-works/pi-coding-agent from devDependencies if no TypeScript extension remains.
   • Remove TypeScript scripts/configuration if no TypeScript source remains.
   • Update package.json pi metadata so it exposes only the retained lightweight assets.
   • Bump the version for the breaking simplification, e.g. 0.2.0-ys.

5. Update docs

   • Rewrite README.md around the new lightweight scope.
   • Remove local codex binary, codex login, app-server, broker, background job, and external runtime setup requirements.
   • Add a migration note explaining that the old external-runtime slash commands were removed because Pi already runs the active model.
   • Update CHANGELOG.md with the simplification and breaking changes.
   • Keep attribution in NOTICE as required, but avoid implying the current package still ships an external Codex CLI runtime solution.

6. Validation

   Run the remaining applicable checks after the simplification:

   npm install
   npm run typecheck   # if still present
   npm test            # if still present
   npm audit
   pi install /path/to/pi-codex
   pi list

   Also verify that no retained runtime/source assets instruct users or models to invoke the removed external runtime:

   rg -n 'codex-companion|app-server|app server|CODEX_COMPANION|BROKER|codex login|codex app-server|PI_CODEX_DATA|PI_CODEX_ROOT' \
     README.md CHANGELOG.md NOTICE package.json prompts skills extension scripts tests || true

Files Summary

File	Action	Purpose
package.json	Edit	Remove extension/runtime/dependencies that supported the external CLI solution; expose only lightweight Pi assets.
README.md	Rewrite	Document the current lightweight skills-only package behavior and remove external Codex CLI setup.
CHANGELOG.md	Update	Record the breaking simplification and migration notes.
NOTICE	Review/edit	Preserve required attribution without describing the current package as an external runtime wrapper.
extension/index.ts	Delete or rewrite	Remove external runtime commands/tools unless a Pi-native extension remains necessary.
prompts/**	Delete or rewrite	Remove shell-out prompt templates; keep only model-only prompts if still useful.
skills/**	Rewrite/prune	Keep lightweight skills; remove codex-cli-runtime or any skill that invokes the companion runtime.
scripts/**	Delete/prune	Remove Codex CLI/app-server/broker/job-state companion runtime code.
tests/**	Delete/rewrite	Replace external runtime tests with lightweight asset/content validation if needed.
tsconfig.json	Delete or update	Remove if TypeScript extension source is deleted.

Commit Sequence

1. refactor: remove external codex runtime

   • Remove companion runtime scripts, app-server/broker code, lifecycle hooks, job state, and runtime tests.
   • Remove or simplify extension commands tied to the external runtime.

2. docs: document lightweight pi-codex scope

   • Rewrite README and changelog for the new skills-only package.
   • Document migration from old slash commands to Pi-native skills/guidance.

Acceptance Criteria

• The package no longer requires a local codex binary for normal use.
• The package no longer instructs users to run codex login, codex login --device-auth, or codex login --with-api-key.
• No retained prompt or skill instructs the model to run node "${PI_CODEX_ROOT}/scripts/codex-companion.mjs" or invoke the external Codex CLI runtime.
• package.json no longer exposes extension commands whose purpose is external runtime setup/status/result/cancel/gate management.
• External runtime files are removed or no longer shipped: scripts/codex-companion.mjs, scripts/app-server-broker.mjs, app-server/broker libraries, lifecycle hooks, and runtime job-state management code.
• Lightweight skills/guidance remain available for Pi-native review/adversarial review/rescue workflows, or the README explicitly documents the replacement workflow.
• README.md is rewritten to match the current lightweight package state and does not advertise the removed external runtime solution.
• Dependencies used only by the old extension/runtime are removed from package.json.
• npm audit reports zero vulnerabilities.
• Remaining validation scripts pass, or removed scripts are intentionally deleted and documented.
• pi install /path/to/pi-codex succeeds and pi list shows the simplified package.

Out of Scope

• Building a new background job runner inside Pi.
• Reimplementing external Codex CLI auth or app-server orchestration.
• Preserving backward compatibility for every /codex:* slash command if those commands only existed to manage the external runtime.
• Publishing the package to npm.

Risks & Mitigations

• Risk: Removing slash commands may surprise users who installed the old runtime wrapper.
  Mitigation: Document the breaking change, replacement skills/workflows, and rationale in README.md and CHANGELOG.md.

• Risk: Removing scripts/tests too aggressively could delete useful review prompt logic.
  Mitigation: Preserve reusable review/adversarial review/rescue guidance in lightweight skills before deleting runtime code.

• Risk: Pi package discovery may expect certain prompt/extension metadata.
  Mitigation: Validate with pi install /path/to/pi-codex and pi list after simplifying package.json.

• Risk: Legal attribution could be accidentally removed while pruning upstream runtime references.
  Mitigation: Keep required attribution in NOTICE and LICENSE while making current package behavior clear.

Related Issues

• Related: Remove remaining Claude references from Pi Codex #2

[yousecjoe]

I uninstalled the plugin from Pi. The plugin and repo are redundant because Pi runs OpenAI Codex models, unlike Claude Code which runs Anthropic models only by default. This entire task can be reduced down to a very slim skill for any model and agent harness to perform code reviews. This is also what CodeRabbit does.