Add a perch-cli provider that runs the official Perch CLI, like claude-cli #7306

Area

Provider adapters

What are you trying to accomplish?

I use Codex (both the CLI and the desktop app) through OpenCodex and also have a Perch account. I want Perch as a provider in OpenCodex, so its hosted models show up in the Codex model picker and can drive normal Codex turns. Like claude-cli, the models should call Codex's own tools (exec, file edits, MCP tools) while Codex keeps control of approvals and sandboxing.

My account is on Perch's free Starter plan, so I wired up the Starter models first:

• Roost standard (200K)
• Roost standard-max (1M)
• DeepSeek V4.1 Flash

Nothing in the adapter is specific to these three. Pro models and reasoning-effort settings can go on the same provider entry once someone with a Pro account can test them.

What prevents this today?

Perch doesn't offer an API on consumer plans. Its models are only reachable through Perch's own web, desktop and CLI clients (npm i -g perchai-cli). OpenCodex has no adapter for it, so the only option today is running Perch's CLI in a separate terminal next to Codex, without Codex's tool loop or session history.

What should OpenCodex do?

Add a perch-cli preset that runs the official perch CLI headlessly, once per turn, following the same design as claude-cli:

• Tool calls go through Codex. Perch's models receive Codex's tool catalog and can make single, parallel or multi-step tool calls. When Perch requests tool calls, the turn ends and the calls go back to Codex, which approves and runs them and sends the results in the next turn. If the model calls one of Perch's built-in tools instead, the adapter retries once with a correction and fails with an explicit error if it happens again.
• No credentials in OpenCodex. Sign-in stays in the CLI (perch login); OpenCodex never stores or forwards Perch credentials.
• Isolated turns. Each turn runs in an isolated environment, so the user's local Perch config, MCP servers, skills and account memories don't leak into Codex sessions.
• Streaming and errors. Text and reasoning stream live as Perch produces them. Failures map to the usual status codes: 401 when not signed in, 429 on usage limits, a retryable 503 when Perch is unreachable.
• Images. The models on this path are text-only, so image inputs go through the vision sidecar first.

Example usage or interface

{
  "providers": {
    "perch-cli": { "adapter": "perch-cli", "baseUrl": "https://app.perchai.app" }
  }
}

Then select perch-cli/roost-standard, perch-cli/roost-standard-max or perch-cli/deepseek-flash-starter in Codex.

This already works on a branch off current dev (a single commit, ready to open as a PR). I tested it on Windows 11 with perchai-cli 2.4.109 on a Starter account:

• Real Codex tasks on all three Starter models, including multi-step exec and file-edit tool loops, and an image question answered through the vision sidecar.
• First output in about 7.5 s once warm (about 12 s on the first turn after a proxy restart), with Codex's full prompt as input.
• All local checks pass: the adapter's tests (offline, no Perch install needed), typecheck, structure:check, privacy:scan, the registry/layout/docs-count guards, and the docs build.
• Not tested on Linux or macOS. On macOS the CLI keeps credentials in the Keychain unless PERCH_CLI_AUTH_DIR is set, so the adapter expects a file-based sign-in there for now.

Alternatives or workarounds

• Running perch by hand outside Codex. It can't share Codex's tools or conversation state.
• Letting Perch execute tools itself ("delegate" mode). I ruled this out for the same reason claude-cli does: Codex would lose ownership of tool execution and the sandbox.
• Calling Perch's private HTTP endpoints directly. Perch's terms restrict those endpoints to its own clients, and imitating the client goes against how claude-cli is built. Running the official CLI avoids that.

Additional context

Going from a first proof of concept to something usable for daily Codex work took a few iterations. Most of the work went into working around how perch run handles MCP tools, startup and prompts.

Tools invisible on the 200K tier. At first, roost-standard never saw the client tools. Once MCP tool schemas pass 10% of the context limit, Perch hides them behind its own loadMcpTools step. Codex's exec schema alone is about 50 KB, so 12 of my first 13 failed turns ended in tool_bridge_init_missing. When the catalog gets close to that threshold, the adapter now cuts each tool to a one-line description and moves the full descriptions into the instructions. I haven't seen the failure since.

Capturing tool calls without killing the CLI. The bridge's MCP server declares no tool annotations, so Perch treats every Codex tool as a write. It reports the whole parallel batch as tool_call_requested and exits cleanly with approval_required on its own; nothing is killed mid-turn.

Keeping the model off Perch's built-in tools. Perch has no flag that disables its built-ins while keeping MCP. Restating the real working directory and the tool rule in the argv prompt took built-in calls on a real Codex task from 2 of 3 runs to 0 of 3. If the model still calls a built-in before any output has streamed, the adapter reruns the turn once with a correction naming the right client tools, and fails closed if that doesn't work either.

First token: about 20 s → about 7.5 s. Most of this comes from a small --import preload loaded into the CLI's Node process:

• The CLI uploads the transcript at the end of every turn, which held the result back for 1.5–12 s. The preload answers those uploads locally.
• The preload caches three startup requests: the public default model, cli-context and account. The two account-specific entries are keyed by a hash of the sign-in, so the token itself is never written to disk.

Outside the preload, the adapter:

• turns off Perch's seeded CourtListener MCP server, which otherwise starts npx and adds about 4 s;
• disables the built-in skills, saving about 1.7K tokens per request;
• runs the CLI's Node entry point directly. That skips Perch's heap re-exec and the Windows .cmd shim, which also cut argv at the first newline.

Streaming. perch run --json prints a single JSON document on exit. The preload copies model-call deltas to an extra pipe, so text and reasoning stream as they arrive. The adapter tracks how much of each model call already went out and only sends the rest from the final document, so a tail is never dropped or sent twice.

Passing the conversation. perch run only takes its prompt from argv, so the conversation goes through Perch's project instruction files: .perch/PERCH.md plus up to 40 rule files of 64 KB each.

• History is capped by bytes, using the conversation's own bytes-per-character ratio (CJK text takes about 3 bytes per character). The current turn's input is never cut.
• Perch reads rule files in raw readdir order, so each file carries an explicit part number.
• If Perch compacts those files during a run, the adapter fails closed instead of letting the model answer from a cut conversation.

Isolation. Every turn gets a fresh --thread ID; otherwise Perch derives the thread from the working directory and replays its own past turns. The CLI also runs with an empty staging home directory, so the user's local Perch config stays out.

Retries and lifecycle:

• One of Perch's startup requests occasionally times out. The run then has no turn ticket and fails with "model is busy". That case, along with provider_transport and turn_preparation_stalled failures, is retried once through the shared send budget (transient send class), but only if nothing has streamed yet. Perch's own error codes, such as quota or context limits, take precedence and are never retried.
• Token usage is summed across attempts and reported on whatever ends the turn, errors included.
• An abort returns 499, also between attempts.
• Runs stopped by max_iterations or turn_incomplete are marked as truncated, so Codex doesn't treat a partial answer as complete.
• On Windows the CLI's process tree is cleaned up with the shared runner's helper.
• Error messages are stripped of bearer tokens, JWTs and token fields.

Known limitations (also in the docs):

• Perch always prepends its own operator persona, and the CLI can't replace it. Codex's instructions come right after it and win out for tool use, but the model occasionally still introduces itself by Perch's persona name.
• Each request carries about 22K tokens of Perch's own system prompt and built-in tool schemas.
• Perch's built-in read tools (web search, web fetch) can run inside Perch before the adapter sees the call, so they bypass the client's network sandbox.
• Conversation history has to fit in those 40 rule files, so the 1M-context models are advertised at 512K and Codex compacts before hitting the cap.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.